Hacking the PipBoy 3000 Mk V Bootloader

Ever since getting my hands on the PipBoy 3000 Mk V one of the main things I wanted to achieve was to make it easier for other people to be able to modify them, initially that started out with creating this series of articles as a deep dive into the inner workings of the device and then off the back of that I started to create a more simplified set of User Documentation containing the more relevant information. Since creating that page though, it’s become by far the most viewed and useful section of this website to most people that want to mod their PipBoy’s, not everybody as it turns out cares so much about the PCB design or the inner workings of the firmware.

It has been a few weeks since I had a deeper dive into my PipBoy 3000 Mk V but I’ve been reinvigorated into looking into it some more after meeting a few more community members and talking about some software modding options. Most of the questions I’ve been asked in the past couple of months have been the same sort of things, people want to change the UI colour, make their own radio stations or override features that already exist. I recently connected with CodyTolene after coming across the wonderfuly useful utility of his website pip-boy.com and we worked together on adding some tools for helping people get their own apps onto their PipBoy’s without needing to pry the thing open and remove the SD cards, which I think is a great step in helping people do this sort of customisation.

One thing has been bugging me though, so far I’ve been ableto modify all different parts of the system, but nothing that really persists, user apps in the /APPS directory are just one shot scripts, and any overrides to the default functionality will reset when the system resets. To do any deeper modification we need to get into the boot process and have something that can persist.

Hooking the boot process

Reading the documentation about how Espruino loads code at boot time, the boot process (simplified somewhat) is as follows:

• Unpack the firmware image into RAM
• Check flash for files named .boot0 .boot1 etc. and executes the content in order
• Check flash for a file named .bootrst and execute
• Check flash for file named .bootcde and execute (if previous step wasn’t found)
• Init peripherals
• Execute any handlers registered as E.on('init', function() {...})
• If there is a function named onInit() execute that

Outside of the “standard” Espruino boot process, there is also some boot code specific to the PipBoy that handles things like firmware updates from the SD card, recovery, display setup and so on.

We need to get into the boot process somewhere but ideally we want to invoke any of our user customisations as late as possible in this process to avoid breaking anything. Looking at the previous process that will mean either an E.on('init') event handler or defining an onInit function. The Espruino documentation for E.init states that:

Subsequent calls to E.on(‘init’, will *add a new handler, rather than replacing the last one. This allows you to write modular code - something that was not possible with onInit.

This sounds like exactly what we want in order to avoid breaking any existing handlers. But we need to also create that handler:

Modifying the flash

To create our init event handler, we need to create something that will persist, which will mean adding something to either the SD storage or the flash. Looking at our previous boot order though there’s no real interaction with the SD card at this stage so we will have to modify the flash.

The .bootrst and .bootcde files in flash are already used by the PipBoy firmware so we shouldn’t interface with those, but the .boot0, .boot1 etc. files don’t exist on the flash, and I don’t see any reference to them anywhere in the firmware either. Besides, if something were to use .boot0 for example, we could just use .boot1 or .boot2 etc. and avoid issues, hopefully.

The goal now is to create some code in the flash at .boot0, this code will execute and create an E.on('init') event handler which will then later be called at the end of the boot procedure. So time to test this theory.

Proof of concept

My proof of concept was to run the following command, this creates the .boot0 file in flash, the file creates an on init event handler which then adds the parameter test to the Pip class. This should prove that we can extend or override the default code.

require("Storage").write(
  ".boot0",
  'E.on("init", function() { Pip.test = 123 })'
)

Once writing this file I hard rebooted the PipBoy to make sure it was definitely fully off, powered it back up and then connected to see if my modification sticks, and it does!

>Pip.test
=123

Running user code at startup

Now my proof of concept has proven the theory is sound, I wanted to take this a step further. Ideally any user customisations after this point would not need to write anything to flash, both to save flash space and also just for safety. Instead it would be nice to have user customisations loaded from the SD card, so to do this we now need to add one more step to the boot process, the process will now look something like:

• Load the .boot0 file from flash which creates an E.on('init') event handler
• E.on('init') event handler runs which will now check the SD card for any boot scripts
• Execute all boot scripts in order from the SD card

The init event handler now looks like this:

E.on("init", function () {
  require("fs")
    .readdir("USER_BOOT")
    .forEach(function (f) {
      if (f.endsWith(".js")) {
        eval(require("fs").readFile(`USER_BOOT/${f}`))
      }
    })
})

This event handler will list all .js files from the directory USER_BOOT on the SD card and then invoke them. I opted to use the directory USER_BOOT on the SD card, there is already a directory named BOOT for boot videos and such, and there is already USER for user scripts and I did not want to invoke those.

Putting it all together

Now all that was left was to create a user customisation and see if it all works. The below code creates a new file on the SD card USER_BOOT/ui_color.js, and now when I reboot the device, the UI theme is orange.

require("fs").mkdir("USER_BOOT")
require("fs").writeFile(
  "USER_BOOT/ui_color.js",
  "for(var pal=[new Uint16Array(16),new Uint16Array(16),new Uint16Array(16),new Uint16Array(16),],i=0;i<16;i++)pal[0][i]=g.toColor(i/15,i/30,0),pal[1][i]=g.toColor(i/30,i/60,0),pal[2][i]=g.toColor(i/10,i/20,0),pal[3][i]=g.toColor(i/20,i/40,0);Pip.setPalette(pal);"
)