Using BLE Demo with the NAVQ Plus Linux BSP
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 thevalue handle=0x15
;The demo responds to a command by sending notifications in RX characteristic with
UUID=89accce6-179e-11eb-a4b6-e3d7b2402624
andvalue 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:
Sync the Telink programmer with the target:
sudo tcdb 9518 sws
Program the bootloader with the
0
offset:sudo tcdb 9518 wf 0 -i ./bootloader.bin -b
Program the demo binary with the
1000
offset:sudo tcdb 9518 wf 1000 -i ./sensor_base_mission-evb-002.001.000.bin -b
Reset the target.
Checking a Local Interface
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
.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
Open
bluetoothctl
:user@imx8mpnavq:~$ bluetoothctl Agent registered [CHG] Controller D4:53:83:C4:E5:5B Pairable: yes [bluetooth]#
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 ...
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
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]>
Connect to the device:
[C4:19:D1:52:01:4F][LE]> connect Attempting to connect to C4:19:D1:52:01:4F Connection successful
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
To send commands to the target, write to the TX characteristic using the
char-write-req
or thechar-write-cmd
command. A response from the demo is received as a notification on RX characteristic value change.
To read a device name send thesys 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
, andacc 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 |
---|---|---|
sys fw-ver |
| Device firmware version request |
sys device-name=? |
| Device name request |
sys log-lvl=0 |
| Set system debug output verbosity (0 - disabled, 3 - max level) |
acc log-lvl=0 |
| Set IMU debug output verbosity |
tmp log-lvl=0 |
| Set temp sensor debug output verbosity |
sys log-lvl=? |
| Current system debug output verbosity request |
acc log-lvl=? |
| Current IMU debug output verbosity request |
tmp log-lvl=? |
| Current temp sensor debug output verbosity request |
acc set_config |
| Configure IMU |
acc start |
| Enable IMU |
acc stop |
| Disable IMU |
acc stream-on |
| Enable IMU sample streaming |
acc stream-off |
| Disable IMU sample streaming |
tmp set_config |
| Configure temp sensor |
tmp start |
| Enable temp sensor |
tmp stop |
| Disable temp sensor |
tmp stream-on |
| Enable temp sensor sample streaming |
tmp stream-off |
| Disable temp sensor sample streaming |