prime-ble-firmware

Passport Prime BLE controller firmware.

This workspace contains the following crates:

• bootloader: Secure bootloader that handles firmware updates and verification
• firmware: Main BLE application firmware that implements the Bluetooth protocol
• host-protocol: Shared protocol definitions for MPU-BLE communication

The firmware and bootloader communicate with the main MCU using the host-protocol.

Prerequisites

Nix develop environment

nix develop

Manual installation

# Install xtask for custom build scripts
cargo install cargo-xtask

# Install just for running the Justfile
cargo install just

# Install binutils for working with binary files
cargo install cargo-binutils

# Install LLVM toolchain
apt install llvm libclang-dev

# Add LLVM tools component for binary inspection
rustup component add llvm-tools

# Add ARM Cortex-M4 compilation target
rustup target add thumbv7em-none-eabi

Customizing environment

Rename the env-example file into .env and edit its values to match your environment.

Installation and Running with probe-rs

Follow the probe-rs installation guide to get started.

1. Install the probe-rs tools:

   cargo install probe-rs-tools

2. Verify your ST-Link probe is detected:

   probe-rs list

3. Build firmware packages using the provided just commands:

   Just command list

   just -l

   Build Production Package

   just build

   This creates a BtPackage folder containing:

   • BTApp_Full_Image.hex - Complete production image in Intel HEX format
   • BT_application.bin - Raw Bluetooth application binary
   • BT_application_signed.bin - Signed application with cosign2 header for updates

   Build Debug Package

   just build-debug

   This creates a BtPackage folder containing:

   • BTApp_Full_Image_debug.hex - Debug image with console UART and no flash protection

   Flash SoftDevice and run Bluetooth test app with UART MPU

   just bluetooth-app

Building with Docker

The firmware can be built using docker without installing anything. This needs a file called .github-access-token in the repository root, which is a github personal access token with access to repo, read:org, and gist, and will be used for gh auth login.

Build a default production firmware

./run-with-docker.sh

Run any other command in the build shell

./run-with-docker.sh just build-unsigned
./run-with-docker.sh bash

Caveat: The docker build only mounts the current working directory, so if the cosign PEM file is outside this directory, code signing will not work.

Fixing JtagNoDeviceConnected error

Some nRF52 chips are coming locked from the fab and need an unlocking procedure to be programmed. The unlocking requires a J-Link probe and cannot be done with ST-Link probe.

• Install nrf-recover tool

  cargo install nrf-recover

• Connect the J-Link SWD wires (as well as VCC and GND) to the nRF52 programming port. The easiest way to do it is to use tag-connect 20-to-10 ribbon cable converter board. If this converter isn't available, you can connect the wires manually.

• Run the nrf-recover tool while selecting the J-Link probe:

  nrf-recover --probe-index 0 -y

• The result should look like this:

  Starting mass erase...
  Mass erase completed, chip unlocked
  

• Power cycle the board and try to program the SoftDevice again.

Notes about Access port protection use and chip revisions

As reported by Informational Notice there was a change in the way 'Access port protection' is used in rev. B of the chip due to a possible attack.

You can read about in nrf52805 datasheet at paragraph 4.8.2 and you can read about the different methods of lock/unlock based on chip revision.

Be careful that reading, with a probe-rs read command, info bytes at paragraph 4.4.1.9 INFO.VARIANT in datasheet we get from prime board rev. Y2/A1 these values:

$ probe-rs read --chip nrf52805_xxAA b32 0x10000100 3
00052805 41414130 00002004
         ^^^^^^^^
           AAA0: build code Axx with Access port controlled by hardware only

that are indicating that chip is still of rev. A not variant B with the updated protection command.

As explained in Informational Notice chip of rev. A are still produced ( probably for legacy ) and in case we want to switch to patched protection sequence a different part number must be ordered.