X16 (ROM) UPGRADE Utility

The Commander X16 is still actively evolving. As the community finds issues or comes up with new ideas, new ROMs updates are made available. However, ever since around R46, a lot more emphasis has been placed on retaining backwards compatibility (i.e. software built around R45/R46 era should continue to be compatible with and run for newer releases of the ROM firmware — they might take advantage of new features, but they should still RUN and be functional). For the most part, the gatekeepers of the X16 ROMs have firmly held to this (via lengthy debate and discussion on the merits of any changes, especially as they navigate upcoming 65C816 support).

The X16 consists of three upgradable firmware modules: The VERA itself has firmware software, the KERNAL+BASIC are in the System ROM (often just called the “ROM”), and then the SMC is a core external hardware interface (mainly keyboard and mouse) that has its own firmware. Generally it is not necessary to update the SMC, and you can update the System ROM or VERA on their own. But since the process of updating ROMs involves taking the case cover off and flipping jumpers, people generally feel more comfortable just updating the whole system at once, and using a “verified compatible” set of firmware binaries. This is also good to help ensure everyone is “on the same page” in terms of what ROMs are being used – so when providing support, we don’t have to wonder if issues are related to unknown differences due to mix-match of firmware.

So, for these reasons, the upgrade process has evolved over time, and there are several options that cater to different situations.

OPTION 1: The “original” standalone VERA, ROM, SMC update utilities. These were made available on the SD-card that was included on the original “100” X16 DEV boards from June 2023. They still work, each updates just one aspect of the system. But the SMC updater here isn’t aware of the possible bootloader issue. These utilities were later placed in the \EXPLORE\SYSTEM folder of the SD-card for the X16 PR boards. I still use the VERA and ROM updater of this for loading in custom or experimental builds of those ROMs. (on later SD images, the EXPLORE file got re-arranged slightly, but these updaters are still there)

OPTION 2: The “first” all-in-one updater. This had good intentions of making the update process easy, but forces going through the steps of updating all 3 ROMs (and retains the flaw of the original SMC update, of not being aware of the possible bootloader issue). This option does still work well, if you don’t have the bootloader issue (basically units past PR500 are probably fine, but there isn’t a sure guarantee, such as for Otter16 systems). This option may require figuring out the filenames that updater requires.

OPTION 3: The nitty-gritty details and “official” ROM upgrade instructions are at the Commander X16 Technical Reference github repository. This is located here. That is, from the main “X16Community” github repo, go to x16-docs, and currently Appendix H Onboard Upgrade Guide. This is the “official” source in that core X16 dev team will be maintaining and updating this page as things evolve over time. The instructions here are more similar to Option 1. Basically the ROM releases themselves tend to be packaged with some software used to flash them. This can still be a bit overwhelming for many people (not a simple step 1, 2, 3 sequence), but it is the most comprehensive and maintained info on the topic of updating the CMDR X16.

OPTION 4: Stephan’s “second” all-in-one “unofficial” updater, the X16UPGRADE utility. Now having understood the bootloader issue, this version will detect if you have this issue and provides instructions accordingly. In addition, a goal was to have a way to have “certified compatible” sets of ROMs (compatible with each other) all packaged together. The prior update tools used fixed filenames for whatever ROM file it was going to flash. So this option uses a “PKG” file, where all three ROMs are packaged into a single file (using Python scripts to package this up). This option isn’t as convenient for custom or experimental ROMs, but for general users it is probably the most convenient “follow these steps” option.

stefan-b-jakobsson/x16-upgrade

REPO of PKG files (at github, at the top right is “…” icon, click that to get the Download option)

R48 PKG: X16_MANUALS/LAUNCH_SD_CONTENT/X16-R48-ROM-X1.PKG at main · voidstar78/X16_MANUALS

R49 PKG: X16_MANUALS/LAUNCH_SD_CONTENT/X16-R49-ROM-X1.PKG at main · voidstar78/X16_MANUALS

Here is an example reference of the steps I went through in using the X16 UPGRADE utility. A visualization of the screenshots is further below, but to summarize the main highlights:

Write down or remember the name of your ROM PKG file
LOAD “X16UPGRADE.PRG” (do this from the root folder of the SD-card, not a sub-folder)
RUN it
Type in the filename (with the extension) of the ROM PKG file. I do this in whatever the default startup settings of the system is (i.e. lower case). Do include the .pkg extension if you have it (but you could rename it to .bin or have no extension at all, depending on who prepared the package)
On the “PACKAGE INFORMATION” use arrow keys over to “NEXT” option.
If you need some help, there is an F1 assistance to help show approximately where the jumpers are. On modern hardware we take firmware updates for granted (like for our Router or Camera security systems). But for the X16, it is a bit more “hands on” process
When asked to hold “power and reset” you can use the buttons that are right on the board itself (even if the external switches are connected).
Don’t panic if you don’t react fast enough if “power and reset” switch aren’t pressed by the end of the timer. It will pause and restart the countdown if you do end up needing more time to get situated to press those buttons.
The system will shutdown at the end of the process (not a restart), so you’ll need to manually power it back on.
REMEMBER to place the VERA jumper back on in place. Many of us have forgotten to do this, and so the system won’t boot up until you do this.
Unlike the VERA, the System ROM can operate with its jumper on or off. You can run the system full time with the jumper on, but there is technically a risk then that any piece of software could then update your System ROM without consent. For this reason, it is best to run the system with the System ROM jumper off (or offset by one pin), to put it in a “read-only” mode until you are ready for the next update. Of course, if updating often or experimenting with alternate ROMs, then leaving it on is fine during that testing.