riotboot tinyUSB DFU

Detailed Description

Overview

riotboot_tinyusb_dfu is a variation of riotboot that adds USB device firmware upgrade (DFU) based on the tinyUSB device stack package. It uses a board's USB interface to allow firmware upgrades from inside the bootloader.

At startup, the DFU mode is entered when either

• none of the slots contains a valid firmware image, or
• the first button was pressed when the board started (configurable at board level using BTN_BOOTLOADER_PIN), or
• the last running firmware asked the bootloader to go to DFU mode by using a magic number (see RIOTBOOT_MAGIC_ADDR).

Prerequisites

• The board must have functional USB support and has to support the tinyusb_device feature.
• The board must have functional riotboot support, see riotboot.

Flashing riotboot_tinyusb_dfu

The riotboot_tinyusb_dfu bootloader can be flashed using a regular programmer like any other application:

$ make -C bootloaders/riotboot_tinyusb_dfu BOARD=... all flash

Depending on your setup, you may need to select the right PROGRAMMER (and its details) in addition to your board.

DFU mode

A device in riotboot DFU mode can be recognized in the USB device list by its VID/PID pair 1209:7d02:

$ lsusb
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 005: ID 138a:003f [...]
Bus 001 Device 004: ID 8087:0a2b [...]
Bus 001 Device 045: ID 1209:7d02 Generic USB device
Bus 001 Device 001: ID 1d6b:0002 [...]

When running in DFU mode, the bootloader allows writing to either of the two firmware slots.

When the device is attached and in DFU mode (or the current firmware uses the tinyusb_dfu module), new firmware can be flashed to slot 0 using:

$ FEATURES_REQUIRED+=riotboot USEMODULE+=tinyusb_dfu make -C examples/basic/saul BOARD=particle-xenon \
  PROGRAMMER=dfu-util USB_VID=1209 USB_PID=7d02 all riotboot/flash-slot0

Instead of setting USB_VID and USB_PID, the variable DFU_USB_ID could also be used to specify the DFU device to be used.

$ FEATURES_REQUIRED+=riotboot USEMODULE+=tinyusb_dfu make -C examples/basic/saul BOARD=particle-xenon \
  PROGRAMMER=dfu-util DFU_USB_ID=1209:7d02 all riotboot/flash-slot0

Note that when building and flashing a different slot (e.g. flash-slot1), not only is the image built for that slot, but also dfu-util gets passed --alt 1 (via the DFU_ALT build variable) to store it in the right place.

Entering DFU mode

When RIOT applications are built with USEMODULE=tinyusb_dfu, they implement what is called "runtime mode" in DFU.

In runtime mode, it is visible to the dfu-util that they are upgradable. On firmware upgrades, the build system can send a command via USB to enter DFU mode. This can also be done manually using dfu-util -e.

Files
file	tinyusb_dfu.h
	TinyUSB specific DFU definitions.