Skip to content

Programming

This page documents how to update or program your Solo.

Prerequisites

To program Solo, you'll likely only need to use our Solo tool.

pip3 install solo-python

Updating the firmware

If you just want to update the firmware, you can run one of the following commands. Make sure your key is in bootloader mode first.

solo key update <--secure | --hacker>

You can manually install the latest release, or use a build that you made.

solo program bootloader <firmware.hex | firmware.json>

Note you won't be able to use all.hex or the bundle-*.hex builds, as these include the solo bootloader. You shouldn't risk changing the Solo bootloader unless you want to make it a secure device, or make other customizations.

Updating a Hacker to a Secure Solo

Updating a hacker to be a secure build overwrites the Solo bootloader. So it's important to not mess this up or you may brick your device.

You can use a firmware build from the latest release or use a build that you made yourself.

You need to use a firmware file that has the combined bootloader, application, and attestation key pair (bootloader + firmware + key). This means using the bundle-*.hex file or the bundle.hex from your build.

Warning

  • Any DFU update erases everything! If you overwrite the Solo flash with a missing bootloader, it will be bricked.
  • If you program bootloader and firmware with no attestation, you will run into FIDO registration issues.

We provide two types of bundled builds. The bundle-hacker-*.hex build is the hacker build. If you update with this, you will update the bootloader and application, but nothing will be secured. The bundle-secure-non-solokeys.hex is a secured build that will lock your device and it will behave just like a Secure Solo. The main difference is that it uses a "default" attestation key in the device, rather than the SoloKeys attestation key. There is no security concern with using our default attestation key, aside from a small privacy implication that services can distinguish it from Solo Secure.

Procedure

  1. Boot into DFU mode.

    # Enter Solo bootloader
solo program aux enter-bootloader

# Enter DFU
solo program aux enter-dfu

    The device should be turned off.

  2. Program the device

    solo program dfu <bundle-secure-non-solokeys.hex | bundle.hex>

    Double check you programmed it with bootloader + application (or just bootloader). If you messed it up, simply don't do the next step and repeat this step correctly.

  3. Boot the device

    Once Solo boots a secure build, it will lock the flash permantly from debugger access. Also the bootloader will only accept signed firmware updates.

    solo program aux leave-dfu

If you are having problems with solo tool and DFU mode, you could alternatively try booting into DFU by holding down the button while Solo is in bootloader mode. Then try another programming tool that works with ST DFU:

  • STM32CubeProg
  • openocd
  • stlink

Windows users need to install libusb for solo-python to work with Solo's DFU.

Programming a Solo that hasn't been programmed

A Solo that hasn't been programmed will boot into DFU mode. You can program it by following a bootloader, or combined bootloader + application.

solo program dfu <bundle-*.hex | all.hex>

Then boot the device. Make sure it has a bootloader to boot to.

solo program aux leave-dfu

Disable signed firmware updates

If you'd like to also permanently disable signed updates, plug in your programmed Solo and run the following:

# WARNING: No more signed updates.
solo program disable-bootloader

You won't be able to update to any new releases.