Skip to content

boards/nrf52840dongle: Support a FLOSS programmer #21466

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chrysn wants to merge 4 commits into
base: master
Choose a base branch
from
Open

boards/nrf52840dongle: Support a FLOSS programmer #21466

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7cefa6d
boards/nrf52840dongle: Add support for nrfdfu programmer
chrysn May 6, 2025
ad61b52
boards/nrf52840dongle: Use nrfdfu programmer by default
chrysn May 7, 2025
972e25a
boards/nrf52840dongle: Document free programmer
chrysn May 6, 2025
11e54b0
boards/nrf52840dongle: Documentation precision for nrfutil
chrysn May 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 19 additions & 8 deletions boards/nrf52840dongle/Makefile.include
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,26 @@
# This board uses the vendor's serial bootloader

PROGRAMMER ?= nrfutil
PROGRAMMER ?= nrfdfu

ifeq (nrfutil,$(PROGRAMMER))
USING_NRF_BOOTLOADER = 1

# Using nrfutil implies using the Nordic bootloader described at
FLASHFILE = $(HEXFILE)
FLASHDEPS += $(HEXFILE).zip
FLASHER = nrfutil
FFLAGS = dfu usb-serial --port=${PORT} --package=$(HEXFILE).zip
Copy link
Copy Markdown
Contributor

@crasbe crasbe May 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
FFLAGS = dfu usb-serial --port=${PORT} --package=$(HEXFILE).zip
FFLAGS = dfu usb-serial --port=$(PORT) --package=$(HEXFILE).zip

Copy link
Copy Markdown
Member Author

@chrysn chrysn May 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd rather leave it as is in this commit so that it is visible in the commit that this line was not modified. (The GitHub diff settings choice mark it as a new line, but eg. a git diff color-moved does show those as unmodified).

endif

ifeq (nrfdfu,$(PROGRAMMER))
USING_NRF_BOOTLOADER = 1

FLASHFILE = $(ELFFILE)
FLASHER = nrfdfu
FFLAGS = $(FLASHFILE)
endif

ifeq (1,$(USING_NRF_BOOTLOADER))
Copy link
Copy Markdown
Contributor

@crasbe crasbe May 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
ifeq (1,$(USING_NRF_BOOTLOADER))
ifneq (,$(filter nrfutil nrfdfu,$(PROGARMMER)))

Since the number of programmer variants is very limited (two), we could omit the extra variable here.
NRF_BOOTLOADER might be misleading, since there is (at least) one other bootloader for the nRFs, the Adafruit nRF52 Bootloader.

Copy link
Copy Markdown
Member Author

@chrysn chrysn May 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there is value to having this independent, because it could also be used with an external programmer but leaving the bootloader in place.

Even if you accept that rationale, let's leave this open for the naming issue. I think that the adafruit bootloader is similar enough, but I'll want to check that anyway while looking at knurling-rs/nrfdfu-rs#16, and then I'll see if there is a better name to use here.

Copy link
Copy Markdown
Contributor

@crasbe crasbe May 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a valid point, but then the parameter must be documented somewhere.

There is a similar parameter for the Adafruit nRF52 Bootloader called UF2_SOFTDEV to keep the SoftDevice in place. However that wouldn't protect the Bootloader from overriding with a JLink.

# Using an nrfutil style flasher implies using the Nordic bootloader described at
# <https://devzone.nordicsemi.com/nordic/short-range-guides/b/getting-started/posts/nrf52840-dongle-programming-tutorial>.
#
# It has a static MBR at the first 4k, and an ample 128k Open USB Bootloader at
Expand All @@ -14,15 +30,10 @@ ifeq (nrfutil,$(PROGRAMMER))
ROM_OFFSET = 0x1000
ROM_LEN = 0xdf000

FLASHFILE = $(HEXFILE)
FLASHDEPS += $(HEXFILE).zip
FLASHER = nrfutil
FFLAGS = dfu usb-serial --port=${PORT} --package=$(HEXFILE).zip

include $(RIOTMAKE)/tools/usb_board_reset.mk
endif

PROGRAMMERS_SUPPORTED += nrfutil
PROGRAMMERS_SUPPORTED += nrfutil nrfdfu

%.hex.zip: %.hex
$(call check_cmd,$(FLASHER),Flash program and preparation tool)
Expand Down
33 changes: 26 additions & 7 deletions boards/nrf52840dongle/doc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,22 +48,41 @@ reset button as well as 15 configurable external pins.

### Flash the board {#nrf52840dongle_flash}

The board is flashed using its on-board boot loader; the proprietary
The board is flashed using its on-board boot loader
called [Open USB bootloader](https://devzone.nordicsemi.com/nordic/short-range-guides/b/getting-started/posts/nrf52840-dongle-programming-tutorial)
using either of two tools described below.

If RIOT is already running on the board, flashing the device 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 pressing the board's reset button.

Readiness of the bootloader is indicated by LD2 pulsing in red.

#### nrfdfu

The tool [nrfdfu](https://github.com/knurling-rs/nrfdfu-rs/)
is RIOT's default way of flashing a program by sending it to the bootloader.

It needs to be installed locally using `cargo install nrfdfu`.

#### nrfutil

The proprietary
[nrfutil](https://www.nordicsemi.com/Products/Development-tools/nRF-Util) program needs to
be installed, and `nrfutil install nrf5sdk-tools` needs to be executed. Note
that nrfutil, even when not running the "install" command, will install itself
into `~/.nrfutil`. The older Python based version of nrfutil is no longer
maintained by Nordic, and has become dysfunctional on Python 3.11.

The nrfutil can turn the binary into a suitable zip file and send it to the
The nrfutil works in two steps by turning the binary into a zip file and then sending the content of that zip file to the
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 pressing the board's reset button.
#### Other programming methods

Readiness of the bootloader is indicated by LD2 pulsing in red.
When building a program for this board to be flashed using other methods
(e.g. using the board's Tag-Connect footprint),
setting `USING_NRF_BOOTLOADER=1` in the makefiles aligns the program suitable to be flashed after the bootloader.
Comment on lines +83 to +85
Copy link
Copy Markdown
Contributor

@crasbe crasbe May 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't it make sense to set USING_NRF_BOOTLOADER ?= 1 by default and just write something like "if you want to override the original bootloader with external tools, set it to zero.
Warning: you will not be able to program the dogle without external tools anymore. You will have to reflash the original bootloader afterwards."

Copy link
Copy Markdown
Member Author

@chrysn chrysn May 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One has to use an external programmer to lock oneself out, but then I think that working on the full device unless something else is specified is at least consistent with what we had and have in other places.

There are multiple bootloaders, and people do flash other bootloaders in, so I'd say that once a debugger is connected, it's a stretch to assume that the bootloader is still there.

What I would appreciate if we had was a way to say "hey I have this board and a debugger attached, RIOT please undo what you did and do a factory reset", and I'm starting to gather the metadata for that, but that's something bigger.

Copy link
Copy Markdown
Contributor

@crasbe crasbe May 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One should assume that when someone gathers a J-Link and a Tag Connect, that they know what they are doing, indeed.
My personal taste is that it's nicer to explicitly break something rather than implicitly, but I also understand your position.

For reference: Mikolai started working on such an "undo RIOT changes" in #21330 by reflashing the Adafruit Bootloader, but that is riddled by oddities in the adafruit-nrfutil Adafruit nRF52 Bootloader...

Copy link
Copy Markdown
Member Author

@chrysn chrysn May 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, "explicit" would be better, but for now I think we should prioritize "consistent".

(On the long run I'd like to have something like BOOTLOADER along with BOARD, where the former has a default depending on the latter; not sure how to do that switch in a way that it's apparent to all users what is happening).


### Accessing STDIO

Expand Down
2 changes: 1 addition & 1 deletion doc/doxygen/src/flashing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ support multiple platforms are given in section
### nRF52

- `adafruit-nrfutil`, `uf2conv` (requires Adafruit bootloader), see @ref boards_common_adafruit-nrf52-bootloader
- `nrfutil` (required nRF bootloader)
- `nrfdfu` or `nrfutil` (requires nRF bootloader)
- `nrfjprog` (requires a separate J-Link debugger)

### RP2040
Expand Down
Loading