umrx-app-v3 1.5.0

Communication with COINES firmware for humans

Python communication with COINES firmware

python3 communication with COINES firmware on Application Board 3.1 or 3.0 hardware.

Install the latest version from pypi:

pip install umrx-app-v3

The umrx-app-v3 project implements in python3 COINES communication protocol to interact with the micro-controller (MCU) and read the sensor data from the Application Board 3.1 and 3.0 when board is programmed with BST default firmware.

Unlike python bindings from COINES SDK which load pre-compiled OS-dependent C library, this project is built entirely in python and requires only pyserial and pyusb dependencies.

Features

• Support Application Board 3.1 and Application Board 3.0;
• Configure shuttle pins, set pin levels;
• Switch ON/OFF VDD and VDDIO of the shuttle board to power the sensor;
• Read / write the sensor registers using the I2C protocol;
• Read / write the sensor registers using the SPI protocol;
• Configure and receive streaming packets:
  • Polling streaming: sensor registers are read in bulk at regular intervals;
  • Interrupt streaming: sensor registers are read in bulk when sensor reports data ready over interrupt pin;
• Switch application to DFU or MTP;
• Enable MCU time stamp (works only with Application Board 3.0).

Installation

Communication with firmware happens either via USB (for Application Board 3.0) or serial port over USB (for Application Board 3.1). Reading / writing USB (or serial) devices is often a privileged operation. Below we describe OS-specific setup steps to be able to use the package.

OS prerequisites

Linux

To access USB device on Linux as a regular user, one needs to install the udev-rules. Create the file /etc/udev/rules.d/application_board.rules with the following content:

# Application Board 3.0
SUBSYSTEM=="usb", ATTRS{idVendor}=="152a", ATTRS{idProduct}=="80c0", ACTION=="add", MODE="0666", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEM=="usb", ATTRS{idVendor}=="108c", ATTRS{idProduct}=="ab3d", ACTION=="add", MODE="0666", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEM=="usb", ATTRS{idVendor}=="108c", ATTRS{idProduct}=="ab3f", ACTION=="add", MODE="0666", ENV{ID_MM_DEVICE_IGNORE}="1"

# Application Board 3.1
SUBSYSTEM=="usb", ATTRS{idVendor}=="108c", ATTRS{idProduct}=="ab38", ACTION=="add", MODE="0666", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEM=="usb", ATTRS{idVendor}=="108c", ATTRS{idProduct}=="ab39", ACTION=="add", MODE="0666", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEM=="usb", ATTRS{idVendor}=="108c", ATTRS{idProduct}=="ab3a", ACTION=="add", MODE="0666", ENV{ID_MM_DEVICE_IGNORE}="1"

The file can be created with the following command:

sudo bash -c 'cat <<EOF >>/etc/udev/rules.d/application_board.rules
# Application Board 3.0
SUBSYSTEM=="usb", ATTRS{idVendor}=="152a", ATTRS{idProduct}=="80c0", ACTION=="add", MODE="0666", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEM=="usb", ATTRS{idVendor}=="108c", ATTRS{idProduct}=="ab3d", ACTION=="add", MODE="0666", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEM=="usb", ATTRS{idVendor}=="108c", ATTRS{idProduct}=="ab3f", ACTION=="add", MODE="0666", ENV{ID_MM_DEVICE_IGNORE}="1"

# Application Board 3.1
SUBSYSTEM=="usb", ATTRS{idVendor}=="108c", ATTRS{idProduct}=="ab38", ACTION=="add", MODE="0666", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEM=="usb", ATTRS{idVendor}=="108c", ATTRS{idProduct}=="ab39", ACTION=="add", MODE="0666", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEM=="usb", ATTRS{idVendor}=="108c", ATTRS{idProduct}=="ab3a", ACTION=="add", MODE="0666", ENV{ID_MM_DEVICE_IGNORE}="1"
EOF'

Reload the udev-rules:

sudo udevadm control --reload-rules && sudo udevadm trigger

To access serial devices on Linux as a regular user, one needs to be a member of the dialout group.

sudo usermod -a -G dialout <your-user-name>

Windows

Install libusb-1 via vcpkg by following these instructions.

Add the path where the *.DLL libraries are located to the PATH environment variable.

Use zadig to install the drivers for the boards:

• For Application Board 3.1 install CDC serial driver:

• For Application Board 3.0 install WinUSB:

Mac OS

Install Homebrew.

Install libusb:

brew install libusb

Execute the python scripts with sudo to read/write USB device.

Install using pip

pip install umrx-app-v3

Install from source

To install the package from source:

1. clone the repository, and
2. run in the repo root:

pip install poetry
poetry install 
poetry shell

Supported python version

The project was developed with python-3.12 although it might work earlier python versions >=3.9.

Quick start

The examples below are self-contained and can be copy-pasted as is.

Terminology

Bosch offers two hardware revisions:

• Application Board 3.1, 3.1 HW
• Application Board 3.0, 3.0 HW

Although both boards use nRF52840 (and are based on NINA-B30* modules), they differ in hardware and firmware.

In umrx-v3-py code to differentiate the boards we use v3_rev1 (for v3, revision 1) suffix for 3.1 HW and v3_rev0 (for v3, revision 0) suffix for 3.0 HW.

Create the board object

Create the board object and initialize (connect to board and open communication):

from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1

board = ApplicationBoardV3Rev1()
# initialize board communication 
board.initialize()

Configure shuttle pins

from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1
from umrx_app_v3.mcu_board.bst_protocol_constants import MultiIOPin, PinDirection, PinValue

board = ApplicationBoardV3Rev1()
board.initialize()
# configure shuttle pin P2.6 as output and set to high 
board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_6, PinDirection.OUTPUT, PinValue.HIGH)

Supply power to shuttle

from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1

board = ApplicationBoardV3Rev1()
board.initialize()
# set VDD to 3.3 V, VDDIO to 3.3 V
board.set_vdd_vddio(3.3, 3.3)

Configure communication interface

I2C

import time
from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1
from umrx_app_v3.mcu_board.bst_protocol_constants import MultiIOPin, PinDirection, PinValue

board = ApplicationBoardV3Rev1()
board.initialize()
board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_6, PinDirection.OUTPUT, PinValue.HIGH)
board.set_vdd_vddio(3.3, 3.3)
time.sleep(0.01)
board.configure_i2c()

SPI

import time
from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1
from umrx_app_v3.mcu_board.bst_protocol_constants import MultiIOPin, PinDirection, PinValue, SPIBus
from umrx_app_v3.mcu_board.commands.spi import SPIConfigureCmd

board = ApplicationBoardV3Rev1()
board.initialize()
board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_1, PinDirection.OUTPUT, PinValue.HIGH)
board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_5, PinDirection.OUTPUT, PinValue.HIGH)
board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_6, PinDirection.OUTPUT, PinValue.LOW)
board.set_vdd_vddio(3.3, 3.3)
time.sleep(0.01)
SPIConfigureCmd.set_bus(SPIBus.BUS_1)
board.configure_spi()

Read / write registers

I2C

import time
from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1
from umrx_app_v3.mcu_board.bst_protocol_constants import MultiIOPin, PinDirection, PinValue

board = ApplicationBoardV3Rev1()
board.initialize()
board.start_communication()
board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_6, PinDirection.OUTPUT, PinValue.HIGH)
board.set_vdd_vddio(3.3, 3.3)
time.sleep(0.1)
board.configure_i2c()
result = board.read_i2c(i2c_address=0x68, register_address=0x0, bytes_to_read=1)
print(result)

SPI

import time
from umrx_app_v3.mcu_board.app_board_v3_rev1 import ApplicationBoardV3Rev1
from umrx_app_v3.mcu_board.bst_protocol_constants import MultiIOPin, PinDirection, PinValue, SPIBus
from umrx_app_v3.mcu_board.commands.spi import SPIConfigureCmd

board = ApplicationBoardV3Rev1()
board.initialize()
board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_1, PinDirection.OUTPUT, PinValue.HIGH)
board.set_pin_config(MultiIOPin.MINI_SHUTTLE_PIN_2_6, PinDirection.OUTPUT, PinValue.LOW)
board.set_vdd_vddio(3.3, 3.3)
time.sleep(0.01)
SPIConfigureCmd.set_bus(SPIBus.BUS_1)
board.configure_spi()
result = board.read_spi(cs_pin=MultiIOPin.MINI_SHUTTLE_PIN_2_5, register_address=0x0, bytes_to_read=1)
print(result)

Examples

Take a look at the additional examples.

Default firmware

The code was developed and tested with the default firmware the 3.0 and 3.1 boards were pre-programmed with.

If you want to program you board with the same firmware, follow instructions from this repo.