2018-08-07 14:21:12 +00:00
|
|
|
# Adafruit Bluefruit nRF52 Bootloader
|
2018-01-25 10:10:07 +00:00
|
|
|
|
2018-12-04 23:18:49 +00:00
|
|
|
This is a CDC/DFU/UF2 bootloader for nRF52 boards.
|
2018-05-08 15:25:15 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
- [Adafruit Feather nRF52832](https://www.adafruit.com/product/3406)
|
|
|
|
- Adafruit Feather nRF52840 Express
|
2018-08-10 15:15:11 +00:00
|
|
|
- Nordic nRF52840DK PCA10056
|
2018-09-06 17:46:11 +00:00
|
|
|
- Nordic nRF52840DK PCA10059 ("Dongle")
|
2018-12-04 23:18:49 +00:00
|
|
|
- Particle Argon
|
|
|
|
- Particle Boron
|
|
|
|
- Particle Xenon
|
2018-08-07 14:21:12 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
UF2 is an easy-to-use bootloader that appears as a flash drive. You can just copy `.uf2`-format
|
|
|
|
application images to the flash drive to load new firmware.
|
|
|
|
See https://github.com/Microsoft/uf2 and https://github.com/adafruit/uf2-samdx1
|
|
|
|
for more information.
|
2018-08-07 14:21:12 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
[adafruit-nrfutil](https://github.com/adafruit/Adafruit_nRF52_nrfutil),
|
|
|
|
a modified version of [Nordic nrfutil](https://github.com/NordicSemiconductor/pc-nrfutil),
|
|
|
|
is required to perform DFU.
|
|
|
|
Install `python3` if it is not installed already and run this command to install adafruit-nrfutil from PyPi:
|
2018-08-07 14:21:12 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
```
|
|
|
|
$ pip3 install --user adafruit-nrfutil
|
|
|
|
```
|
|
|
|
|
|
|
|
This repository depends on the following submodules:
|
2018-08-07 14:21:12 +00:00
|
|
|
|
|
|
|
- [tinyusb](https://github.com/hathach/tinyusb/tree/develop)
|
|
|
|
- [nrfx](https://github.com/NordicSemiconductor/nrfx)
|
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
Note that `tinyusb` also includes `nrfx` as a submodule, so you need
|
|
|
|
to initialize and update submodules with the `--recursive`` flag.
|
2018-08-07 14:21:12 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
Clone this repo with following commands, or fork it for your own development
|
|
|
|
|
|
|
|
```
|
|
|
|
git clone https://github.com/adafruit/Adafruit_nRF52_Bootloader
|
|
|
|
cd Adafruit_nRF52_Bootloader
|
|
|
|
git submodule update --init --recursive
|
|
|
|
```
|
2018-05-08 15:25:15 +00:00
|
|
|
|
2018-08-10 15:15:11 +00:00
|
|
|
## Features
|
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
- DFU over Serial and OTA ( application, Bootloader+SD )
|
|
|
|
- Self-upgradable via Serial and OTA
|
|
|
|
- DFU using UF2 (https://github.com/Microsoft/uf2) (application only)
|
|
|
|
- Auto-enter DFU briefly on startup for DTR auto-reset trick (832 only)
|
2018-08-10 15:15:11 +00:00
|
|
|
|
2018-08-29 09:11:38 +00:00
|
|
|
## How to use
|
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
There are two pins, `DFU` and `FRST` that bootloader will check upon reset/power:
|
2018-08-29 09:11:38 +00:00
|
|
|
|
2018-08-30 19:25:47 +00:00
|
|
|
- `Double Reset` Reset twice within 500 ms will enter DFU with UF2 and CDC support (only works with nRF52840)
|
2018-08-29 12:51:13 +00:00
|
|
|
- `DFU = LOW` and `FRST = HIGH`: Enter bootloader with UF2 and CDC support
|
|
|
|
- `DFU = LOW` and `FRST = LOW`: Enter bootloader with OTA, to upgrade with a mobile application such as Nordic nrfConnect/Toolbox
|
|
|
|
- `DFU = HIGH and `FRST = LOW`: Factory Reset mode: erase firmware application and its data
|
|
|
|
- `DFU = HIGH and `FRST = HIGH`: Go to application code if it is present, otherwise enter DFU with UF2
|
|
|
|
- The `GPREGRET` register can also be set to force the bootloader can enter any of above modes (plus a CDC-only mode for Arduino).
|
|
|
|
`GPREGRET` is set by the application before performing a soft reset.
|
2018-08-29 09:11:38 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
On the Nordic PCA10056 DK board, `DFU` is connected to **Button1**, and `FRST` is connected to **Button2**.
|
|
|
|
So holding down **Button1** while clicking **RESET** will put the board into USB bootloader mode, with UF2 and CDC support.
|
2018-09-06 17:46:11 +00:00
|
|
|
Holding down **Button2** while clicking **RESET** will put the board into OTA (over-the-air) bootloader mode.
|
|
|
|
|
|
|
|
On the Nordic PCA10059 Dongle board, `DFU` is connected to the white button.
|
|
|
|
`FRST` is connected to pin 1.10. Ground it to pull `FRST` low, as if you had pushed an `FRST` button.
|
|
|
|
There is an adjacent ground pad.
|
2018-08-29 09:11:38 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
For other boards, please check the board definition for details.
|
2018-08-29 09:11:38 +00:00
|
|
|
|
|
|
|
## Burn & Upgrade with pre-built binaries
|
2018-08-10 15:15:11 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
You can burn and/or upgrade the bootloader with either a J-link or DFU (serial) to a specific pre-built binary version
|
|
|
|
without the hassle of installing a toolchain and compiling the code.
|
|
|
|
This is preferred if you are not developing/customizing the bootloader.
|
2018-08-10 15:15:11 +00:00
|
|
|
|
2018-11-09 15:29:59 +00:00
|
|
|
To flash version `6.1.1r0` using J-Link:
|
2018-08-10 15:15:11 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
```
|
2018-11-09 15:29:59 +00:00
|
|
|
make BOARD=feather_nrf52840_express VERSION=6.1.1r0 flash
|
2018-08-29 12:51:13 +00:00
|
|
|
```
|
2018-08-10 15:15:11 +00:00
|
|
|
|
|
|
|
To upgrade with dfu serial
|
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
```
|
2018-11-09 15:29:59 +00:00
|
|
|
make BOARD=feather_nrf52840_express VERSION=6.1.1r0 dfu-flash
|
2018-08-29 12:51:13 +00:00
|
|
|
```
|
2018-08-10 15:15:11 +00:00
|
|
|
|
2018-12-04 23:18:49 +00:00
|
|
|
Pre-builtin binaries are available on GitHub releases.
|
2018-08-29 09:11:38 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
Note: The bootloader can be downgraded. Since the binary release is a merged version of
|
|
|
|
of both bootloader and the Nordic SoftDevice, you can freely upgrade/downgrade to any version you like.
|
2018-08-10 15:15:11 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
## How to compile and build
|
2018-08-10 15:15:11 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
You should only continue if you are looking to develop bootloader for your own.
|
|
|
|
You must have have a J-Link available to "unbrick" your device.
|
2018-08-10 15:15:11 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
### Option 1: Build with Makefile
|
2018-08-07 14:21:12 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
Prerequisites
|
2018-08-07 14:21:12 +00:00
|
|
|
|
|
|
|
- ARM GCC
|
|
|
|
- Nordic's [nRF5x Command Line Tools](http://infocenter.nordicsemi.com/index.jsp?topic=%2Fcom.nordic.infocenter.tools%2Fdita%2Ftools%2Fnrf5x_command_line_tools%2Fnrf5x_installation.html)
|
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
To build:
|
2018-08-07 14:21:12 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
```
|
2018-11-21 19:37:47 +00:00
|
|
|
make BOARD=feather_nrf52840_express all combinehex
|
2018-08-29 12:51:13 +00:00
|
|
|
```
|
2018-05-08 15:25:15 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
To flash the bootloader:
|
2018-05-08 15:25:15 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
```
|
|
|
|
make BOARD=feather_nrf52840_express flash
|
|
|
|
```
|
2018-05-08 15:25:15 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
To flash SoftDevice (and chip erase):
|
2018-05-08 15:25:15 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
```
|
|
|
|
make BOARD=feather_nrf52840_express sd
|
|
|
|
```
|
2018-05-14 10:30:45 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
To erase all of flash:
|
2018-08-08 09:00:29 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
```
|
|
|
|
make BOARD=feather_nrf52840_express erase
|
|
|
|
```
|
2018-08-08 09:00:29 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
For the list of supported boards, run `make` without `BOARD=` :
|
2018-05-08 15:25:15 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
```
|
|
|
|
$ make
|
|
|
|
You must provide a BOARD parameter with 'BOARD='
|
|
|
|
Supported boards are: feather_nrf52840_express feather_nrf52840_express pca10056
|
|
|
|
Makefile:90: *** BOARD not defined. Stop
|
|
|
|
```
|
2018-05-08 15:25:15 +00:00
|
|
|
|
2018-05-14 10:30:45 +00:00
|
|
|
### Common makefile problems
|
2018-05-08 15:25:15 +00:00
|
|
|
|
2018-05-14 10:30:45 +00:00
|
|
|
#### 1. `arm-none-eabi-gcc`: No such file or directory
|
|
|
|
|
2018-05-14 15:37:06 +00:00
|
|
|
If you get the following error ...
|
2018-05-14 10:30:45 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
```
|
2018-11-21 19:37:47 +00:00
|
|
|
$ make BOARD=feather_nrf52840_express all
|
2018-08-29 12:51:13 +00:00
|
|
|
Compiling file: main.c
|
|
|
|
/bin/sh: /usr/bin/arm-none-eabi-gcc: No such file or directory
|
|
|
|
make: *** [_build/main.o] Error 127
|
|
|
|
```
|
2018-05-14 10:30:45 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
... you may need to edit the `Makefile` and update `GNU_INSTALL_ROOT` to point to the root path of your GCC ARM toolchain.
|
2018-05-08 15:25:15 +00:00
|
|
|
|
2018-05-14 10:30:45 +00:00
|
|
|
#### 2. `mergehex: No such file or directory`
|
|
|
|
|
|
|
|
Make sure that `mergehex` is available from the command-line. This binary is
|
2018-08-29 12:51:13 +00:00
|
|
|
part of Nordic's nRF5x Command Line Tools.
|
2018-05-14 10:30:45 +00:00
|
|
|
|
2018-05-14 10:35:41 +00:00
|
|
|
#### 3. `make: nrfjprog: No such file or directory`
|
|
|
|
|
|
|
|
Make sure that `nrfjprog` is available from the command-line. This binary is
|
2018-08-29 12:51:13 +00:00
|
|
|
part of Nordic's nRF5x Command Line Tools.
|
2018-05-14 10:35:41 +00:00
|
|
|
|
|
|
|
On POSIX-type systems you can temporarily add the path to `nrfjprog` via a
|
|
|
|
variation on the following command:
|
|
|
|
|
|
|
|
```
|
2018-08-29 12:51:13 +00:00
|
|
|
$ export PATH=$PATH:/location/of/nRF5x-Command-Line-Tools_9_7_2_OSX/nrfjprog
|
2018-05-14 10:35:41 +00:00
|
|
|
```
|
2018-05-14 10:30:45 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
### Option 2: Build using Segger Embedded Studio
|
2018-05-14 10:30:45 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
For easier debugging you can also use [SES](https://www.segger.com/products/development-tools/embedded-studio/).
|
2018-08-08 09:04:56 +00:00
|
|
|
The project file is located at `src/segger/Adafruit_nRF52_Bootloader.emProject`.
|
2018-05-14 15:37:06 +00:00
|
|
|
|
2018-08-29 12:51:13 +00:00
|
|
|
> **Note**: SES only flashes the bootloader when you click download, not the SoftDevice.
|
|
|
|
You need to flash the SoftDevice beforehand if you haven't already done so.
|
|
|
|
As mentioned above do something like:
|
|
|
|
|
|
|
|
```
|
|
|
|
make BOARD=feather_nrf52840_express sd
|
|
|
|
```
|