kaspar/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2025-12-27 23:41:18 +01:00
Code Releases Activity

boards/common/ada-nrf52-bootl: refactor and enhance documentation

Browse Source
This commit is contained in:
crasbe 2025-03-13 18:24:43 +01:00
parent ec6cd78174
commit ebcb656d8a
1 changed files with 71 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
boards/common/adafruit-nrf52-bootloader/doc.md
View File

@ -2,13 +2,37 @@
@ingroup boards_common
@brief Common Flashing Description for the Adafruit nRF52 Bootloader
## Flashing the Board
## Introduction
The board is flashed using its on-board UF2 boot loader by default.
The boot loader will present a mass storage device that has to be mounted to /media/MDK-DONGLE so
`uf2conv.py` can find it. If you have an auto-mounter installed this will happen automatically.
The Adafruit nRF52 Bootloader is used by many Adafruit and Seeedstudio boards
that are based on the Nordic Semiconductor nRF52 microcontroller family.
It features a Mass Storage Device emulation, so that UF2 files can be uploaded
via Drag and Drop. It is also backwards compatible to the BOSSA bootloader.
With the Adafruit nRF52 Bootloader, no external debugger such as a J-Link is
necessary for the normal usage.
The rest of the process is automated in the usual way with e.g. `BOARD=feather-nrf52840`.
In some cases the bootloader may be too old to even mount on startup.
Enter the bootloader mode (usually by double tapping the reset button for
nRF52840 based boards) and check the `INFO_UF2.TXT` for bootloader information.
If the version is less than `0.4.0`, please refer to @ref ada-nrf52-update.
Until and including RIOT Release 2025.01, the SoftDevice on `feather-nrf52840`
and `feather-nrf52840-sense` boards got erased when flashing RIOT. To restore
the ability of using i.a. Arduino and CircuitPython, the SoftDevice has to be
flashed again. Please also refer to @ref ada-nrf52-update.
If the bootloader is not present on your board at all, an external debugger
such as the J-Link has to be used. Please refer to @ref ada-nrf52-reflashing.
## Flashing the Board with RIOT
The board is flashed using its on-board UF2 bootloader by default.
The bootloader will present a mass storage device that has to be mounted so
the RIOT buildsystem can find it. If you have an auto-mounter installed this
will happen automatically.
The rest of the process is automated in the usual way with e.g.
`BOARD=feather-nrf52840`.
Example with `hello-world` application:
```
@ -39,63 +63,63 @@ for SoftDevice Version 6.1.1 and `SD730` for Version 7.3.0.
make a reflash of the SoftDevice necessary. Do not change it unless you know
what you're doing!**
Otherwise see the **Flashing** section in @ref boards_common_nrf52. The easiest way is to
use an external Segger J-Link Programmer connected to the [SWD Connector].
## Updating Old Bootloaders and Restoring the SoftDevice {#ada-nrf52-update}
[SWD Connector]: https://learn.adafruit.com/introducing-the-adafruit-nrf52840-feather/pinouts#swd-connector-3-12
If the Adafruit nRF52 Bootloader is still present on the board but outdated
or the SoftDevice got erased (the `INFO_UF2.TXT` file will show
`SoftDevice: not found`), you can flash the bootloader via DFU.
## (Re-)Flashing the UF2 Bootloader
As prerequisites, the `arm-none-eabi-gcc` compiler (which is usually already
present if you compiled something for your nRF52 board) and the
`adafruit-nrfutil` have to be installed.
To flash the UF2 bootloader (if it is no longer present on your board),
you need to have [`nrfjprog`][nrfjprog] installed,
connect a jlink to your BOARD and execute the following commands.
Details on the installation process can be found in [Adafruit's GitHub
repository](https://github.com/adafruit/Adafruit_nRF52_Bootloader).
@note The Adafruit nRF52 Bootloader uses other board names than RIOT. The
`feather-nrf52840` for example is called `feather_nrf52840_express`.
Be sure to check the `boards/` subfolder in the bootloader directory
to find out the correct board name.
~~~~~~~~~~~~~{.sh}
git clone git@github.com:adafruit/Adafruit_nRF52_Bootloader.git
cd Adafruit_nRF52_Bootloader
# only download what is needed, use
# `git submodule update --init --recursive`
# to download everything
git submodule update --init
git -C lib/tinyusb submodule update --init hw/mcu/nordic/nrfx/
pip3 install --user adafruit-nrfutil
make BOARD=feather_nrf52840_express all
make BOARD=feather_nrf52840_express flash
make BOARD=feather_nrf52840_express flash-sd
~~~~~~~~~~~~~
With the following commands, the bootloader with SoftDevice will be compiled
and flashed. For MacOS, you might have to select a different serial port.
[nrfjprog]: https://www.nordicsemi.com/Products/Development-tools/nRF-Command-Line-Tools
## Updating Old Bootloaders and Restoring the SoftDevice
In some cases the bootloader may be too old to even mount on startup.
Enter the bootloader mode (usually by double tapping the reset button for
nRF52840 based boards) and check the `INFO_UF2.TXT` for bootloader information.
If the version is less than `0.4.0` then one can use the
[Adafruit_nRF52_Bootloader](https://github.com/adafruit/Adafruit_nRF52_Bootloader)
tool to update.
Until and including RIOT Release 2025.01, the SoftDevice on `feather-nrf52840` and
`feather-nrf52840-sense` boards got erased when flashing RIOT. To restore the
ability of using i.a. Arduino and CircuitPython, the SoftDevice has to be
flashed again. This can be done in the same way as updating the bootloader.
Sometimes the process has to be done twice until the SoftDevice is successfully
restored.
For example, one can run the following if `arm-none-eabi-gcc` and
`adafruit-nrfutil` are installed. Make sure to select the correct board for your
application.
```
git clone https://github.com/adafruit/Adafruit_nRF52_Bootloader.git
cd Adafruit_nRF52_Bootloader
git submodule update --init
pip3 install --user adafruit-nrfutil
make BOARD=feather_nrf52840_sense SERIAL=/dev/ttyACM0 flash-dfu
```
Further information can be found on the
Sometimes the process has to be done twice until the SoftDevice is successfully
restored.
Further information about the update process can be found on the
[Adafruit Website](https://learn.adafruit.com/adafruit-feather-sense/update-bootloader).
## (Re-)Flashing the UF2 Bootloader with an External Debugger {#ada-nrf52-reflashing}
To flash the UF2 bootloader (if it is no longer present on your board),
you need to have the original [`nrfjprog`][nrfjprog] installed and a compatible
debugger, such as a J-Link. Make sure to select the right board (see the note
in @ref ada-nrf52-update).
~~~~~~~~~~~~~{.sh}
git clone https://github.com/adafruit/Adafruit_nRF52_Bootloader
cd Adafruit_nRF52_Bootloader
git submodule update --init
nrfjprog --recover
make BOARD=feather_nrf52840_express flash
make BOARD=feather_nrf52840_express flash-sd
~~~~~~~~~~~~~
More information about how to flash nRF52 microcontrollers can be found in the
**Flashing** section in @ref boards_common_nrf52. Some variants of the
Adafruit Feather feature an [SWD Connector], to which an external debugger can
be connected. Other boards such as the Seeedstudio Xiao nRF52840 only have
solder pads.
[SWD Connector]: https://learn.adafruit.com/introducing-the-adafruit-nrf52840-feather/pinouts#swd-connector-3-12
[nrfjprog]: https://www.nordicsemi.com/Products/Development-tools/nRF-Command-Line-Tools