mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2025-12-16 10:03:50 +01:00
Merge pull request #21395 from crasbe/pr/ada-nrfutil
boards/adafruit-{clue,itsybitsy-nrf52}: Convert to Common `adafruit-nrf52-bootloader` module
This commit is contained in:
Marian Buschsieweke
GitHub
commit
098bc8de64
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
*/
|
||||
@ -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 */
|
||||
@ -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
|
||||
|
||||
@ -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
26
boards/adafruit-itsybitsy-nrf52/doc.md
Normal 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.
|
||||
@ -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.
|
||||
|
||||
*/
|
||||
@ -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 */
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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 $< $@
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user