From e76539eeff25f58382266654c39d490ad9e8e5e3 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Wed, 29 Aug 2018 08:51:13 -0400 Subject: [PATCH] copyedit README.md --- README.md | 175 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 111 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 250f517..21e0691 100644 --- a/README.md +++ b/README.md @@ -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 .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 +```