BBR Digital Expander Documentation

Updating the firmware#

The board runs its own firmware, and it ships with a version on it. You do not need to update it to use the board — but a driver that refuses to start with “firmware speaks a protocol major this driver does not” is telling you the two have drifted apart, and this is the page that fixes it.

Get the release#

Download firmware 1.1.1 (bbr-digital-expander-1.1.1.uf2)

Every release, with its notes, is on the driver repository’s releases page: all firmware releases.

A UF2 is the Raspberry Pi Foundation’s drag-and-drop firmware format. There is nothing to install to use one — the board appears as a USB drive and you copy the file onto it.

What’s new in 1.1.1#

Update if your robot sees I2C dropouts, or the driver logs expander REBOOTED.

  • No more hangs under bus noise. Electrical noise on the I2C cable could make 1.1.0 freeze for half a second and restart, holding the bus while it did. 1.1.1 fixes the cause.
  • Faster recovery from noise. When a noise spike puts the board out of step with the Hub, it now lets go of the bus within about 1 ms instead of 50.
  • No lost read after a pause. The first read after the Hub has been quiet for a while is no longer at risk of being reset.
  • Checksummed telemetry and diagnostics (new since 1.0.0, protocol 1.2): encoder and sensor readings are CRC-checked like the pose, and the board reports why it last reset and how often its I2C link has been disturbed.

Which version am I on?#

Ask the board rather than guessing. Every driver prints it:

telemetry.addData("firmware", exp.getFirmwareVersion());   // 1.1.1
telemetry.addData("protocol", "1.%d", exp.getProtocolMinor());

The firmware version and the protocol version are different numbers and move independently. The protocol version is the contract the drivers are written against; the firmware version identifies the build. A driver only refuses to run over a mismatched protocol major.

Put the board in bootloader mode#

Hold the USB select button down, then plug the USB cable in. Keep the button held until the drive appears; you can let go after that.

The board comes up in its bootloader rather than running the firmware, disconnects from I2C, and appears on your computer as a USB drive named RPI-RP2.

No drive appeared? The button was not down early enough — it is read once, as the board powers up, so pressing it after the cable is in does nothing. Unplug, press and hold, plug back in.

Copy the UF2 across#

Drag the .uf2 file onto the RPI-RP2 drive, or:

cp bbr-digital-expander-1.1.1.uf2 /Volumes/RPI-RP2/     # macOS
cp bbr-digital-expander-1.1.1.uf2 /media/$USER/RPI-RP2/ # Linux

The drive disappears on its own as soon as the copy finishes — that is the board rebooting into the new firmware, not an error or an ejection failure. It is back on the I2C bus a moment later.

Then check it took, with the same device_info call as above. The version it reports is the version you flashed.

Your configuration survives#

Taught colours, trigger configuration, encoder directions, localizer parameters and PWM calibration all live in a flash region the firmware image does not reach — the image ends well below 64 KB, and the configuration slots are at the top of an 8 MB part. Updating the firmware does not erase what you taught the board.

The exception is a firmware that changes the configuration schema. When that happens the board loads defaults rather than misreading an old layout, and says so: STATUS raises its CFG_DEFAULTED bit, which device_info prints as config-defaulted. Any release that does this will say so in its notes. Re-teach and re-save if you see it.

If it goes wrong#

The drive appeared, the file copied, and now nothing is on the bus. Put it back in bootloader mode and copy the UF2 again. A UF2 is verified as it is written, so a half-copied image is not the usual cause; a wrong .uf2 — one built for a different board — is.

The RPI-RP2 drive never appears. Hold the USB select button down before the cable goes in and keep holding it — that is the whole trick. If it still does not appear, try another USB cable: a charge-only cable powers the board but carries no data, so the board is alive and the computer cannot see it.