DocumentationUsing BLE Demo with the NAVQ Plus Linux BSP

Using BLE Demo with the NAVQ Plus Linux BSP

Owned by NS
Last updated: Apr 05, 2023 by Sergei Poselenov

This application note explains how to use a BLE demo with the NAVQ Plus Linix BSP.

The NAVQ Plus Linix BSP contains several BLE demos located in the ml_ble_platform project.

BLE demos use a similar communications protocol for sending commands and receiving responses:

  • Commands are sent by writing to TX characteristic with UUID=813dd366-179e-11eb-b214-a3729d689162 and the value handle=0x15;

  • The demo responds to a command by sending notifications in RX characteristic with UUID=89accce6-179e-11eb-a4b6-e3d7b2402624 and value handle=0x17.

In this application note the ml_ble_platform/sensor_base demo is used as an example. This application provides a platform for supporting external sensors and logging raw sample values over BLE. IMU readings are sent as notifications on ACC_SAMPLES (UUID=110d8470-2eb3-11eb-bf0c-8ff42f5dc2bc and value handle=0x1d) characteristic value change. Refer to “ML_BLE_Platform BLE Interface Specification” for more information.

Uploading a BLE Demo to the Target

BLE demos included in the NAVQ Plus Linix BSP consist of two parts: the bootloader and a working (“mission“) firmware.

Bootloader binaries are located in the build/core_drivers_ble_v3p2/CMakeProjects/bootloader directory:

ls -l build/core_drivers_ble_v3p2/CMakeProjects/bootloader total 44 -rwxrwxr-x 1 user user 260 Nov 15 00:15 bootloader.bin -rwxrwxr-x 1 user user 6080 Nov 15 00:15 bootloader.elf drwxrwxr-x 3 user user 4096 Nov 24 19:53 CMakeFiles -rw-rw-r-- 1 user user 1029 Nov 15 00:14 cmake_install.cmake -rw-rw-r-- 1 user user 6260 Nov 15 00:14 Makefile -rw-rw-r-- 1 user user 3969 Nov 15 00:15 objdump.txt -rw-rw-r-- 1 user user 4242 Nov 15 00:15 readelf.txt -rw-rw-r-- 1 user user 856 Nov 15 00:15 symbol.txt

Refer to https://voxelbotics.atlassian.net/wiki/spaces/DOC/pages/31752193 for more information.

Perform the following steps to upload the demo to the target:

  1. Sync the Telink programmer with the target:

    sudo tcdb 9518 sws

  2. Program the bootloader with the 0 offset:

    sudo tcdb 9518 wf 0 -i ./bootloader.bin -b

  3. Program the demo binary with the 1000 offset:

    sudo tcdb 9518 wf 1000 -i ./sensor_base_mission-evb-002.001.000.bin -b

  4. Reset the target.

Checking a Local Interface

  1. Verify that a local interface is detected with hcitool:

    user@imx8mpnavq:~$ sudo hcitool dev Devices: hci0 D4:53:83:C4:E5:5B

    Follow the instructions provided in https://voxelbotics.atlassian.net/wiki/spaces/DOC/pages/7274511 application note if a local interface is not detected by hcitool.

  2. Check a local interface status and switch it on if it is disabled:

    user@imx8mpnavq:~$ sudo hciconfig -a hci0 hci0: Type: Primary Bus: UART BD Address: D4:53:83:C4:E5:5B ACL MTU: 1016:5 SCO MTU: 60:12 UP RUNNING RX bytes:1393 acl:0 sco:0 events:64 errors:0 TX bytes:3256 acl:0 sco:0 commands:64 errors:0 user@imx8mpnavq:~$ sudo hciconfig hci0 up

Scanning for Remote Devices and Pairing

The default device name in the ml_ble_platform/sensor_base demo is AZN1-EVB. This name can be changed in the source files or by sending a command over BLE.

Scanning for Remote Devices with hcitool

Run sudo hcitool lescan to start scanning for LE devices:

user@imx8mpnavq:~$ sudo hcitool lescan LE Scan ... ... C4:19:D1:52:01:4F AZN1-EVB

Scanning for Remote Devices and Pairing Using bluetoothctl

  1. Open bluetoothctl:

    user@imx8mpnavq:~$ bluetoothctl Agent registered [CHG] Controller D4:53:83:C4:E5:5B Pairable: yes [bluetooth]#

  2. Scan for available remote devices with the scan le command:

    [bluetooth]# scan le Discovery started [CHG] Controller D4:53:83:C4:E5:5B Discovering: yes ... [NEW] Device C4:19:D1:52:01:4F AZN1-EVB

    The list of remote devices can be printed using the devices command:

    [bluetooth]# devices ... Device C4:19:D1:52:01:4F AZN1-EVB ...

  3. Use the pair <BD address> command to initiate pairing:

    [bluetooth]# pair C4:19:D1:52:01:4F Attempting to pair with C4:19:D1:52:01:4F [CHG] Device C4:19:D1:52:01:4F Connected: yes [AZN1-EVB]# ... [CHG] Device C4:19:D1:52:01:4F UUIDs: 00001800-0000-1000-8000-00805f9b34fb [CHG] Device C4:19:D1:52:01:4F UUIDs: 00001801-0000-1000-8000-00805f9b34fb [CHG] Device C4:19:D1:52:01:4F UUIDs: 0000180a-0000-1000-8000-00805f9b34fb [CHG] Device C4:19:D1:52:01:4F UUIDs: 0000180f-0000-1000-8000-00805f9b34fb [CHG] Device C4:19:D1:52:01:4F UUIDs: 242b0000-3f36-45ef-bb6b-6b0e778eb823 [CHG] Device C4:19:D1:52:01:4F UUIDs: 563b1512-179d-11eb-af7d-e30cfa630c08 [CHG] Device C4:19:D1:52:01:4F ServicesResolved: yes [CHG] Device C4:19:D1:52:01:4F Modalias: usb:v248Ap8266d0001 [CHG] Device C4:19:D1:52:01:4F Paired: yes Pairing successful

Communicating with the BLE Demo

Communicating with the BLE Demo Using gatttool in an Interactive Mode

  1. Open gatttool in an interactive mode:

    user@imx8mpnavq:~$ sudo gatttool -b C4:19:D1:52:01:4F --interactive [C4:19:D1:52:01:4F][LE]>

  2. Connect to the device:

    [C4:19:D1:52:01:4F][LE]> connect Attempting to connect to C4:19:D1:52:01:4F Connection successful

  3. The characteristics list can be printed using the characteristics command:

    [C4:19:D1:52:01:4F][LE]> characteristics handle: 0x0002, char properties: 0x12, char value handle: 0x0003, uuid: 00002a00-0000-1000-8000-00805f9b34fb handle: 0x0004, char properties: 0x02, char value handle: 0x0005, uuid: 00002a01-0000-1000-8000-00805f9b34fb handle: 0x0006, char properties: 0x02, char value handle: 0x0007, uuid: 00002a04-0000-1000-8000-00805f9b34fb handle: 0x0009, char properties: 0x20, char value handle: 0x000a, uuid: 00002a05-0000-1000-8000-00805f9b34fb handle: 0x000d, char properties: 0x02, char value handle: 0x000e, uuid: 00002a50-0000-1000-8000-00805f9b34fb handle: 0x0010, char properties: 0x12, char value handle: 0x0011, uuid: 00002a19-0000-1000-8000-00805f9b34fb handle: 0x0014, char properties: 0x08, char value handle: 0x0015, uuid: 813dd366-179e-11eb-b214-a3729d689162 handle: 0x0016, char properties: 0x10, char value handle: 0x0017, uuid: 89accce6-179e-11eb-a4b6-e3d7b2402624 handle: 0x0019, char properties: 0x10, char value handle: 0x001a, uuid: a366b5cc-284a-11eb-b543-2766e21b935f handle: 0x001c, char properties: 0x10, char value handle: 0x001d, uuid: 110d8470-2eb3-11eb-bf0c-8ff42f5dc2bc handle: 0x001f, char properties: 0x08, char value handle: 0x0020, uuid: 773d9c12-efb8-44e8-bcc7-3e60e6fabd3a handle: 0x0022, char properties: 0x22, char value handle: 0x0023, uuid: 242b0001-3f36-45ef-bb6b-6b0e778eb823 handle: 0x0025, char properties: 0x10, char value handle: 0x0026, uuid: 242b0002-3f36-45ef-bb6b-6b0e778eb823 handle: 0x0028, char properties: 0x0a, char value handle: 0x0029, uuid: 242b0003-3f36-45ef-bb6b-6b0e778eb823

  4. To send commands to the target, write to the TX characteristic using the char-write-req or the char-write-cmd command. A response from the demo is received as a notification on RX characteristic value change.
    To read a device name send the sys device-name=? command:

    [C4:19:D1:52:01:4F][LE]> char-write-req 0x15 737973206465766963652d6e616d653d3f0a Characteristic value was written successfully Notification handle = 0x0017 value: 40 31 32 35 37 36 32 32 3a 73 79 73 20 64 65 76 69 63 65 2d 6e 61 6d 65 3d 3f 0a Notification handle = 0x0017 value: 40 31 32 35 37 36 32 32 3a 44 65 76 69 63 65 20 6e 61 6d 65 20 69 73 20 41 5a 4e 31 2d 45 56 42 0a

    To set a new name use the sys device-name=<new name> command.

    To enable IMU sample streaming send the acc set_config, acc stream-on, and acc stream-on commands:

    [C4:19:D1:52:01:4F][LE]> char-write-req 0x15 616363207365745f636f6e6669670a Characteristic value was written successfully Notification handle = 0x0017 value: 40 31 33 34 30 32 37 32 3a 61 63 63 20 73 65 74 5f 63 6f 6e 66 69 67 0a Notification handle = 0x0017 value: 61 63 63 20 73 74 61 74 65 20 32 2c 20 63 61 6c 6c 62 61 63 6b 20 30 78 30 0a Notification handle = 0x0017 value: 40 31 33 34 30 32 37 32 3a 61 63 63 20 73 65 74 74 69 6e 67 20 63 6f 6e 66 69 67 2e 2e 2e 0a Notification handle = 0x0017 value: 73 65 6e 73 6f 72 20 30 20 63 6f 6e 66 69 67 65 64 0a [C4:19:D1:52:01:4F][LE]> char-write-req 0x15 6163632073746172740a Characteristic value was written successfully Notification handle = 0x0017 value: 40 31 33 39 39 39 38 35 3a 61 63 63 20 73 74 61 72 74 0a Notification handle = 0x0017 value: 73 6d 67 20 61 64 64 20 34 35 34 63 20 74 6f 20 30 0a Notification handle = 0x0017 value: 73 65 6e 73 6f 72 20 30 20 73 65 74 74 69 6e 67 20 63 6f 6e 66 69 67 0a Notification handle = 0x0017 value: 73 65 6e 73 6f 72 20 30 20 63 6f 6e 66 69 67 65 64 0a Notification handle = 0x0017 value: 40 31 33 39 39 39 39 30 3a 73 65 6e 73 6f 72 20 30 20 73 74 61 72 74 65 64 0a [C4:19:D1:52:01:4F][LE]> char-write-req 0x15 6163632073747265616d2d6f6e0a Characteristic value was written successfully Notification handle = 0x0017 value: 40 31 34 37 37 39 30 30 3a 61 63 63 20 73 74 72 65 61 6d 2d 6f 6e 0a Notification handle = 0x0017 value: 40 31 34 37 37 39 30 30 3a 61 63 63 20 73 74 72 65 61 6d 69 6e 67 20 65 6e 61 62 6c 65 64 2e 2e 2e 0a Notification handle = 0x0017 value: 67 61 70 20 69 6e 20 73 65 6e 73 6f 72 20 30 20 73 65 71 5f 6e 6f 20 66 72 6f 6d 20 30 20 74 6f 20 34 30 35 30 0a

    After that notifications with IMU samples are being received:

    Notification handle = 0x001d value: 8e 87 16 00 a4 1f 36 1f 00 51 f9 ff c4 00 00 fe 01 00 Notification handle = 0x001d value: a0 87 16 00 a6 1f 35 1f 00 58 f9 ff 8f 00 00 fe 01 00 Notification handle = 0x001d value: b2 87 16 00 a8 1f 3d 1f 00 81 f9 ff 99 00 00 fe 01 00 Notification handle = 0x001d value: c4 87 16 00 aa 1f 7d 1f 00 6b f9 ff 9e 00 00 02 02 00 Notification handle = 0x001d value: d6 87 16 00 ac 1f 3d 1f 00 74 f9 ff c2 00 00 fe 01 00 Notification handle = 0x001d value: e8 87 16 00 ae 1f 6b 1f 00 44 f9 ff 9b 00 00 02 02 00 Notification handle = 0x001d value: fa 87 16 00 b0 1f 2d 1f 00 75 f9 ff 7c 00 00 fd 01 00 Notification handle = 0x001d value: 0c 88 16 00 b2 1f 57 1f 00 40 f9 ff b3 00 00 01 02 00 Notification handle = 0x001d value: 1e 88 16 00 b4 1f 4d 1f 00 5a f9 ff ab 00 00 00 02 00 Notification handle = 0x001d value: 30 88 16 00 b6 1f 5b 1f 00 6e f9 ff 8f 00 00 00 02 00 Notification handle = 0x001d value: 42 88 16 00 b8 1f 67 1f 00 5d f9 ff a2 00 00 01 02 00 Notification handle = 0x001d value: 54 88 16 00 ba 1f 5a 1f 00 5f f9 ff 93 00 00 00 02 00 Notification handle = 0x001d value: 66 88 16 00 bc 1f 6b 1f 00 35 f9 ff a6 00 00 02 02 00 Notification handle = 0x001d value: 78 88 16 00 be 1f 54 1f 00 5b f9 ff 9f 00 00 00 02 00

    In the notification value the first 4 bytes are a timestamp, the next 2 bytes are a sequence number and the last 12 bytes are IMU samples.

Communicating with the BLE Demo Using gatttool in a Non-Interactive Mode

In a non-interactive mode gatttool connects to the target automatically, executes a requested command, and disconnects from the target.

Use --char-write-req -a <characteristic value handle> -n <value> to write to characteristic. Use the --listen flag to prevent disconnecting from the target.

  • To read a device name execute the following command:

user@imx8mpnavq:~$ sudo gatttool -b C4:19:D1:52:01:4F --char-write-req -a 0x15 -n 737973206465766963652d6e616d653d3f0a --listen Characteristic value was written successfully Notification handle = 0x0017 value: 40 31 38 38 32 34 36 34 3a 73 79 73 20 64 65 76 69 63 65 2d Notification handle = 0x0017 value: 6e 61 6d 65 3d 3f 0a Notification handle = 0x0017 value: 40 31 38 38 32 34 36 34 3a 44 65 76 69 63 65 20 6e 61 6d 65 Notification handle = 0x0017 value: 20 69 73 20 41 5a 4e 31 2d 45 56 42 58 58 0a

  • To enable IMU sample streaming execute the following commands:

user@imx8mpnavq:~$ sudo gatttool -b C4:19:D1:52:01:4F --char-write-req -a 0x15 -n 616363207365745f636f6e6669670a user@imx8mpnavq:~$ sudo gatttool -b C4:19:D1:52:01:4F --char-write-req -a 0x15 -n 6163632073747265616d2d6f6e0a user@imx8mpnavq:~$ sudo gatttool -b C4:19:D1:52:01:4F --char-write-req -a 0x15 -n 6163632073746172740a user@imx8mpnavq:~$ sudo gatttool -b C4:19:D1:52:01:4F --char-write-req -a 0x15 -n 00 --listen Notification handle = 0x001d value: f4 b7 1c 00 9c c7 7c 1f 00 58 f9 ff ba 00 00 03 02 00 Notification handle = 0x001d value: 06 b8 1c 00 9e c7 2a 1f 00 58 f9 ff b0 00 00 fd 01 00 Notification handle = 0x001d value: 18 b8 1c 00 a0 c7 40 1f 00 60 f9 ff 99 00 00 ff 01 00 Notification handle = 0x001d value: 2a b8 1c 00 a2 c7 5b 1f 00 67 f9 ff a4 00 00 00 02 00 Notification handle = 0x001d value: 3c b8 1c 00 a4 c7 63 1f 00 84 f9 ff af 00 00 00 02 00 Notification handle = 0x001d value: 4e b8 1c 00 a6 c7 71 1f 00 53 f9 ff b9 00 00 02 02 00 Notification handle = 0x001d value: 60 b8 1c 00 a8 c7 7b 1f 00 5b f9 ff bd 00 00 02 02 00 Notification handle = 0x001d value: 72 b8 1c 00 aa c7 44 1f 00 6b f9 ff 97 00 00 ff 01 00 Notification handle = 0x001d value: 84 b8 1c 00 ac c7 49 1f 00 54 f9 ff 94 00 00 ff 01 00

Note: To send a command convert it to a hex-string without any quotes or the 0x prefix. Gatttool outputs also receive notification values as hex value arrays.

Useful Commands

Here are some useful commands for communicating with BLE demo:

Command

Gatttool command

Description

Command

Gatttool command

Description

sys fw-ver

char-write-req 0x15 7379732066772d7665720a

Device firmware version request

sys device-name=?

char-write-req 0x15 737973206465766963652d6e616d653d3f0a

Device name request

sys log-lvl=0

char-write-req 0x15 737973206c6f672d6c766c3d300a

Set system debug output verbosity (0 - disabled, 3 - max level)

acc log-lvl=0

char-write-req 0x15 616363206c6f672d6c766c3d300a

Set IMU debug output verbosity

tmp log-lvl=0

char-write-req 0x15 746d70206c6f672d6c766c3d300a

Set temp sensor debug output verbosity

sys log-lvl=?

char-write-req 0x15 737973206c6f672d6c766c3d3f0a

Current system debug output verbosity request

acc log-lvl=?

char-write-req 0x15 616363206c6f672d6c766c3d3f0a

Current IMU debug output verbosity request

tmp log-lvl=?

char-write-req 0x15 746d70206c6f672d6c766c3d3f0a

Current temp sensor debug output verbosity request

acc set_config

char-write-req 0x15 616363207365745f636f6e6669670a

Configure IMU

acc start

char-write-req 0x15 6163632073746172740a

Enable IMU

acc stop

char-write-req 0x15 6163632073746f70200a

Disable IMU

acc stream-on

char-write-req 0x15 6163632073747265616d2d6f6e0a

Enable IMU sample streaming

acc stream-off

char-write-req 0x15 6163632073747265616d2d6f66660a

Disable IMU sample streaming

tmp set_config

char-write-req 0x15 746d70207365745f636f6e6669670a

Configure temp sensor

tmp start

char-write-req 0x15 746d702073746172740a

Enable temp sensor

tmp stop

char-write-req 0x15 746d702073746f700a

Disable temp sensor

tmp stream-on

char-write-req 0x15 746d702073747265616d2d6f6e0a

Enable temp sensor sample streaming

tmp stream-off

char-write-req 0x15 746d702073747265616d2d6f66660a

Disable temp sensor sample streaming