197 lines
5.8 KiB
Markdown
197 lines
5.8 KiB
Markdown
# Setup
|
|
|
|
## Installing CircuitPython submodules
|
|
|
|
Before you can build, you will need to run the following commands once, which
|
|
will install the submodules that are part of the CircuitPython ecosystem, and
|
|
build the `mpy-cross` tool:
|
|
|
|
```
|
|
$ cd circuitpython
|
|
$ git submodule update --init
|
|
$ make -C mpy-cross
|
|
```
|
|
|
|
You then need to download the SD and Nordic SDK files via:
|
|
|
|
> This script relies on `wget`, which must be available from the command line.
|
|
|
|
```
|
|
$ cd ports/nrf
|
|
$ ./drivers/bluetooth/download_ble_stack.sh
|
|
```
|
|
|
|
## Installing `nrfutil`
|
|
|
|
The Adafruit Bluefruit nRF52 Feather ships with a serial and OTA BLE bootloader
|
|
that can be used to flash firmware images over a simple serial connection,
|
|
using the on-board USB serial converter.
|
|
|
|
If you haven't installed this command-line tool yet, go to the `/libs/nrfutil`
|
|
folder (where nrfutil 0.5.2 is installed as a sub-module) and run the following
|
|
commands:
|
|
|
|
> If you get a 'sudo: pip: command not found' error running 'sudo pip install',
|
|
you can install pip via 'sudo easy_install pip'
|
|
|
|
```
|
|
$ cd ../../lib/nrfutil
|
|
$ sudo pip install -r requirements.txt
|
|
$ sudo python setup.py install
|
|
```
|
|
|
|
# Building and flashing firmware images
|
|
|
|
## Building CircuitPython binaries
|
|
|
|
#### REPL over UART (default settings)
|
|
|
|
To build a CircuitPython binary with default settings for the
|
|
`feather52832` target enter:
|
|
|
|
> **NOTE:** `BOARD=feather52832` is the default option and isn't stricly required.
|
|
|
|
```
|
|
$ make BOARD=feather52832 V=1
|
|
```
|
|
|
|
#### REPL over BLE UART (AKA 'NUS')
|
|
|
|
To build a CircuitPython binary that uses the Nordic UART Service (AKA 'NUS' or
|
|
'BLEUART'), modify `/ports/nrf/bluetooth_conf.h` to have the following macro
|
|
set to `1` in the `#elif (BLUETOOTH_SD == 132)` section:
|
|
|
|
```
|
|
#define MICROPY_PY_BLE_NUS (1)
|
|
```
|
|
|
|
... then build as normal, via:
|
|
|
|
```
|
|
$ make BOARD=feather52832 V=1
|
|
```
|
|
|
|
You can then connect over BLE UART using an application like Bluefruit LE
|
|
Connect, available for Android, iOS and OS X, or any other application that
|
|
supports the NUS service and allows you to send the corrent EOL sequence.
|
|
|
|
## Flashing binaries with `nrfutil`
|
|
|
|
### 1. **Update bootloader** to single-bank version
|
|
|
|
The Adafruit nRF52 Feather ships, by default, with a **dual-bank** bootloader
|
|
that cuts the available flash memory in half in exchange for safer
|
|
OTA updates.
|
|
|
|
Due to the size of CircuitPython, we must migrate this bootloader to a
|
|
**single-bank** version, doubling the amount of flash memory available to us.
|
|
|
|
> These commands only need to be run once and will update the SoftDevice and
|
|
bootloader from the dual-bank version that ships on Arduino-based Adafruit
|
|
Feather52 boards to a single-bank CircuitPython compatible version:
|
|
|
|
#### S132 v2.0.1 single-bank (recommended):
|
|
|
|
By default s132 v2.0.1 is used when no `SOFTDEV_VERSION` field is passed in:
|
|
|
|
```
|
|
$ make BOARD=feather52832 SERIAL=/dev/tty.SLAB_USBtoUART boot-flash
|
|
```
|
|
|
|
#### S132 v5.0.0 (BLE5, experimental):
|
|
|
|
To enable BLE5 support and the latest S132 release, flash the v5.0.0 bootloader via:
|
|
|
|
```
|
|
$ make BOARD=feather52832 SERIAL=/dev/tty.SLAB_USBtoUART SOFTDEV_VERSION=5.0.0 boot-flash
|
|
```
|
|
|
|
### 2. Generate and flash a CircuitPython DFU .zip package over serial
|
|
|
|
The following command will package and flash the CircuitPython binary using the
|
|
appropriate bootloader mentionned above.
|
|
|
|
This command assumes you have already built a valid circuitpython
|
|
image, as described earlier in this readme.
|
|
|
|
> The name of the serial port target will vary, depending on your OS.
|
|
|
|
```
|
|
$ make BOARD=feather52832 SERIAL=/dev/tty.SLAB_USBtoUART dfu-gen dfu-flash
|
|
```
|
|
|
|
By default, CircuitPython will build with **BLE** support enabled using
|
|
`SD=s132` and the `SOFTDEV_VERSION=2.0.1`. If you wish to specify a different
|
|
SD family or version you can enter the optional fields as shown below:
|
|
|
|
```
|
|
$ make BOARD=feather52832 SERIAL=/dev/tty.SLAB_USBtoUART SD=s132 SOFTDEV_VERSION=5.0.0 dfu-gen dfu-flash
|
|
```
|
|
|
|
## Working with CircuitPython
|
|
|
|
### Running local files with `ampy`
|
|
|
|
[ampy](https://learn.adafruit.com/micropython-basics-load-files-and-run-code/install-ampy)
|
|
is a command-line tool that can be used with the nRF52 Feather to transfer
|
|
local python files to the nRF52 for execution, rather than having to enter
|
|
the REPL manually, enter paste mode, and paste the code yourself.
|
|
|
|
> **IMPORTANT**: You must have `ampy` version **1.0.3** or higher to use `ampy`
|
|
with the nRF52. The bootloader on the nRF52 requires a delay between the
|
|
HW reset, and the moment when the command sequance is sent to enter raw
|
|
mode. This required `-d/--delay` flag was added in release 1.0.3.
|
|
|
|
|
|
Save the following file as `test.py`:
|
|
|
|
```
|
|
import board
|
|
import digitalio
|
|
import time
|
|
|
|
led = digitalio.DigitalInOut(board.LED2)
|
|
led.direction = digitalio.Direction.OUTPUT
|
|
|
|
while True:
|
|
led.value = True
|
|
time.sleep(0.5)
|
|
led.value = False
|
|
time.sleep(0.5)
|
|
```
|
|
|
|
Then run the saved file via ampy, updating the serial port as required:
|
|
|
|
```
|
|
$ ampy -p /dev/tty.SLAB_USBtoUART -d 1.5 run test.py
|
|
```
|
|
|
|
This should give you blinky at 1 Hz on LED2 (the blue LED on the nRF52 Feather).
|
|
|
|
### Uploading files and libraries with `ampy`
|
|
|
|
To upload Python files or pre-compiled CircuitPython libraries to the `lib` folder,
|
|
run the following commands:
|
|
|
|
> In this example **i2c_device.py** is used, which is part of
|
|
[Adafruit_CircuitPython_BusDevice](https://github.com/adafruit/Adafruit_CircuitPython_BusDevice)
|
|
|
|
```
|
|
$ ampy -p /dev/tty.SLAB_USBtoUART -d 1.5 put i2c_device.py lib/i2c_device.py
|
|
```
|
|
|
|
To verify that the file was uploaded correctly, you can check the contents of
|
|
the `lib` folder with:
|
|
|
|
```
|
|
$ ampy -p /dev/tty.SLAB_USBtoUART -d 1.5 ls /lib
|
|
i2c_device.py
|
|
```
|
|
|
|
### Suggested libraries
|
|
|
|
The following libraries should be installed as a minimum on most new boards:
|
|
|
|
- [Adafruit_CircuitPython_BusDevice](https://github.com/adafruit/Adafruit_CircuitPython_BusDevice)
|
|
- [Adafruit_CircuitPython_Register](https://github.com/adafruit/Adafruit_CircuitPython_Register/tree/master)
|