supl : Supperware Uploader

Every Supperware-made USB MIDI device has a bootloader. It enables firmware versions to be checked, and firmware to be updated, without taking out screws or fiddling with hardware. All these devices use the same system.

Firmware is encrypted using TEA (a unique key is used for every project) so it’s inscrutable when it’s distributed as a file. Underneath it all, we use a standard MIDI 1.0 file transfer protocol which means that Supperware and our friends aren’t tied to an annual MIDI Manufacturer’s Association subscription. (Not for this, anyway.)

Where to use supl

We provide lovely GUIs for some production hardware to manage firmware in a smooth and pretty way, like Bridgehead and the PWM Updater. supl is not that pretty, but it’s useful while a GUI is outside the project scope, or we haven’t finished it yet.

It also unlocks features that customers might lack, such as no-questions-asked downgrading and wiping non-volatile memory.

Although supl is customer-safe because it’s robust against bricking units and doesn’t expose any secrets, you might not want too many end-users playing with this, because a terminal application is a lot to figure out for some people.

Here it is! for Windows 64-bit for macOS

How to use it

  1. Unzip the application and put it somewhere you can find it.
  2. Plug in some Supperware hardware.
  3. On Windows, run cmd, navigate to the appropriate folder., and type supl info
  4. On macOS, run terminal, navigate to the appropriate folder, and type ./supl info
  5. If you have some compatible hardware, supl will connect to it and display the device and version information.

supl info : seeing what you have

Here you see that we’re connected to a head tracker: the USB name of the device is displayed as well as an asset code (=headtrk) which is the device’s internal way of making sure that it doesn’t try to load something it shouldn’t.

The hardware version is given as /2. Actually this is quite old: that head tracker firmware is good up to /8. But again, there’s a hardware version tracking mechanism within these tools so that we don’t end up with compatibility issues.

#0 is a placeholder for a serial number. Some products, like the head tracker, are aware of their serial number. It can only be set in the bootloader, and the act of setting it enables read-out protection.

b and m are version numbers for the bootloader and main firmware.

The hexadecimal at the bottom is a CRC code and length, so that the bootloader can check that the firmware is good before trying to run it. Usually there is no manual way to start the bootloader as it’s assumed that the software is tested enough that we’re not going to break our customers’ units. The CRC is one check that is run before we call the main firmware; another is looking for evidence of a watchdog reset. If the main firmware hangs, we don’t run it a second time.

supl load : upgrading firmware

Type supl load firmware.supload (Windows) or ./supl load firmware.supload (macOS) to load some firmware, with firmware.supload replaced with the appropriate filename. If you don’t have any firmware files, what are you even doing here?

supl checks for file validity before it goes ahead — you can’t brick a synthesiser by trying to upload a JPEG — but it doesn’t ask for confirmation. To take a closer look at compatibility without diving into an upgrade, you can change the verb and use supl verify instead.

Note: The load operation might have to be run twice on macOS. When a device restarts into the bootloader, supl might not see it until you run it again. This is a JUCE library issue that hasn’t had the investigation it deserves.

supl wipe : wiping non-volatile memory

If your device has permanent configuration settings, supl wipe will remove them all and revert your unit back to its virginal, decalibrated state. (Not the serial number, though!)

This command might get us out of a scrape if something unexpected and bad happens to pre-production firmware that we failed to predict and cannot reset our way out of, but it’s best not to be too cavalier about using this unless you know exactly what you’re going to throw away. In the head tracker, for example, it’s calibration settings and things like chirality that the device remembers because it’s handy to do so. On Malevolent, it’s joystick and pitch calibration and MIDI channel settings.