Link search Menu Expand Document
monome/docs

modular firmware updates

new releases are available per module:

firmware is updated by connecting a USB A-A cable to your computer and using the utility dfu programmer.

get a normal, inexpensive USB A-A cable such as p/n 1175-1035-ND on digikey. a “transfer” cable will not work.

mac

nb. if you run into verification troubles at any point through this process, please refer to the steps in this Apple support article to resolve!

we’ll use Homebrew to install dfu-programmer. to get Homebrew installed on your Mac, go to the homebrew page and scroll down to “Install Homebrew” where it will prompt you to paste a line of text into Terminal.

after Homebrew is installed, be sure to run any Next steps that it presents to you.

then, you should be able to simply type:

brew install dfu-programmer

(if you see brew: command not found, this means the commands Homebrew asked you to run in the Next steps did not get executed and Homebrew is not executible. please try installing homebrew again.)

now, we can move on to the firmware. download the firmware from the links at the top of this page. remember where these are stored on your computer. inside, there’s a script called update_firmware.command within the named module folder.

connect the USB A-A cable to your computer and the module. on the module, hold down the front panel button while powering up to launch the bootloader. the leds may be lit or not; don’t worry.

within the folder execute the downloaded script by double-clicking (in mac):

update_firmware.command

and the firmware will be updated. the clock led (if present) will flash to show it has successfully installed.

you will need to power-cycle the module to re-enable USB device detection.

seeing device not present? first, ensure you are following the connection steps in order. then, it might be good to update Xcode’s command-line tools (following the steps in this post).

windows

download the dfu-programmer binary from dfu-programmer.github.io.

connect the USB A-A cable to your computer and the module. on the module, hold down the front panel button while powering up to launch the bootloader. the leds may be lit or not; don’t worry. at this point, Windows should say a new device was detected and it’s installing drivers for it.

open your device manager.

there should be a new category: Atmel USB Devices (you might need to select view > show hidden devices) with AT32UC3B device. If there is a warning icon next to it you need to update the driver – right click and select Update Driver Software, then Browse my computer for driver software. navigate to the folder where you installed dfu-programmer. it should find a new driver there; install it. if everything installs okay, the warning icon next to the device should disappear.

get the firmware from the links at the top of the page. remember where these are stored on your computer.

copy the firmware hex file to your dfu-programmer folder.

run cmd as Administrator (not sure it matters but best to anyway), cd to the dfu-programmer folder and execute the following (replace whitewhale.hex with whatever firmware you’re updating):

dfu-programmer at32uc3b0512 erase
dfu-programmer at32uc3b0512 flash whitewhale.hex --suppress-bootloader-mem
dfu-programmer at32uc3b0512 start

the clock led (if present) will flash to show it has successfully installed.

you will need to power-cycle the module to re-enable USB device detection.

if you’re getting a missing libusb error, there’s a pretty good change the driver update didn’t work. try to redo the process above (starting at “open your device manager.”)

linux

you’ll need to install dfu-programmer from your distribution’s package repository, or build it from source.

get the firmware from the links at the top of the page. remember where these are stored on your computer. unzip the firmware to get the script called update_firmware.command within the named module folder.

$ unzip firmware.zip

connect the USB A-A cable to your computer and the module. on the module, hold down the front panel button while powering up to launch the bootloader. the leds may be lit or not; don’t worry.

to run the firmware update command, your user will need to be in the dialout or uucp group, depending on what your distribution calls it. otherwise you’ll need to run it as root or sudo:

$ ./update_firmware.command

the clock led (if present) will flash to show it has successfully installed.

you will need to power-cycle the module to re-enable USB device detection.

firmware backups

you may wish to backup your module firmware before updating it, particularly if you want to save your presets, patterns, scales, settings. at this time, it is not possible to save or restore only presets; the entire firmware image, including any presets, is backed up from or loaded into the module. this means that restoring a backup may reinstall an older version of the firmware, potentially losing features or bugfixes in newer firmware versions.

to backup your firmware, install dfu-programmer and power up the module in bootloader mode according to the earlier instructions. then, follow the steps below for your module.

ansible, meadowphysics, white whale, earthsea

once in bootloader mode, open a terminal and run:

dfu-programmer at32uc3b0512 read > firmware-name.hex

restart the module before you unplug the USB cable:

dfu-programmer at32uc3b0512 start

you can restore the backed-up firmware any time by getting back into bootloader mode, opening a terminal in your backup’s directory, and running:

dfu-programmer at32uc3b0512 erase
dfu-programmer at32uc3b0512 flash firmware-name.hex --suppress-bootloader-mem
dfu-programmer at32uc3b0512 start

note: these are the same commands that are run by the update_firmware.command script included in the official firmware releases.

teletype

once in bootloader mode, open a terminal and run:

dfu-programmer at32uc3b0512 read > firmware-name.hex

restart the module before you unplug the USB cable:

dfu-programmer at32uc3b0512 start

you can restore the backed-up firmware any time by getting back into bootloader mode, opening a terminal in your backup’s directory, and running:

dfu-programmer at32uc3b0512 erase
dfu-programmer at32uc3b0512 flash firmware-name.hex --suppress-bootloader-mem
dfu-programmer at32uc3b0512 start

note: these are the same commands that are run by the update_firmware.command script included in the official firmware releases.

after reflashing teletype, it makes the following proclamation:

SCENES WILL BE OVERWRITTEN!
PRESS TO CONFIRM
DO NOT PRESS OTHERWISE!

this will appear every time you power on the module until the panel button is pressed during this message, after which the module will behave normally. this is a safeguard that requires user confirmation before teletype will reset its flash memory to the default state, and was added to avoid accidentally wiping out saved scenes. if you see this message or get stuck in this state after normal usage of teletype without reflashing, do not press the button and please do post on lines, it should be possible to recover your scenes and troubleshoot using a firmware backup .hex file.