xobs/simmel-bootloader
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

copyedit README.md

Browse Source
This commit is contained in:
Dan Halbert
2018-08-29 08:51:13 -04:00
parent 4924e6787f
commit e76539eeff
1 changed files with 111 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
README.md
View File

@@ -1,105 +1,146 @@
# Adafruit Bluefruit nRF52 Bootloader
This repository contains the bootloader for Adafruit nRF52 series and other popular boards
This is a CDC/DFU/UF2 bootloader for Adafruit nRF52 boards and Nordic development boards.
- [Bluefruit Feather nRF52832](https://www.adafruit.com/product/3406)
- Bluefruit Feather nRF52840 Express
- [Adafruit Feather nRF52832](https://www.adafruit.com/product/3406)
- Adafruit Feather nRF52840 Express
- Nordic nRF52840DK PCA10056
[adafruit-nrfutil](https://github.com/adafruit/Adafruit_nRF52_nrfutil), modified version of [Nordic nrfutil](https://github.com/NordicSemiconductor/pc-nrfutil), is required to perform DFU. Install python3 to your system if it is not installed already and run this command to install adafruit-nrfutil from PyPi:
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.
$ pip3 install --user adafruit-nrfutil
[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:
This repository depends on following submodule
```
$ pip3 install --user adafruit-nrfutil
```
This repository depends on the following submodules:
- [tinyusb](https://github.com/hathach/tinyusb/tree/develop)
- [nrfx](https://github.com/NordicSemiconductor/nrfx)
Get the code with following command:
Note that `tinyusb` also includes `nrfx` as a submodule, so you need
to initialize and update submodules with the `--recursive`` flag.
git clone <URL>.git Adafruit_nRF52_Bootloader
cd Adafruit_nRF52_Bootloader
git submodule update --init
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
```
## Features
- DFU over Serial and OTA ( Application, Bootloader+SD )
- Self-upgradble via Serial and OTA
- DFU using USB Flashing Format a.k.a [UF2](https://github.com/Microsoft/uf2) (Applicatoin only)
- Auto enter DFU briefly on startup for DTR auto-reset trick (832 only)
- 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)
## How to use
There are 2 pins **DFU & FRST** that bootloader will check upon reset/power
There are two pins, `DFU` and `FRST` that bootloader will check upon reset/power:
- `DFU = Low and FRST = High` Enter DFU with UF2 and CDC support
- `DFU = Low and FRST = Low` Enter DFU with OTA, can be upgraded with 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` Goto application code if it is present, otherwise enter DFU with UF2
- Depending on value of the `GPREGRET` register, Bootloader can enter any of above mode (plus a CDC only mode for Arduino). `GPREGRET` is set by application before performing a softreset.
- `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.
For the exact pin location, please check your board definition for details
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.
Holding down **Button2** while clicking **RESE**T will put the board into OTA (over-the-air) bootloader mode.
For other boards, please check the board definition for details.
## Burn & Upgrade with pre-built binaries
You can burn and/or upgrade bootloader with either jlink or dfu (serial) to a specific pre-built binary version without the hassle to install toolchain and compile the code. This is preferred if you are not developing/customizing the bootloader
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.
To flash version `6.1.0r0` using jlink
To flash version `6.1.0r0` using J-Link:
$ make BOARD=feather_nrf52840_express VERSION=6.1.0r0 flash
```
make BOARD=feather_nrf52840_express VERSION=6.1.0r0 flash
```
To upgrade with dfu serial
$ make BOARD=feather_nrf52840_express VERSION=6.1.0r0 dfu-flash
```
make BOARD=feather_nrf52840_express VERSION=6.1.0r0 dfu-flash
```
You can run following command for the list of pre-builtin binaries
Pre-builtin binaries are in the `bin` directory:
$ ls bin/*
bin/feather_nrf52832:
2.0.1 5.0.0 6.1.0r0
```
bin/feather_nrf52832/
2.0.1
5.0.0
6.1.0r0
bin/feather_nrf52840_express:
6.1.0r0
bin/feather_nrf52840_express
6.1.0r0
bin/pca10056:
6.1.0r0
bin/pca10056:
6.1.0r0
```
Note: bootloader is downgradable, since the binary release is merged of bootloader and Softdevice, you could freely "upgrade" to any version you like.
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.
## Compile with latest codes
## How to compile and build
You should only continue if you are looking to develop bootloader for your own. Having a jlink to **de-brick** your device is a must.
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.
### Option 1: Build with makefile
### Option 1: Build with Makefile
Prerequisite
Prerequisites
- 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)
To build
To build:
$ make BOARD=feather_nrf52840_express all
```
make BOARD=feather_nrf52840_express all
```
To flash bootloader
To flash the bootloader:
$ make BOARD=feather_nrf52840_express flash
```
make BOARD=feather_nrf52840_express flash
```
To flash SoftDevice (chip erase)
To flash SoftDevice (and chip erase):
$ make BOARD=feather_nrf52840_express sd
```
make BOARD=feather_nrf52840_express sd
```
To erase chip
To erase all of flash:
$ make BOARD=feather_nrf52840_express erase
```
make BOARD=feather_nrf52840_express erase
```
For the list of supported boards, try to type make without `BOARD=`
For the list of supported boards, run `make` without `BOARD=` :
$ 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
```
$ 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
```
### Common makefile problems
@@ -107,35 +148,41 @@ For the list of supported boards, try to type make without `BOARD=`
If you get the following error ...
$ make BOARD=feather_nrf52840_express all
Compiling file: main.c
/bin/sh: /usr/bin/arm-none-eabi-gcc: No such file or directory
make: *** [_build/main.o] Error 127
```
$ make BOARD=feather_nrf52840_express all
Compiling file: main.c
/bin/sh: /usr/bin/arm-none-eabi-gcc: No such file or directory
make: *** [_build/main.o] Error 127
```
... you may need to edit the `Makefile` and update the `GNU_INSTALL_ROOT` to point to the root path of your GCC ARM toolchain.
... you may need to edit the `Makefile` and update `GNU_INSTALL_ROOT` to point to the root path of your GCC ARM toolchain.
#### 2. `mergehex: No such file or directory`
Make sure that `mergehex` is available from the command-line. This binary is
part of of Nordic's nRF5x Command Line Tools
part of Nordic's nRF5x Command Line Tools.
#### 3. `make: nrfjprog: No such file or directory`
Make sure that `nrfjprog` is available from the command-line. This binary is
part of of Nordic's nRF5x Command Line Tools.
part of Nordic's nRF5x Command Line Tools.
On POSIX-type systems you can temporarily add the path to `nrfjprog` via a
variation on the following command:
```
$ export PATH=$PATH:/Users/Kevin/Downloads/nRF5x-Command-Line-Tools_9_7_2_OSX/nrfjprog
$ export PATH=$PATH:/location/of/nRF5x-Command-Line-Tools_9_7_2_OSX/nrfjprog
```
### Option 2: Build using Segger Embeded Studio
### Option 2: Build using Segger Embedded Studio
For better debugging you can also use [SES](https://www.segger.com/products/development-tools/embedded-studio/).
For easier debugging you can also use [SES](https://www.segger.com/products/development-tools/embedded-studio/).
The project file is located at `src/segger/Adafruit_nRF52_Bootloader.emProject`.
> **Note**: SES only flashes the bootloader when you click download, you need to
flash Softdevice beforehand if you haven't done so ( use `make BOARD=feather_nrf52840_express sd`
mentioned above )
> **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
```