From f9b0cc77110d2e6889dfa6e6e0ee8181d3a95e6d Mon Sep 17 00:00:00 2001 From: crasbe Date: Wed, 9 Apr 2025 20:57:46 +0200 Subject: [PATCH 1/5] boards/adafruit-{clue,itsybitsy-nrf52}: convert to common Ada nRF52 BL The Adafruit Clue and Itsybitsy nRF52 also use the Adafruit nRF52 Bootloader which has a common module that can be used. Especially the Itsybitsy nRF52 (mis)uses the nrfutil programmer target and has a lot of redundant code. Furthermore, the Double Tap Magic Value used by both boards is incorrect for using the USB Bootloader. --- boards/adafruit-clue/Makefile.dep | 3 +- boards/adafruit-clue/Makefile.include | 13 +------ boards/adafruit-clue/reset.c | 38 ------------------- boards/adafruit-itsybitsy-nrf52/Makefile.dep | 3 +- .../adafruit-itsybitsy-nrf52/Makefile.include | 32 +--------------- boards/adafruit-itsybitsy-nrf52/reset.c | 34 ----------------- .../Makefile.include | 9 ++++- makefiles/tools/adafruit-nrfutil.inc.mk | 2 +- 8 files changed, 15 insertions(+), 119 deletions(-) delete mode 100644 boards/adafruit-clue/reset.c delete mode 100644 boards/adafruit-itsybitsy-nrf52/reset.c diff --git a/boards/adafruit-clue/Makefile.dep b/boards/adafruit-clue/Makefile.dep index 501bf04aaa..cce31149ca 100644 --- a/boards/adafruit-clue/Makefile.dep +++ b/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 diff --git a/boards/adafruit-clue/Makefile.include b/boards/adafruit-clue/Makefile.include index 5bff4c0f44..e195a21c43 100644 --- a/boards/adafruit-clue/Makefile.include +++ b/boards/adafruit-clue/Makefile.include @@ -1,12 +1 @@ -# Adafruit-nrfutil is the default programmer -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 +UF2_SOFTDEV = SD611 diff --git a/boards/adafruit-clue/reset.c b/boards/adafruit-clue/reset.c deleted file mode 100644 index 29b4b3b673..0000000000 --- a/boards/adafruit-clue/reset.c +++ /dev/null @@ -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 - * - * @} - */ - -#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 */ diff --git a/boards/adafruit-itsybitsy-nrf52/Makefile.dep b/boards/adafruit-itsybitsy-nrf52/Makefile.dep index b72178a1f7..8a628db37c 100644 --- a/boards/adafruit-itsybitsy-nrf52/Makefile.dep +++ b/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 diff --git a/boards/adafruit-itsybitsy-nrf52/Makefile.include b/boards/adafruit-itsybitsy-nrf52/Makefile.include index b2e3879967..35bb08f1c2 100644 --- a/boards/adafruit-itsybitsy-nrf52/Makefile.include +++ b/boards/adafruit-itsybitsy-nrf52/Makefile.include @@ -1,31 +1 @@ -# This board uses the vendor's serial bootloader - -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 +UF2_SOFTDEV ?= SD611 diff --git a/boards/adafruit-itsybitsy-nrf52/reset.c b/boards/adafruit-itsybitsy-nrf52/reset.c deleted file mode 100644 index 09b64e4a49..0000000000 --- a/boards/adafruit-itsybitsy-nrf52/reset.c +++ /dev/null @@ -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 */ diff --git a/boards/common/adafruit-nrf52-bootloader/Makefile.include b/boards/common/adafruit-nrf52-bootloader/Makefile.include index 8cb74f6f37..73151afe87 100644 --- a/boards/common/adafruit-nrf52-bootloader/Makefile.include +++ b/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 diff --git a/makefiles/tools/adafruit-nrfutil.inc.mk b/makefiles/tools/adafruit-nrfutil.inc.mk index 73c395faf2..8e427f3a66 100644 --- a/makefiles/tools/adafruit-nrfutil.inc.mk +++ b/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 $< $@ From 296d9b194900ed3f93db5586cc62d8f70c5867ea Mon Sep 17 00:00:00 2001 From: crasbe Date: Sat, 12 Apr 2025 22:26:38 +0200 Subject: [PATCH 2/5] boards/adafriot-{clue,itsybitsy-nrf52}: change doc.txt to Markdown --- boards/adafruit-clue/{doc.txt => doc.md} | 2 -- boards/adafruit-itsybitsy-nrf52/{doc.txt => doc.md} | 3 --- 2 files changed, 5 deletions(-) rename boards/adafruit-clue/{doc.txt => doc.md} (99%) rename boards/adafruit-itsybitsy-nrf52/{doc.txt => doc.md} (99%) diff --git a/boards/adafruit-clue/doc.txt b/boards/adafruit-clue/doc.md similarity index 99% rename from boards/adafruit-clue/doc.txt rename to boards/adafruit-clue/doc.md index 72a6958561..e14598a5f2 100644 --- a/boards/adafruit-clue/doc.txt +++ b/boards/adafruit-clue/doc.md @@ -1,4 +1,3 @@ -/** @defgroup boards_adafruit-clue Adafruit Clue @ingroup boards @brief Support for the Adafruit Clue @@ -42,4 +41,3 @@ Use the `term` target to connect to the board serial port
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. - */ diff --git a/boards/adafruit-itsybitsy-nrf52/doc.txt b/boards/adafruit-itsybitsy-nrf52/doc.md similarity index 99% rename from boards/adafruit-itsybitsy-nrf52/doc.txt rename to boards/adafruit-itsybitsy-nrf52/doc.md index f0a7cebf03..d94d11b77e 100644 --- a/boards/adafruit-itsybitsy-nrf52/doc.txt +++ b/boards/adafruit-itsybitsy-nrf52/doc.md @@ -1,4 +1,3 @@ -/** @defgroup boards_adafruit-itsybitsy-nrf52 Adafruit-Itsybitsy-nRF52 @ingroup boards @brief Support for the Adafruit-Itsybitsy-nRF52 @@ -41,5 +40,3 @@ you may need to run `pip3 install --upgrade pip3` before being able to run `pip3 ### Accessing STDIO The usual way to obtain a console on this board is using an emulated USB serial port. - - */ From 4ee42929f00da1072a52389439978f204364f16a Mon Sep 17 00:00:00 2001 From: crasbe Date: Sat, 12 Apr 2025 22:51:14 +0200 Subject: [PATCH 3/5] boards/ada-nrf52-bl: add documentation about ada-nrfutil --- .../common/adafruit-nrf52-bootloader/doc.md | 30 +++++++++++++++++-- doc/doxygen/src/flashing.md | 3 +- 2 files changed, 29 insertions(+), 4 deletions(-) diff --git a/boards/common/adafruit-nrf52-bootloader/doc.md b/boards/common/adafruit-nrf52-bootloader/doc.md index ff1d43f4df..13820ebeb5 100644 --- a/boards/common/adafruit-nrf52-bootloader/doc.md +++ b/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 @@ -65,6 +71,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 +111,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 diff --git a/doc/doxygen/src/flashing.md b/doc/doxygen/src/flashing.md index 50f7e3366e..c211943af8 100644 --- a/doc/doxygen/src/flashing.md +++ b/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 From cebe693556e047c6de0cccb0e3f1346aa71a1a01 Mon Sep 17 00:00:00 2001 From: crasbe Date: Sat, 12 Apr 2025 22:51:50 +0200 Subject: [PATCH 4/5] boards/ada-{clue,itsybitsy-nrf52}: update flashing doc --- boards/adafruit-clue/doc.md | 17 ++++------------- boards/adafruit-itsybitsy-nrf52/doc.md | 24 ++++-------------------- 2 files changed, 8 insertions(+), 33 deletions(-) diff --git a/boards/adafruit-clue/doc.md b/boards/adafruit-clue/doc.md index e14598a5f2..6f424d7143 100644 --- a/boards/adafruit-clue/doc.md +++ b/boards/adafruit-clue/doc.md @@ -18,15 +18,10 @@ The board detailed description and schematic is available ### Flash the board -The board is flashed using the `adafruit-nrfutil` Python package: -``` - $ pip install --user adafruit-nrfutil -``` - -Example with `hello-world` application: -``` - make BOARD=adafruit-clue -C examples/basic/hello-world flash -``` +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 via UART @@ -37,7 +32,3 @@ Use the `term` target to connect to the board serial port
``` 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. diff --git a/boards/adafruit-itsybitsy-nrf52/doc.md b/boards/adafruit-itsybitsy-nrf52/doc.md index d94d11b77e..8730f28091 100644 --- a/boards/adafruit-itsybitsy-nrf52/doc.md +++ b/boards/adafruit-itsybitsy-nrf52/doc.md @@ -16,26 +16,10 @@ reset button as well as 21 configurable external pins(6 of which can be analog i ### 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. +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 From a7536df2ca3de71494bcaf03cbb69c3092ae7bc0 Mon Sep 17 00:00:00 2001 From: crasbe Date: Wed, 7 May 2025 16:28:40 +0200 Subject: [PATCH 5/5] boards/ada-nrf52-bl: add note about Automounting for uf2conv --- boards/common/adafruit-nrf52-bootloader/doc.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/boards/common/adafruit-nrf52-bootloader/doc.md b/boards/common/adafruit-nrf52-bootloader/doc.md index 13820ebeb5..56f01e86fb 100644 --- a/boards/common/adafruit-nrf52-bootloader/doc.md +++ b/boards/common/adafruit-nrf52-bootloader/doc.md @@ -52,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