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

Merge pull request #27 from dhalbert/readme-copyedit

Browse Source 
copyedit README.md
This commit is contained in:
hathach
2018-08-29 08:56:14 -07:00
committed by GitHub
parent 4924e6787f e76539eeff
commit ea70e141dd
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 # 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) - [Adafruit Feather nRF52832](https://www.adafruit.com/product/3406)
- Bluefruit Feather nRF52840 Express - Adafruit Feather nRF52840 Express
- Nordic nRF52840DK PCA10056 - 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) - [tinyusb](https://github.com/hathach/tinyusb/tree/develop)
- [nrfx](https://github.com/NordicSemiconductor/nrfx) - [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 Clone this repo with following commands, or fork it for your own development
cd Adafruit_nRF52_Bootloader
git submodule update --init ```
git clone https://github.com/adafruit/Adafruit_nRF52_Bootloader
cd Adafruit_nRF52_Bootloader
git submodule update --init --recursive
```
## Features ## Features
- DFU over Serial and OTA ( Application, Bootloader+SD ) - DFU over Serial and OTA ( application, Bootloader+SD )
- Self-upgradble via Serial and OTA - Self-upgradable via Serial and OTA
- DFU using USB Flashing Format a.k.a [UF2](https://github.com/Microsoft/uf2) (Applicatoin only) - DFU using UF2 (https://github.com/Microsoft/uf2) (application only)
- Auto enter DFU briefly on startup for DTR auto-reset trick (832 only) - Auto-enter DFU briefly on startup for DTR auto-reset trick (832 only)
## How to use ## 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 = HIGH`: Enter bootloader 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 = 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 = 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 - `DFU = HIGH and `FRST = HIGH`: Go to 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. - 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 ## 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 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: bin/feather_nrf52832/
2.0.1 5.0.0 6.1.0r0 2.0.1
5.0.0
6.1.0r0
bin/feather_nrf52840_express: bin/feather_nrf52840_express
6.1.0r0 6.1.0r0
bin/pca10056: bin/pca10056:
6.1.0r0 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 - 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) - 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=' $ make
Supported boards are: feather_nrf52840_express feather_nrf52840_express pca10056 You must provide a BOARD parameter with 'BOARD='
Makefile:90: *** BOARD not defined. Stop Supported boards are: feather_nrf52840_express feather_nrf52840_express pca10056
Makefile:90: *** BOARD not defined. Stop
```
### Common makefile problems ### 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 ... If you get the following error ...
$ make BOARD=feather_nrf52840_express all ```
Compiling file: main.c $ make BOARD=feather_nrf52840_express all
/bin/sh: /usr/bin/arm-none-eabi-gcc: No such file or directory Compiling file: main.c
make: *** [_build/main.o] Error 127 /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` #### 2. `mergehex: No such file or directory`
Make sure that `mergehex` is available from the command-line. This binary is 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` #### 3. `make: nrfjprog: No such file or directory`
Make sure that `nrfjprog` is available from the command-line. This binary is 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 On POSIX-type systems you can temporarily add the path to `nrfjprog` via a
variation on the following command: 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`. 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 > **Note**: SES only flashes the bootloader when you click download, not the SoftDevice.
flash Softdevice beforehand if you haven't done so ( use `make BOARD=feather_nrf52840_express sd` You need to flash the SoftDevice beforehand if you haven't already done so.
mentioned above ) As mentioned above do something like:
```
make BOARD=feather_nrf52840_express sd
```