boards/common: Make Adafruit nRF52 Bootloader shared

boards/common/adafruit-nrf52-bootloader/Makefile

@@ -0,0 +1,3 @@
+MODULE = boards_common_adafruit-nrf52-bootloader
+
+include $(RIOTBASE)/Makefile.base

boards/common/adafruit-nrf52-bootloader/Makefile.dep

@@ -0,0 +1,4 @@
+include $(RIOTBOARD)/common/nrf52/bootloader_nrfutil.dep.mk
+
+# make sure the bootloader module is used for reset to work
+USEMODULE += boards_common_adafruit-nrf52-bootloader

boards/common/adafruit-nrf52-bootloader/Makefile.include

@@ -0,0 +1,71 @@
+PROGRAMMER ?= uf2conv
+
+ifneq (,$(filter uf2conv,$(PROGRAMMER)))
+
+  # The Adafruit nRF52 Bootloader currently only really supports
+  # two MCUs. Set the according Family Flag and SoftDevice version if
+  # not set already.
+  ifneq (,$(filter nrf52833xxaa,$(CPU_MODEL)))
+    UF2CONV_FLAGS = -f 0x621E937A
+
+    # The Adafruit nRF52 Bootloader has a static MBR at the first 4k
+    # and a 38k UF2 Bootloader at the end, leaving 972k (nRF52840) or 460k
+    # (nRF52833) for the application when not using the SoftDevice.
+    # SoftDevice v6 uses an additional 114k and SoftDevice v7 uses 118k.
+    # The option "DROP" overrides any SoftDevice, making a reflash of the
+    # bootloader necessary if i.a. Arduino or CircuitPython
+    # are to be used again.
+    ifneq (,$(filter DROP,$(UF2_SOFTDEV)))
+      ROM_OFFSET = 0x1000
+      ROM_LEN    = 0x7f000
+
+    else ifneq (,$(filter SD611,$(UF2_SOFTDEV)))
+      ROM_OFFSET = 0x26000
+      ROM_LEN    = 0x5a000
+
+    else ifneq (,$(filter SD730,$(UF2_SOFTDEV)))
+      ROM_OFFSET = 0x27000
+      ROM_LEN    = 0x59000
+
+    else
+      $(error Unsupported SoftDevice Version $(UF2_SOFTDEV).)
+    endif
+
+  else ifneq (,$(filter nrf52840xxaa,$(CPU_MODEL)))
+    UF2CONV_FLAGS = -f 0xADA52840
+
+    ifneq (,$(filter DROP,$(UF2_SOFTDEV)))
+      ROM_OFFSET = 0x1000
+      ROM_LEN    = 0xf3000
+
+    else ifneq (,$(filter SD611,$(UF2_SOFTDEV)))
+      ROM_OFFSET = 0x26000
+      ROM_LEN    = 0xda000
+
+    else ifneq (,$(filter SD730,$(UF2_SOFTDEV)))
+      ROM_OFFSET = 0x27000
+      ROM_LEN    = 0xd9000
+
+    else
+      $(error Unsupported SoftDevice Version $(UF2_SOFTDEV).)
+    endif
+
+  else
+    $(error Unsupported CPU $(CPU_MODEL) for Adafruit nRF52 Bootloader.)
+  endif
+
+  # Driver can take some time to get mounted
+  PREFLASH_DELAY ?= 3
+  include $(RIOTMAKE)/tools/usb_board_reset.mk
+endif
+
+PROGRAMMERS_SUPPORTED += uf2conv
+
+# HACK: replicate dependency resolution in Makefile.dep, only works
+# if `USEMODULE` or `DEFAULT_MODULE` is set by the command line or in the
+# application Makefile.
+ifeq (,$(filter stdio_%,$(DISABLE_MODULE) $(USEMODULE)))
+  RIOT_TERMINAL ?= jlink
+endif
+
+include $(RIOTBOARD)/common/nrf52/Makefile.include

boards/common/adafruit-nrf52-bootloader/doc.md

@@ -0,0 +1,125 @@
+@defgroup  boards_common_adafruit-nrf52-bootloader Adafruit nRF52 Bootloader Common
+@ingroup   boards_common
+@brief     Common Flashing Description for the Adafruit nRF52 Bootloader
+
+## Introduction
+
+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.
+
+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:
+```
+     make BOARD=feather-nrf52840 -C examples/basic/hello-world flash term
+```
+
+If RIOT is already running on the board, it will automatically reset the CPU and enter
+the bootloader.
+If some other firmware is running or RIOT crashed, you need to enter the bootloader
+manually by double-tapping the board's reset button while the device is connected.
+
+The board definitions with RIOT retain the SoftDevice firmware blob shipped with
+the original Adafruit nRF52 Bootloader that is used by i.a. Arduino and
+CircuitPython but not used by RIOT. If you want to override the SoftDevice
+to avoid having closed source software on your microcontroller or if you need
+the additional space, you can specify the `UF2_SOFTDEV=DROP` option in your
+`make` command. **Be aware that you have to reflash the SoftDevice if you want
+to use it in the future!**
+
+```
+     make UF2_SOFTDEV=DROP BOARD=feather-nrf52840 -C examples/basic/hello-world flash term
+```
+
+If your board features a non-standard SoftDevice version, you can specify it
+with the `UF2_SOFTDEV` option as well. Currently supported are i.a. `SD611`
+for SoftDevice Version 6.1.1 and `SD730` for Version 7.3.0.
+**Setting the wrong SoftDevice version might corrupt the SoftDevice and
+make a reflash of the SoftDevice necessary. Do not change it unless you know
+what you're doing!**
+
+## Updating Old Bootloaders and Restoring the SoftDevice {#ada-nrf52-update}
+
+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.
+
+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.
+
+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.
+
+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
+git submodule update --init
+pip3 install --user adafruit-nrfutil
+make BOARD=feather_nrf52840_sense SERIAL=/dev/ttyACM0 flash-dfu
+```
+
+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

boards/feather-nrf52840/reset.c → boards/common/adafruit-nrf52-bootloader/reset.c

@@ -7,10 +7,10 @@
  */
 
 /**
- * @ingroup     boards_feather-nrf52840
+ * @ingroup     boards_common_adafruit-nrf52-bootloader
  * @{
  * @file
- * @brief       Implementation for managing the nrfutil bootloader
+ * @brief       Reset Logic for the Adafruit nRF52 Bootloader
  *
  * @author      Alexandre Abadie <[email protected]>
  *

boards/feather-nrf52840-sense/Makefile

@@ -1,3 +1,8 @@
 MODULE = board
 
+ifneq (,$(filter boards_common_adafruit-nrf52-bootloader,$(USEMODULE)))
+  # add the adafruit-nrf52-bootloader directory to the build
+  DIRS += $(RIOTBOARD)/common/adafruit-nrf52-bootloader
+endif
+
 include $(RIOTBASE)/Makefile.base

boards/feather-nrf52840-sense/Makefile.dep

@@ -9,6 +9,8 @@ ifneq (,$(filter saul_default,$(USEMODULE)))
   USEMODULE += ws281x
 endif
 
+# include common Adafruit nRF52 Bootloader dependencies
+include $(RIOTBOARD)/common/adafruit-nrf52-bootloader/Makefile.dep
+
 # include common nrf52 dependencies
-include $(RIOTBOARD)/common/nrf52/bootloader_nrfutil.dep.mk
 include $(RIOTBOARD)/common/nrf52/Makefile.dep

boards/feather-nrf52840-sense/Makefile.include

@@ -0,0 +1,4 @@
+UF2_SOFTDEV ?= SD611
+
+# Include the common definitions for the Adafruit nRF52 Bootloader
+include $(RIOTBOARD)/common/adafruit-nrf52-bootloader/Makefile.include

boards/feather-nrf52840-sense/doc.txt → boards/feather-nrf52840-sense/doc.md

@@ -1,4 +1,3 @@
-/**
 @defgroup    boards_feather-nrf52840-sense Adafruit Feather nRF52840 Sense
 @ingroup     boards
 @brief       Support for the Adafruit Feather nRF52840 Sense
@@ -20,33 +19,12 @@ Low Energy and IEEE 802.15.4 support via the nRF52840 MCU.
 
 ### Flashing, Bootloader, and Terminal
 
-Refer to the [Feather nRF52840 Express
-documentation](https://doc.riot-os.org/group__boards__feather-nrf52840.html) for further details.
+Refer to the [Feather nRF52840 Express](@ref boards_feather-nrf52840) documentation for further details.
+Details to the Flashing process can be found in the common
+[Adafruit nRF52 Bootloader](@ref boards_common_adafruit-nrf52-bootloader) documentation.
 Both use the same flasher, bootloader, and terminal settings.
 
 Example with `hello-world` application:
 ```
      make BOARD=feather-nrf52840-sense -C examples/basic/hello-world flash term
 ```
-
-On "fresh" boards the
-[bootloader may need to be updated](https://learn.adafruit.com/adafruit-feather-sense/update-bootloader).
-
-#### Updating Old Bootloaders
-
-In some cases the bootloader may be too old to even mount on startup.
-Double tap the reset button to get into bootloader mode 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.
-
-For example, one can run the following if `arm-none-eabi-gcc` and
-`adafruit-nrfutil` are installed:
-```
-git clone https://github.com/adafruit/Adafruit_nRF52_Bootloader.git
-cd Adafruit_nRF52_Bootloader
-git submodule update --init
-make BOARD=feather_nrf52840_sense SERIAL=/dev/ttyACM0 flash-dfu
-```
-*/

boards/feather-nrf52840/Makefile

@@ -1,3 +1,8 @@
 MODULE = board
 
+ifneq (,$(filter boards_common_adafruit-nrf52-bootloader,$(USEMODULE)))
+  # add the adafruit-nrf52-bootloader directory to the build
+  DIRS += $(RIOTBOARD)/common/adafruit-nrf52-bootloader
+endif
+
 include $(RIOTBASE)/Makefile.base

boards/feather-nrf52840/Makefile.dep

@@ -4,6 +4,8 @@ ifneq (,$(filter saul_default,$(USEMODULE)))
   USEMODULE += ws281x
 endif
 
+# include common Adafruit nRF52 Bootloader dependencies
+include $(RIOTBOARD)/common/adafruit-nrf52-bootloader/Makefile.dep
+
 # include common nrf52 dependencies
-include $(RIOTBOARD)/common/nrf52/bootloader_nrfutil.dep.mk
 include $(RIOTBOARD)/common/nrf52/Makefile.dep

boards/feather-nrf52840/Makefile.include

@@ -1,29 +1,4 @@
-PROGRAMMER ?= uf2conv
+UF2_SOFTDEV ?= SD611
 
-UF2CONV_FLAGS = -f 0xADA52840
-
-ifeq (uf2conv,$(PROGRAMMER))
-
-  # Using uf2conv implies using the UF2 bootloader
-  #
-  # It has a static MBR at the first 4k, and a 38k UF2 Bootloader at
-  # the end, leaving 972k for the application. This overwrites any SoftDevice,
-  # but that's what the minimal working example does as well.
-  ROM_OFFSET = 0x1000
-  ROM_LEN    = 0xf3000
-
-  # Driver can take some time to get mounted
-  PREFLASH_DELAY ?= 3
-  include $(RIOTMAKE)/tools/usb_board_reset.mk
-endif
-
-PROGRAMMERS_SUPPORTED += uf2conv
-
-# HACK: replicate dependency resolution in Makefile.dep, only works
-# if `USEMODULE` or `DEFAULT_MODULE` is set by the command line or in the
-# application Makefile.
-ifeq (,$(filter stdio_%,$(DISABLE_MODULE) $(USEMODULE)))
-  RIOT_TERMINAL ?= jlink
-endif
-
-include $(RIOTBOARD)/common/nrf52/Makefile.include
+# Include the common definitions for the Adafruit nRF52 Bootloader
+include $(RIOTBOARD)/common/adafruit-nrf52-bootloader/Makefile.include

boards/feather-nrf52840/doc.md

@@ -0,0 +1,37 @@
+@defgroup    boards_feather-nrf52840 Adafruit Feather nRF52840 Express
+@ingroup     boards
+@brief       Support for the Adafruit Feather nRF52840 Express
+
+### General information
+
+The [Feather nRF52840 Express][feather-nrf52840] is a development board
+from Adafruits Feather board family. It provides native USB support, Bluetooth
+Low Energy and IEEE 802.15.4 support via the nRF52840 MCU.
+
+<img src="https://cdn-learn.adafruit.com/assets/assets/000/068/578/medium800/circuitpython_Screenshot_2019-01-02_at_12.04.27.png"
+     alt="top-down view on feather-nrf52840" width="50%"/>
+
+[feather-nrf52840]: https://learn.adafruit.com/introducing-the-adafruit-nrf52840-feather/
+
+### Flash the board
+
+Flashing the Feather nRF52840 is described in the
+common [Adafruit nRF52 Bootloader](@ref boards_common_adafruit-nrf52-bootloader) section.
+
+### Terminal
+To connect a terminal to the Feather, RIOT chooses `stdio_cdc_acm` per default.
+This lets you access the Feather directly over USB.
+
+You have several alternative possibilities to connect to the board.
+
+1. With
+   ~~~~~~~~~~~~~~~~~~~~~ {.mk}
+   USEMODULE += stdio_uart
+   ~~~~~~~~~~~~~~~~~~~~~
+   and an FTDI adapter connected to the Feather's RX and TX ports you can use
+   UART-based terminals to connect to the feather
+2. With
+   ~~~~~~~~~~~~~~~~~~~~~ {.mk}
+   USEMODULE += stdio_rtt
+   ~~~~~~~~~~~~~~~~~~~~~
+   you can use the Segger J-Link Programmer as a serial interface to the device.