1
0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2024-12-29 04:50:03 +01:00
RIOT/bootloaders/riotboot_dfu/doc.txt
Gunar Schorcht 421cbc5c29 bootloaders/riotboot_dfu: improve documentation of usage
The `dfu-util` command uses `--device $(DFU_USB_ID)`, where `DFU_USB_ID` is derived from `USB_VID` and `USB_PID` to specify the DFU device to use. Without specifying `USB_VID` and `USB_PID` in the make command, `dfu-util` is called with `--device :`, which only works if there is only one DFU device. Also, the STM32 make system forbids the use of `dfu-util` as programmer without setting the variable `DFU_USB_ID`. Therefore, the documentation is changed to use `USB_VID`/`USB_PID` or `DFU_USB_ID` in the make command.
2022-11-30 19:28:14 +01:00

82 lines
2.9 KiB
Plaintext

/**
@defgroup bootloader_riotboot_dfu riotboot DFU
@ingroup bootloaders
# Overview
`riotboot_dfu` is a variation on @ref bootloader_riotboot that adds USB device firmware upgrade (DFU).
In addition to the (otherwise small) slot selection,
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 @ref BTN_BOOTLOADER_PIN), or
- the last running firmware asked the bootloader to go to DFU mode by using a magic number (see @ref RIOTBOOT_MAGIC_ADDR).
# Prerequisites
- The board must have functional USB support, easily tested using the `examples/usbus_minimal/` example.
- The board must have functional riotboot support, see @ref bootloader_riotboot.
# Flashing riotboot_dfu
The `riotboot_dfu` bootloader can be flashed using a regular programmer like any other application:
```
$ make -C bootloaders/riotboot_dfu BOARD=particle-xenon 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 `usbus_dfu` module),
new firmware can be flashed to slot 0 using:
```
$ FEATURES_REQUIRED+=riotboot USEMODULE+=usbus_dfu make -C examples/saul BOARD=particle-xenon \
PROGRAMMER=dfu-util all riotboot/flash-slot0
```
By default, the VID/PID pair 1209:7d02 is used for the device to be flashed
in riotboot DFU mode. If necessary, this VID/PID pair can be overwritten with
the variable `DFU_USB_ID`, e.g. if the RIOT DFU bootloader was compiled for
a different VID/PID pair.
```
$ FEATURES_REQUIRED+=riotboot USEMODULE+=usbus_dfu make -C examples/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 (eg. `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+=usbus_dfu`,
they implement what is called "runtime mode" in DFU.
In runtime mode, it is visible to 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`.
*/