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

crasbe · crasbe · commit ebcb656d8aa4 · 2025-03-21T15:20:10.000+01:00
diff --git a/boards/common/adafruit-nrf52-bootloader/doc.md b/boards/common/adafruit-nrf52-bootloader/doc.md
@@ -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
+With the following commands, the bootloader with SoftDevice will be compiled
+and flashed. For MacOS, you might have to select a different serial port.
+
+```
+git clone https://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
-~~~~~~~~~~~~~
-
-[nrfjprog]: https://www.nordicsemi.com/Products/Development-tools/nRF-Command-Line-Tools
-
-## Updating Old Bootloaders and Restoring the SoftDevice
+make BOARD=feather_nrf52840_sense SERIAL=/dev/ttyACM0 flash-dfu
+```
 
-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
+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
-make BOARD=feather_nrf52840_sense SERIAL=/dev/ttyACM0 flash-dfu
-```
+nrfjprog --recover
+make BOARD=feather_nrf52840_express flash
+make BOARD=feather_nrf52840_express flash-sd
+~~~~~~~~~~~~~
 
-Further information can be found on the
-[Adafruit Website](https://learn.adafruit.com/adafruit-feather-sense/update-bootloader).
+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
