Under the Hood

How does H3Mod work?

H3Mod does not "understand" firmware. There is no decompiler, there is no code parsing. Instead, it takes everything you throw at it and assumes that it is a bunch of pictures, you only have to tell it where exactly they start. That's the basics. In addition, there is some hardcoded information for some firmwares, like on their encryption and the images they contain. Let's have a look at what happens under the hood when you theme H320 firmware.

Loading the firmware

So, to start with, let's just load the firmware as we downloaded it from iriver. It looks like this: Hmm, not very useful, is it? The reason is that it is encrypted. Now, there are clever people out there, like Mr. stripwax, who can look at that kind of noise and find out how to turn it into readable code. Beats me how they do it, but they can. So I can move on to the next step, decrypting the file.

Decryption
By writing code based on the information from helpful crackers, I can apply some black magic on the complete gibberish we see above, and lo and behold! We can see two images! The rest still looks like gibberish, but it's more structured gibberish, the kind a processor chip can actualy understand. Ignore the little number for now, it'll have its moment of fame with the encryption.

Automatically locating images

Now you could start replacing images already: move around in the firmware, mark where an image starts, how big it is, what colour enoding it uses, etc. All this information on one picture is called a bookmark, remember the term. Then you can load a new image and copy it in the same place as the old one. Sounds time consuming, doesn't it? And what's worse, if you have written down all the positions etc, and happily want to apply them to the next firmware upgrade, forget it. Everything is different, like this: Firmware version 1.20   Firmware version 1.21       To spare you all the searching, members of the misticriver community (including myself) have done it and compiled a table. And here comes the trick how this table still works in the upgrades: With H3Mod, you always need to download a reference file for known firmware. This is essentially an old version of the firmware, with possibly added pictures from later versions. Looks pretty much like the picture on the left. The internal bookmark table refers to this reference file. H3Mod takes a bookmark, reads the data (that is, an image) from the reference, and then starts searching the exact same bit of code (that is, the same image) in the upgraded firmware. There are some gritty details that make it more difficult in reality, but that's the basic procedure. If successful, it creates a new bookmark internally. This is what you see when you open firmware in H3Mod and look at the Current Bookmark box.

Loading a Theme

Themeing firmware is not too difficult with the internal list of bookmarks that was just created. All that H3Mod needs to do is: Load a new picture file. This can just be a gif file in a directory, or it comes from a h3theme file (basically a zipped version of the directory). As a service for the user, verify if size and number of colours are what they should be. This is where the occasional warning for a theme comes from. Convert the image into the internal format of the firmware. This can be quite nasty, especially when colour palettes are involved; but it's enough to know they are translated from a language the PC understands into a language that the H320 understands. Copy the converted picture to the same place as the old one. OK, we did all this, and arrive here. Looks perfect, doesn't it?

Encrypting the firmware again

Since the original firmware was a heap of colourful noise, we need to turn it back into noise again. Or in other words, encrypt it. To do this, I simply use the same black magic as for the decryption, only I say Abracadabra backwards. If you have a close look, this is different from the original noise, which it should be since the images changed. So there. Images changed, encrypted to original form. In addition, H3Mod verifies that really only the images have changed and not some other bits that might be important code. Upgrade the player, and, hooray...wait a minute... the player doesn't accept the new firmware. Or in very unlucky cases turns into a brick. Most models will just tell you "Nope, that's not proper firmware", but some may load it anyway and choke to death... What is the reason? It's checksums. Read all about them in the next box.

Checksums

The original coders of the firmware seem to have foreseen that we may want to hack it. So they fiendishly introduced mechanisms that tell them if anybody modded the firmware. Remember the little number in the lower left? That's a checksum. Before an upgrade, the H320 calculates this number. You can say, it uses some fancy mathematics to add pictures. Like this:   +     =   2674   +     =   7298 See something? Look at the modified firmware above: the little number says 2674. The player expects 7298, and therefore cannot handle the firmware. You can't see it in the encrypted mayhem, but our little 2674 is still in there. And that's the end of the little number's fame, because H3Mod also can add images! It does so, and writes a new little number to the firmware: 7298. Again, it's really more complex than that, but you get the idea:       gets encrypted to ->    This version is then encrypted. I spare you another screenshot of noise with just 2 different pixels, just pick two of your choice and imagine they were different. And that version, finally, is the new firmware that the H320 happily loads and displays, and you can show to iPod users and say "Can you do THIS?"

Possible problems

I hear you say now "But LJ, that is SOOOO easy, how comes I still can't theme my H10, U3, clix, iPod etc. etc.?". Well there are many pitfalls, and I'm amazed we got that far at all. Getting firmware: for many players you never see a firmware file. Instead you have to connect the player, go online and run upgrading software. That directly pumps the upgrade from a secret website to your player. Never any file we can change. Sometimes firmware appears on the web, because people found the secret website, or found the firmware file on their player. But it makes it more difficult to know what even is a firmware file. Encryption: That's a big one. Most firmware is encrypted and I have no clue at all how to decrypt it. We all depend on crackers who spend (reputedly) long nights with IRC, cigarettes and coke to find the right spells to decrypt it, and then publish their wisdom. Checksums: They can ruin it completely just when you think you got it. X5 firmware for example is not encrypted. The pictures are there for everyone to change. But it always rejected the modded firmwares until somebody found out: it has a checksum. Exactly one number, as in the example above, but if that one number is wrong, the modded firmware could as well be a lump of Jell-O, as far as the X5 upgrade software cares. Again, the magicians need to read the code and find out about this. Image formats: An image is just lots of pixels, and each pixel has a colour, which is stored as a number. Right? Wrong. There are countless ways of messing around with the order of the numbers, and how many numbers per pixel, and if the colour is stored with the pixel or somewhere completely different, or if several images share the same colours, or... you get the idea. And software seems to take pride in using all of them and add a few new ones from time to time. The T10, for example, has at least four different ways of storing fonts. And that's just the black and white format, there's several more formats for the coloured images. Any new firmware is likely to have different ideas again.