Skip to content
Snowbird Power Systems

Documentation

Firmware updates

Updating the supervisor over I2C or Bluetooth, what the update policy promises, and how to report a vulnerability.

Two update paths

Every board updates over I2C from the host, using the snowbird-flash command-line tool. Boards with the radio (Snowbird Feather 1S, Snowbird Core 1S, Snowbird 18650, Snowbird Pack) also update over Bluetooth with signed images and MCUboot. Both paths verify the image signature before anything is written to the active slot, and a failed or interrupted update leaves the previous firmware running.

The battery, the charger and the BMS keep working through an update. The supervisor reboots into the new image in about 300 ms; the BMS is in its safe defaults for that interval and the regulators stay up.

Over I2C with snowbird-flash

snowbird-flash runs on Linux, macOS and Windows and drives the board through any I2C adapter it can see: a Raspberry Pi's bus, an FT232H, a CH341, or a Feather host running the bridge sketch from the library examples.

pipx install snowbird-flash
snowbird-flash list                       # adapters and boards found
snowbird-flash info --bus /dev/i2c-1      # board, firmware, register map
snowbird-flash update --bus /dev/i2c-1    # latest release for this board
snowbird-flash update --bus /dev/i2c-1 --image snowbird-feather-1s-2.3.1.bin
snowbird-flash update --bus /dev/i2c-1 --image no-radio   # the no-radio build

update without --image fetches the current release for the detected board from the release server, checks its signature against the Snowbird public key shipped in the tool, and asks before writing. Settings (chemistry, capacity, limits, name, bonds) are preserved across updates.

From a Feather host without a separate adapter, flash the SnowbirdBridge example to the host and point snowbird-flash at its serial port:

snowbird-flash update --port /dev/ttyACM0

The SWD pads on the underside are for recovery and development only. A board that has been bricked by a power loss during an SWD session can always be recovered over SWD; it cannot be bricked by snowbird-flash, because the bootloader is never rewritten by it.

Over Bluetooth

Boards with the radio run MCUboot with two image slots. The DFU service is the standard MCUmgr SMP service over BLE, so the usual tools work:

  • nRF Connect Device Manager (Android and iOS): open the device, choose Image, select the .bin, Upload, then Test and Confirm.
  • mcumgr on the command line:
mcumgr --conntype ble --connstring peer_name='Snowbird-3F2A' image upload snowbird-feather-1s-2.3.1.bin
mcumgr --conntype ble --connstring peer_name='Snowbird-3F2A' image test <hash>
mcumgr --conntype ble --connstring peer_name='Snowbird-3F2A' reset
  • The Snowbird dashboard at /dashboard in Chrome: Firmware, then Update. It fetches the release, uploads it and confirms it.

DFU over BLE requires a bonded connection with LE Secure Connections, the same as configuration writes, and BLE writes must be enabled. See Bluetooth. The image is signed with the Snowbird release key; the bootloader rejects anything else, including an image for a different board.

Test-then-confirm is the safe sequence. An image uploaded with Test runs once; if it does not confirm itself within 60 s of booting, which it does only after the supervisor has read the BMS and found it sane, the bootloader reverts to the previous image.

Releases

Firmware releases are published at /firmware with, for each version: the release notes, the .bin for each board, the detached signature, the SHA-256, the register map YAML and the generated C header. Releases are also announced on the build log and to the mailing list. The current versions are shown on each product page.

Version numbers are semantic. A patch release changes nothing a sketch can see. A minor release adds registers and events. A major release changes the register map's major version, and the libraries are released alongside it.

Verifying an image

Each release ships a detached Ed25519 signature. The public key is in the tool, in the library, and on this page:

snowbird-release-2026  ed25519  3f0c5b2e9a71d4c86b2f0e1d9c7a4b5e6f8d2a1c0b9e8f7a6d5c4b3a2f1e0d9c

sha256sum -c snowbird-feather-1s-2.3.1.bin.sha256
snowbird-flash verify --image snowbird-feather-1s-2.3.1.bin

verify checks the signature and prints the board the image is for and the register map version it carries.

The update policy

  • Security fixes for every board for five years from the date it was last sold.
  • Bug fixes for the current and previous minor version.
  • Register map compatibility: a minor release never moves or removes a register. A major release is announced at least six months ahead, and the previous major keeps receiving security fixes for the policy period.
  • Nothing phones home. The board has no idea whether it is up to date; snowbird-flash and the dashboard check the release server only when you ask.

Reporting a vulnerability

Report security issues in the firmware, the libraries, the dashboard or this site to [email protected]. Encrypt with the PGP key published at /security.txt if the report is sensitive.

What to expect:

  1. An acknowledgement within two business days.
  2. An assessment and a target fix date within ten business days.
  3. A fix released as a patch version, with credit in the release notes if you want it.
  4. Public disclosure coordinated with you, and no later than 90 days after the report.

Please do not test against boards you do not own, and please do report anything that lets an unbonded central change a setting, that lets a setting exceed a jumper ceiling, or that lets an unsigned image run. Those are the three properties the design depends on.

For everything that is not a security issue, the address is [email protected].

Register map