Merge pull request #21395 from crasbe/pr/ada-nrfutil

boards/adafruit-{clue,itsybitsy-nrf52}: Convert to Common `adafruit-nrf52-bootloader` module

boards/adafruit-clue/Makefile.dep

@@ -10,5 +10,6 @@ ifneq (,$(filter disp_dev,$(USEMODULE)))
   USEMODULE += ili9341
 endif
 
-include $(RIOTBOARD)/common/nrf52/bootloader_nrfutil.dep.mk
+USEMODULE += boards_common_adafruit-nrf52-bootloader
+
 include $(RIOTBOARD)/common/nrf52/Makefile.dep

boards/adafruit-clue/Makefile.include

@@ -1,12 +1 @@
-# Adafruit-nrfutil is the default programmer
+UF2_SOFTDEV = SD611
-PROGRAMMER ?= adafruit-nrfutil
-
-include $(RIOTBOARD)/common/nrf52/Makefile.include
-PROGRAMMERS_SUPPORTED += adafruit-nrfutil
-
-ifeq ($(PROGRAMMER),adafruit-nrfutil)
-  # The preinstalled bootloader must also be taken into account so
-  # ROM_OFFSET skips the space taken by such bootloader.
-  ROM_OFFSET = 0x26000
-  include $(RIOTMAKE)/tools/usb_board_reset.mk
-endif

boards/adafruit-clue/doc.md

@@ -1,4 +1,3 @@
-/**
 @defgroup    boards_adafruit-clue Adafruit Clue
 @ingroup     boards
 @brief       Support for the Adafruit Clue
@@ -19,15 +18,10 @@ The board detailed description and schematic is available
 
 ### Flash the board
 
-The board is flashed using the `adafruit-nrfutil` Python package:
+The board is flashed using its on-board
-```
+[bootloader](https://github.com/adafruit/Adafruit_nRF52_Bootloader).
-    $ pip install --user adafruit-nrfutil
+More information about how to work with this bootloader can be found in the
-```
+@ref boards_common_adafruit-nrf52-bootloader section.
-
-Example with `hello-world` application:
-```
-    make BOARD=adafruit-clue -C examples/basic/hello-world flash
-```
 
 ### Accessing STDIO via UART
 
@@ -38,8 +32,3 @@ Use the `term` target to connect to the board serial port<br/>
 ```
     make BOARD=adafruit-clue -C examples/basic/hello-world term
 ```
-
-The `TERM_DELAY` environment variable can be used to add a delay (in second)
-before opening the serial terminal. The default value is 2s which should be
-enough in most of the situations.
- */

boards/adafruit-clue/reset.c

@@ -1,38 +0,0 @@
-/*
- * Copyright (C)  2020 Inria
- *
- * This file is subject to the terms and conditions of the GNU Lesser
- * General Public License v2.1. See the file LICENSE in the top level
- * directory for more details.
- */
-
-/**
- * @ingroup     boards_adafruit-clue
- * @{
- * @file
- * @brief       Implementation for managing the nrfutil bootloader
- *
- * @author      Alexandre Abadie <alexandre.abadie@inria.fr>
- *
- * @}
- */
-
-#ifdef MODULE_USB_BOARD_RESET
-
-#define USB_H_USER_IS_RIOT_INTERNAL
-
-#include "cpu.h"
-#include "usb_board_reset.h"
-
-/* Set the value used by the bootloader to select between boot in
-   application and boot in bootloader mode. */
-#define NRF52_DOUBLE_TAP_MAGIC_NUMBER       (0x4e)
-
-void usb_board_reset_in_bootloader(void)
-{
-    NRF_POWER->GPREGRET = NRF52_DOUBLE_TAP_MAGIC_NUMBER;
-
-    usb_board_reset_in_application();
-}
-
-#endif /* MODULE_USB_BOARD_RESET */

boards/adafruit-itsybitsy-nrf52/Makefile.dep

@@ -2,5 +2,6 @@ ifneq (,$(filter saul_default,$(USEMODULE)))
   USEMODULE += saul_gpio
 endif
 
-include $(RIOTBOARD)/common/nrf52/bootloader_nrfutil.dep.mk
+USEMODULE += boards_common_adafruit-nrf52-bootloader
+
 include $(RIOTBOARD)/common/nrf52/Makefile.dep

boards/adafruit-itsybitsy-nrf52/Makefile.include

@@ -1,31 +1 @@
-# This board uses the vendor's serial bootloader
+UF2_SOFTDEV ?= SD611
-
-PROGRAMMER ?= nrfutil
-
-ifeq (nrfutil,$(PROGRAMMER))
-
-  # For this board it is required to use Adafruit's implementation of nrfutil.
-  # https://github.com/adafruit/Adafruit_nRF52_nrfutil
-  #
-  # This boards comes with Adafruit's bootloader:
-  # https://github.com/adafruit/Adafruit_nRF52_Bootloader
-  # In order to burn the application in the correct location, a offset of
-  # 0x26000 is required
-
-  ROM_OFFSET = 0x26000
-  ROM_LEN = 0xda000
-
-  FLASHFILE = $(HEXFILE)
-  FLASHDEPS += $(HEXFILE).zip
-  FLASHER = adafruit-nrfutil
-  FFLAGS = --verbose dfu serial -p ${PORT} -b 115200 --singlebank --package=$(HEXFILE).zip
-
-  include $(RIOTMAKE)/tools/usb_board_reset.mk
-endif
-
-%.hex.zip: %.hex
-	$(call check_cmd,$(FLASHER),Flash program and preparation tool)
-	$(FLASHER) dfu genpkg --dev-type 0x0052 --sd-req 0x00B6 --application $< $@
-
-include $(RIOTBOARD)/common/nrf52/Makefile.include
-PROGRAMMERS_SUPPORTED += nrfutil

boards/adafruit-itsybitsy-nrf52/doc.md

@@ -0,0 +1,26 @@
+@defgroup    boards_adafruit-itsybitsy-nrf52 Adafruit-Itsybitsy-nRF52
+@ingroup     boards
+@brief       Support for the Adafruit-Itsybitsy-nRF52
+
+### General information
+
+This is a small formfactor (only 1.4\" long by 0.7\" wide) nRF52840 board made by Adafruit.
+
+The board features one red LED (LD1), one DotStar / APA102 RGB LED, a user (SW1), a
+reset button as well as 21 configurable external pins(6 of which can be analog in).
+
+### Links
+
+- [Overview](https://learn.adafruit.com/adafruit-itsybitsy-nrf52840-express?view=all)
+- [Pinouts](https://learn.adafruit.com/adafruit-itsybitsy-nrf52840-express/pinouts)
+
+### Flash the board
+
+The board is flashed using its on-board
+[bootloader](https://github.com/adafruit/Adafruit_nRF52_Bootloader).
+More information about how to work with this bootloader can be found in the
+@ref boards_common_adafruit-nrf52-bootloader section.
+
+### Accessing STDIO
+
+The usual way to obtain a console on this board is using an emulated USB serial port.

boards/adafruit-itsybitsy-nrf52/doc.txt

@@ -1,45 +0,0 @@
-/**
-@defgroup    boards_adafruit-itsybitsy-nrf52 Adafruit-Itsybitsy-nRF52
-@ingroup     boards
-@brief       Support for the Adafruit-Itsybitsy-nRF52
-
-### General information
-
-This is a small formfactor (only 1.4\" long by 0.7\" wide) nRF52840 board made by Adafruit.
-
-The board features one red LED (LD1), one DotStar / APA102 RGB LED, a user (SW1), a
-reset button as well as 21 configurable external pins(6 of which can be analog in).
-
-### Links
-
-- [Overview](https://learn.adafruit.com/adafruit-itsybitsy-nrf52840-express?view=all)
-- [Pinouts](https://learn.adafruit.com/adafruit-itsybitsy-nrf52840-express/pinouts)
-
-### Flash the board
-
-The board is flashed using its on-board [boot loader](https://github.com/adafruit/Adafruit_nRF52_Bootloader).
-Adafruit has a special version of the [nrfutil](https://github.com/adafruit/Adafruit_nRF52_nrfutil) that program needs to
-be installed. It can turn the binary into a suitable zip file and send it to the DFU
-bootloader.
-
-The process is automated in the usual `make flash` target.
-
-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.
-
-Readiness of the bootloader is indicated by LD1 pulsing in blue.
-
-Important to note that Adafruit's nrfutil is not compatible with Nordic's nrfutil.
-
-#### nrfutil installation
-
-On systems with Python 3, a recent version of pip is required to install all dependencies;
-you may need to run `pip3 install --upgrade pip3` before being able to run `pip3 install adafruit-nrfutil` successfully.
-
-### Accessing STDIO
-
-The usual way to obtain a console on this board is using an emulated USB serial port.
-
- */

boards/adafruit-itsybitsy-nrf52/reset.c

@@ -1,34 +0,0 @@
-/*
- * Copyright (C)  2020 Bruno Chianca
- *
- * This file is subject to the terms and conditions of the GNU Lesser
- * General Public License v2.1. See the file LICENSE in the top level
- * directory for more details.
- */
-
-/**
- * @ingroup     boards_adafruit-itsybitsy-nrf52
- * @{
- * @file
- * @brief       Allows reboot into bootloader via prompt
- *
- * @author      Bruno Chianca
- *
- * @}
- */
-
-#ifdef MODULE_USB_BOARD_RESET
-
-#include "periph/gpio.h"
-#include "usb_board_reset.h"
-
-#define NRF52_DOUBLE_TAP_MAGIC_NUMBER       (0x4e)
-
-void usb_board_reset_in_bootloader(void)
-{
-    NRF_POWER->GPREGRET = NRF52_DOUBLE_TAP_MAGIC_NUMBER;
-
-    usb_board_reset_in_application();
-}
-
-#endif /* MODULE_USB_BOARD_RESET */

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

@@ -1,12 +1,13 @@
 PROGRAMMER ?= uf2conv
 
-ifneq (,$(filter uf2conv,$(PROGRAMMER)))
+ifneq (,$(filter uf2conv adafruit-nrfutil,$(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
+    ADANRFUTIL_FLAGS = --dev-type 0x0052
 
     # 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
@@ -22,10 +23,12 @@ ifneq (,$(filter uf2conv,$(PROGRAMMER)))
     else ifneq (,$(filter SD611,$(UF2_SOFTDEV)))
       ROM_OFFSET = 0x26000
       ROM_LEN    = 0x5a000
+      ADANRFUTIL_FLAGS += --sd-req 0x00B6
 
     else ifneq (,$(filter SD730,$(UF2_SOFTDEV)))
       ROM_OFFSET = 0x27000
       ROM_LEN    = 0x59000
+      ADANRFUTIL_FLAGS += --sd-req 0x0123
 
     else
       $(error Unsupported SoftDevice Version $(UF2_SOFTDEV).)
@@ -33,6 +36,7 @@ ifneq (,$(filter uf2conv,$(PROGRAMMER)))
 
   else ifneq (,$(filter nrf52840xxaa,$(CPU_MODEL)))
     UF2CONV_FLAGS = -f 0xADA52840
+    ADANRFUTIL_FLAGS = --dev-type 0x0052
 
     ifneq (,$(filter DROP,$(UF2_SOFTDEV)))
       ROM_OFFSET = 0x1000
@@ -41,10 +45,12 @@ ifneq (,$(filter uf2conv,$(PROGRAMMER)))
     else ifneq (,$(filter SD611,$(UF2_SOFTDEV)))
       ROM_OFFSET = 0x26000
       ROM_LEN    = 0xda000
+      ADANRFUTIL_FLAGS += --sd-req 0x00B6
 
     else ifneq (,$(filter SD730,$(UF2_SOFTDEV)))
       ROM_OFFSET = 0x27000
       ROM_LEN    = 0xd9000
+      ADANRFUTIL_FLAGS += --sd-req 0x0123
 
     else
       $(error Unsupported SoftDevice Version $(UF2_SOFTDEV).)
@@ -60,6 +66,7 @@ ifneq (,$(filter uf2conv,$(PROGRAMMER)))
 endif
 
 PROGRAMMERS_SUPPORTED += uf2conv
+PROGRAMMERS_SUPPORTED += adafruit-nrfutil
 
 # HACK: replicate dependency resolution in Makefile.dep, only works
 # if `USEMODULE` or `DEFAULT_MODULE` is set by the command line or in the

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

@@ -9,12 +9,16 @@ 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.
+necessary for the normal usage. The tool used for flashing the board with
+UF2 files via the Mass Storage Device is `uf2conv` from the [Microsoft UF2
+Reference Repository](https://github.com/microsoft/uf2).
 
 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.
+If the version is less than `0.4.0`, please refer to @ref ada-nrf52-update or
+use the [`adafruit-nrfutil` Script](@ref ada-nrf52-adafruit-nrfutil) to
+program your board.
 
 Until and including RIOT Release 2025.01, the SoftDevice on
 [`adafruit-feather-nrf52840-express`](@ref boards_adafruit-feather-nrf52840-express)
@@ -28,6 +32,8 @@ such as the J-Link has to be used. Please refer to @ref ada-nrf52-reflashing.
 
 ## Flashing the Board with RIOT
 
+### Using the default `uf2conv` Programmer
+
 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
@@ -46,6 +52,12 @@ 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.
 
+@note Some distributions do not setup automounting in the default installation.
+The bootloader emulates a mass storage device which the `uf2conv` script searches
+for in common mounting locations. If the device is not mounted, the flashing
+process fails. Please configure automounting in this case or refer to the
+[`adafruit-nrfutil` Programmer](@ref ada-nrf52-adafruit-nrfutil).
+
 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
@@ -65,6 +77,24 @@ 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!**
 
+### Using the `adafruit-nrfutil` Programmer {#ada-nrf52-adafruit-nrfutil}
+
+The `adafruit-nrfutil` is an adapted version of the original, discontinuied
+`nrfutil` script from Nordic Semiconductor and programs the nRF52
+microcontroller via DFU (Direct File Upload) via the serial port or via USB.
+If you want to use the `adafruit-nrfutil` programming script, most of the
+previous information about the `uf2conv` script applies as well.
+Before using the script, you have to install it with the following command:
+```sh
+pip3 install --user adafruit-nrfutil
+```
+
+To select the `adafruit-nrfutil`, you can define the programmer in the
+environment when you call `make`:
+```sh
+PROGRAMMER=adafruit-nrfutil BOARD=adafruit-feather-nrf52840-express -C examples/basic/hello-world flash term
+```
+
 ## Updating Old Bootloaders and Restoring the SoftDevice {#ada-nrf52-update}
 
 If the Adafruit nRF52 Bootloader is still present on the board but outdated
@@ -87,7 +117,7 @@ repository](https://github.com/adafruit/Adafruit_nRF52_Bootloader).
 With the following commands, the bootloader with SoftDevice will be compiled
 and flashed. For MacOS, you might have to select a different serial port.
 
-```
+```sh
 git clone https://github.com/adafruit/Adafruit_nRF52_Bootloader.git
 cd Adafruit_nRF52_Bootloader
 git submodule update --init

doc/doxygen/src/flashing.md

@@ -109,8 +109,9 @@ support multiple platforms are given in section
 
 ### nRF52
 
-- `adafruit-nrfutil` (requires Adafruit bootloader)
+- `adafruit-nrfutil`, `uf2conv` (requires Adafruit bootloader), see @ref boards_common_adafruit-nrf52-bootloader
 - `nrfutil` (required nRF bootloader)
+- `nrfjprog` (requires a separate J-Link debugger)
 
 ### RP2040
 

makefiles/tools/adafruit-nrfutil.inc.mk

@@ -5,4 +5,4 @@ FFLAGS = dfu serial --port=${PORT} --baudrate=${BAUD} --touch=1200 --package=$(H
 
 %.hex.zip: %.hex
 	$(call check_cmd,$(FLASHER),Flash program and preparation tool)
-	$(FLASHER) dfu genpkg --dev-type 0x0052 --sd-req 0x00B6 --application $< $@
+	$(FLASHER) dfu genpkg $(ADANRFUTIL_FLAGS) --application $< $@