kaspar/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2025-12-16 01:53:51 +01:00
Code Releases Activity

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

Browse Source 
boards/adafruit-{clue,itsybitsy-nrf52}: Convert to Common `adafruit-nrf52-bootloader` module
This commit is contained in:
Marian Buschsieweke 2025-05-08 09:33:31 +00:00 committed by GitHub
commit 098bc8de64
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
13 changed files with 80 additions and 183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
boards/adafruit-clue/Makefile.dep
View File

@ -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

13
boards/adafruit-clue/Makefile.include
View File

@ -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

19
boards/adafruit-clue/doc.txt → boards/adafruit-clue/doc.md
View File

@ -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:
```
$ 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
@ -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.
*/

38
boards/adafruit-clue/reset.c
View File

@ -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 */

3
boards/adafruit-itsybitsy-nrf52/Makefile.dep
View File

@ -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

32
boards/adafruit-itsybitsy-nrf52/Makefile.include
View File

@ -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

26
boards/adafruit-itsybitsy-nrf52/doc.md Normal file
View File

@ -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.

45
boards/adafruit-itsybitsy-nrf52/doc.txt
View File

@ -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.
*/

34
boards/adafruit-itsybitsy-nrf52/reset.c
View File

@ -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 */

9
boards/common/adafruit-nrf52-bootloader/Makefile.include
View File

@ -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

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

@ -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

3
doc/doxygen/src/flashing.md
View File

@ -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

2
makefiles/tools/adafruit-nrfutil.inc.mk
View File

@ -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 $< $@