Getting Started

Building

# install the dependencies
pip install --user intelhex bleak

# import the submodules
git submodule init nrfx
git submodule init micropython
make -C micropython/ports/nrf/ submodules

# build the firmware image
make

This should go through everything required to get a build/firmware.hex file built-up.

Some more dependencies might need to be installed, such as a cross compiler toolchain:

# On Ubuntu/Debian-based systems (including Windows WSL):
sudo apt install gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi gdb-multiarch

# On Fedora-based systems:
sudo yum install arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib gdb-multiarch

# On Arch-based systems:
sudo pacman -Syu arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib gdb-multiarch

# On MacOS:
brew install arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib gdb-multiarch

Flashing to the Monocle

The devkit can be flashed through the SWD debugger interface with a dongle such as st-link/v2 or J-Link.

The connection to the Monocle board is as follow:

┌─────────────────────────────────┐
│ () ┌───────────────────────┐ () │
│    │  o o o o o o o o o o  │    │
│    │  o o o o o │ o o o o  │    │
│    └────────│─│ │───│──────┘    │
│             │ │ │   └─────────────── RESET
│        ┌────│ │ └─────────────────── GND    st-link
│        │    │ └───────────────────── SWCLK
│        │    └─────────────────────── SWDIO
│        │               │        │
│        │               │        │
│        │               │        │
│        └───────────────┘        │
│                                 │
│            |||||||              │
│                                 │
│             ┌──  ──┐            │
│             └──────┘            │
│                 └─────────────────── SEGGER J-Link
│                                 │
:                                 :

Then, the flash command can be issued.

Flashing is done as for any ARM microcontroller

  • With OpenOCD (supporting both st-link/v2/v3 or J-Link)

  • WIth nrfjprog (supporting J-Link only)

Once everything is connected:

# If using OpenOCD with an st-link/v2/v3:
make flash_openocd_stlink
openocd -f interface/stlink-dap.cfg -f target/nrf52.cfg -c "init; nrf52_recover; program build/firmware.hex verify; reset run; exit"

# If using OpenOCD with a J-Link:
make flash_openocd_jlink
openocd -f interface/jlink.cfg -c "transport select swd" -f target/nrf52.cfg -c "init; nrf52_recover; program build/firmware.hex verify; reset run; exit"

# If using nrfjprog with a J-Link:
make flash_nrfjprog_jlink
nrfjprog --family nrf52 --recover --program build/firmware.hex --verify --debugreset

Debugging the firmware with GDB

You will need gdb-multiarch installed on your system.

Then, with the SWD debugger connected as it already is when flashing:

# If using OpenOCD with an st-link/v2/v3:
make gdb_openocd_stlink

# If using OpenOCD with a J-Link:
make gdb_openocd_jlink

# If using nrfjprog with a J-Link:
make gdb_segger_jlink

Then in another terminal, start GDB:

make gdb

Connecting to the Monocle

A MicroPython REPL is running on the Monocle. You can connect to it over the Bluetooth RFCOMM service.

From a computer

A serial_console.py script is provided for connecting over Bluetooth. You can invoke it with python3 serial_console.py or:

make shell

This should give you access to a MicroPython REPL running on the Monocle.

If the connection does not happen, you may need to enable Bluetooth on your system. For instance, on Linux, you need to start the bluetoothd service. You can then scan the existing devices with bluetoothctl or sudo hcitool lescan.

From a phone

You may use a RFCOMM serial console to connect to the shell.

You would need to setup macros or switch to hex mode to enter the various CTRL keys: CTRL-A is 01, CTRL-B is 02, CTRL-D is 04 in hex mode.

Troubleshooting

The community chat is present at MONOCLE/#support on Discord.

See also Hardware Getting Started for troubleshooting the hardware.

See also bootloader() for how to manually jump to the bootloader.

[error] [  nRF52] - Data does not match in address range [0x00000000-0x00000b00] (Flash)`

When using nrfjprog, it is required to use the --recover option to bypass Nordic flash protection, which will erase the whole flash, and allow programming new firmware from a hex file.

An alternative comand that might work better in some cases:

nrfjprog --program firmware_file.hex --chiperase --family nrf52 --verify --reset

Future development

  • Audio transfer from Monocle Hardware to Phone Application

  • Reliable transfer of data to phone

  • Data tranfer from Phone to Monocle Hardware

  • FPGA Upgrade feature