CapBot control using Bluetooth Low Energy

Warning

This is currently a work in progress, it’s by no means finished nor stable.

This repo can be divided in two main parts:

• CapBot firmware that exposes a GATT server (i.e. the BLE peripheral)

• A command line interface that connects to this GATT server (i.e. the BLE central)

Robot Control Service

A custom GATT service is used for interacting with a robot. This service has UUID 00000030-0000-1000-8000-00805f9b34fb and supports the following characteristics:

Table 1. Characteristics of our robot control service (RCS)

Name	Characteristic UUID
Drive	00000031-0000-1000-8000-00805f9b34fb
Speed	00000032-0000-1000-8000-00805f9b34fb
Angle	00000033-0000-1000-8000-00805f9b34fb
Vcap	00000034-0000-1000-8000-00805f9b34fb

Drive

Table 2. Format of drive characteristic

	0				4				8				12
Drive	FL	FR	BL	BR	DUR				/

• FL: Target speed (RPM) for Front Left motor

• FR: Target speed (RPM) for Front Right motor

• BL: Target speed (RPM) for Back Left motor

• BR: Target speed (RPM) for Back Right motor

• DUR: The amount of milliseconds to keep these target speeds before stopping again

Speed

Table 3. Format of speed characteristic

	0				4				8				12
Speed	FL	FR	BL	BR	/

• FL: Measured speed (RPM) of Front Left motor

• FR: Measured speed (RPM) of Front Right motor

• BL: Measured speed (RPM) of Back Left motor

• BR: Measured speed (RPM) of Back Right motor

Angle

Table 4. Format of angle characteristic

	0				4				8				12
Angle	FL				FR				BL				BR

• FL: Measured angle (°) of Front Left motor

• FR: Measured angle (°) of Front Right motor

• BL: Measured angle (°) of Back Left motor

• BR: Measured angle (°) of Back Right motor

Vcap

Table 5. Format of Vcap characteristic

	0				4				8				12
Vcap	VOLT		/

• VOLT: Capacitor voltage (mV)

Robot firmware

The robot firmware is based on Nordic’s flavor of zephyr and their nRF Connect SDK.

Building

Using nordic’s docker container

TODO: Update instructions for windows/macos

1. Start toolchain container (deny the SEGGER license to skip JLink installation)

   $ docker run --privileged --rm -it -v .:/firmware ghcr.io/nrfconnect/sdk-nrf-toolchain:v2.7.0

2. Navigate to project directory

   $ cd /firmware/robot/
   $ ls
   CMakeLists.txt  boards  build  capbot.overlay  inc  prj.conf  src  west-ncs-v2.7.0.yml  west-ncs-v2.8.0.yml  west-ncs-v2.9.0.yml

3. Initialize west workspace and get dependencies

   $ west init --local --mf west-ncs-v2.7.0.yml
   === Initializing from existing manifest repository robot
   --- Creating /firmware/.west and local configuration file
   === Initialized. Now run "west update" inside /firmware.
   $ west update
   === updating nrf (deps/nrf):
   --- nrf: initializing
   Initialized empty Git repository in /firmware/deps/nrf/.git/
   ...
   === updating zephyr (deps/zephyr):
   --- zephyr: initializing
   Initialized empty Git repository in /firmware/deps/zephyr/.git/
   ...
   === updating nrfxlib (deps/nrfxlib):
   --- nrfxlib: initializing
   Initialized empty Git repository in /firmware/deps/nrfxlib/.git/
   ...
   === updating cmsis (deps/modules/hal/cmsis):
   --- cmsis: initializing
   Initialized empty Git repository in /firmware/deps/modules/hal/cmsis/.git/
   ...
   === updating hal_nordic (deps/modules/hal/nordic):
   --- hal_nordic: initializing
   Initialized empty Git repository in /firmware/deps/modules/hal/nordic/.git/
   ...

4. Build robot firmware

   $ west build --no-sysbuild --board capbot
   Loading Zephyr default modules (Zephyr base).
   -- Application: /firmware/robot
   -- CMake version: 3.21.0
   -- Using NCS Toolchain 2.6.20240605.1004412633878 for building. (/opt/ncs/toolchains/e9dba88316/cmake)
   -- Found Python3: /opt/ncs/toolchains/e9dba88316/usr/local/bin/python3 (found suitable version "3.9.18", minimum required is "3.8") found components: Interpreter
   -- Cache files will be written to: /firmware/deps/zephyr/.cache
   -- Zephyr version: 3.6.99 (/firmware/deps/zephyr)
   -- Found west (found suitable version "1.2.0", minimum required is "0.14.0")
   -- Board: capbot, qualifiers: nrf52840
   -- Found host-tools: zephyr 0.16.5 (/opt/ncs/toolchains/e9dba88316/opt/zephyr-sdk)
   -- Found toolchain: zephyr 0.16.5 (/opt/ncs/toolchains/e9dba88316/opt/zephyr-sdk)
   -- Found Dtc: /opt/ncs/toolchains/e9dba88316/usr/local/bin/dtc (found suitable version "1.5.0", minimum required is "1.4.6")
   -- Found BOARD.dts: /firmware/robot/boards/kul/capbot/capbot.dts
   -- Found devicetree overlay: /firmware/robot/capbot.overlay
   -- Generated zephyr.dts: /firmware/robot/build/zephyr/zephyr.dts
   -- Generated devicetree_generated.h: /firmware/robot/build/zephyr/include/generated/devicetree_generated.h
   -- Including generated dts.cmake file: /firmware/robot/build/zephyr/dts.cmake
   /firmware/robot/build/zephyr/zephyr.dts:61.25-66.5: Warning (unique_unit_address_if_enabled): /soc/clock@40000000: duplicate unit-address (also used in node /soc/power@40000000)
   Parsing /firmware/deps/zephyr/Kconfig
   Loaded configuration '/firmware/robot/boards/kul/capbot/capbot_defconfig'
   Merged configuration '/firmware/robot/prj.conf'
   Configuration saved to '/firmware/robot/build/zephyr/.config'
   Kconfig header saved to '/firmware/robot/build/zephyr/include/generated/autoconf.h'
   -- Found GnuLd: /opt/ncs/toolchains/e9dba88316/opt/zephyr-sdk/arm-zephyr-eabi/arm-zephyr-eabi/bin/ld.bfd (found version "2.38")
   -- The C compiler identification is GNU 12.2.0
   -- The CXX compiler identification is GNU 12.2.0
   -- The ASM compiler identification is GNU
   -- Found assembler: /opt/ncs/toolchains/e9dba88316/opt/zephyr-sdk/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
   -- Configuring done
   -- Generating done
   -- Build files have been written to: /firmware/robot/build
   -- west build: building application
   [1/197] Preparing syscall dependency handling
   
   [5/197] Generating include/generated/version.h
   -- Zephyr version: 3.6.99 (/firmware/deps/zephyr), build: v3.6.99-ncs2
   [197/197] Linking C executable zephyr/zephyr.elf
   Memory region         Used Size  Region Size  %age Used
              FLASH:      159884 B         1 MB     15.25%
                RAM:       31328 B       256 KB     11.95%
           IDT_LIST:          0 GB        32 KB      0.00%
   Generating files from /firmware/robot/build/zephyr/zephyr.elf for board: capbot

Important

After a successful build, the file ./robot/build/zephyr/zephyr.hex should be present.

Tip	Once the west workspace is created and dependencies are present in ./deps, step 3 is no longer required for rebuilding.

Flashing

Important

We use pyOCD for interacting with the robot’s hardware. Make sure it’s successfully installed (i.e. pyocd list reports the robot’s DAPLink interface)

Flash zephyr binary with our application to the robot

$ pyocd flash -t nrf52840 robot/build/zephyr/zephyr.hex
0000539 I Loading ████████████████████████████████████████████████████████/robot/build/zephyr/zephyr.hex [load_cmd]
[==================================================] 100%
0009467 I Erased 159744 bytes (39 sectors), programmed 159744 bytes (39 pages), skipped 0 bytes (0 pages) at 17.65 kB/s [loader]

Command line interface

The controller CLI is a python program. It connects to CapBots over BLE and uses the custom GATT service described above. It relies on bleak for managing these connections.

Getting started

1. Create a python virtual environment

   $ python -m venv venv
   $ source venv/bin/activate
   $ pip install --upgrade pip
   $ pip install ./controller

2. Use BLE based CapBot controller

   $ cbctl -h
   usage: cbctl [-h] [-v] [-a ADDRESS] {scan,sense,drive} ...
   
   BLE based controller for CapBots
   
   positional arguments:
     {scan,sense,drive}    subcommand help
   
   options:
     -h, --help            show this help message and exit
     -v, --verbose         show verbose output
     -a ADDRESS, --address ADDRESS

Tip	If there’s no robot address specified the sense and drive commands will scan for available robots and continue with the first one found.