BLE Interface
Introduction
This page describes the LEAPS UWB Subsystem APIs (UWBS) available over the Bluetooth Low Energy (BLE) link.
In the UWBS BLE API design, the UWBS module acts as the BLE peripheral and can be communicated by BLE central devices through the APIs. This document introduces the APIs that the BLE central devices can use for communication.
Note
In case the Bluetooth on Linux stops working completely, restart the Bluetooth using the following command:
systemctl restart bluetooth.service
Used terminology
UWBS: The LEAPS UWB Subsystem module. The UWBS acts as a BLE peripheral in the BLE communication.
CDEV: The BLE central device that connects to the UWBS peripheral.
ELDR: Extended loader.
Position Representation
In presenting locations and distances in a Real-Time Positioning System, there are two things to consider:
Accuracy
Precision
Accuracy is the error between the position reported by the nodes and the real position. Currently, the UWBS used in this design provides approximately 10 cm accuracy.
Precision is the value of a least-significant bit (LSB) represented. In the onboard firmware of this system, the precision is 1 mm, i.e. 0.001 meter. The positions are presented in 3-dimensional coordinates (X, Y, Z), where X, Y, and Z each is 32-bit integers (4 bytes). Each LSB represents 1 mm. This is for easier interpretation of the value and easier mathematics over the reported values.
When deciding on the precision, it is important to choose it concerning accuracy to get a meaningful result. It is useless to show the user precise values if accuracy is low. The 1 mm precision is too fine-grained concerning the current 10 cm accuracy. Therefore, in the Android application, a precision of 1 cm, i.e. 0.01 meter, is used. Only when the coordinate/distance has changed over 1 cm will the updated value be presented on the Android application? It is similar to rounding float/double values to a meaningful number of decimal places.
BLE Communication With UWBS
Enable events in the UWBS by leaps_ble_evt_cfg_set.
enable notification on dedicated characteristic
Autodisconnect
UWBS will terminate the connection automatically after 15 seconds if CDEV does not enable notifications by writing 0x0001 to the CCCD of the characteristic “API Response” or “API Events” (see BLE GATT Model)
BLE throughput
Use the maximum possible ATT MTU and the highest connection priority to utilize the maximum possible throughput when streaming data to and from UWBS. The maximum MTU supported by the UWBS is 150 bytes. Connection interval preferred by the node is from min 10 ms to max 40 ms, latency 0, timeout 2 sec. Please note that in Bluetooth v4.0 and v4.1, the maximum data length remains at default value regardless of MTU negotiation, which limits the maximum throughput for those Bluetooth versions compared to Bluetooth v4.2 and higher.
Security/encryption
Features
Access control and message integrity (MIC/MAC - Message Integrity Code or Message Authentication Code)
Confidentiality
Replay protection
The wireless encryption on BLE uses AES OFB 128 cipher.
On an encrypted network, each node which wants to participate in the communication needs to have a 128-bit symmetric key set by the user via
In the LEAPS Android Manager: via settings
On module: UART/SPI/UserApp/Shell API
The encryption/decryption is done in blocks where each block has a fixed size of 16 Bytes. Hence, the encrypted payload size has to be rounded to a multiple of 16 Bytes. In other words, the payload of the message must be aligned to the multiple of 16 bytes if security is enabled. The payload must not be aligned to 16 bytes if encryption is disabled.
Each message will contain
Nonce - 16 bytes
MIC/MAC - 2 bytes
Payload (aligned to 16 bytes if encryption is enabled)
See also Message encoding
The picture below explains how the data is encrypted using AES
In red: secret key and must be protected
In blue: public data - distributed in every BLE message
In grey: crypto accelerator / controller
In yellow: calculated/encrypted blocks
In green: cleartext / decrypted block
The picture below explains how the data is encrypted and chained using AES OFB
Requirements for a node wanting to participate in an encrypted network
Use correct Nonce for encryption/decryption
Having 128-bit AES key
There are two types of nonce - nonce used for message encryption/decryption and nonce used for message integrity check.
Each encryption/decryption nonce has a length 16 Bytes. The sender generates and embeds the nonce in the sent message. The receiver uses the received nonce as an Initialization Vector (IV) during the decryption.
Each integrity nonce has a length of 16 Bytes. It is derived from the received message nonce by incrementing it nonce by 1.
To be resistant to relay attacks, every nonce must be unique, and no nonce should be reused for any message at any time in the network.
BLE GATT Model
The UWBS service UUID is 680c21d9-c946-4c1f-9c11-baa1c21329e7. All characteristic values are encoded as little endian as BLE spec suggests.
UWBS Characteristics
uuid |
name |
length |
value |
flags |
|---|---|---|---|---|
Std.GAP service, label 0x2A00 |
Label |
Var |
UTF-8 encoded string |
RW |
e6bfa234- 6758-11e9- 979f-5b2 4c4603eb8 |
API Request |
Var 50 bytes max |
message header + TLV encoded API request |
WO |
e8573d96- 6758-11e9- 8860-cb4 385c24b83 |
API Response |
Var 273 bytes max |
message header + TLV encoded API response |
RO |
003bbdf2- c634-4b3d- ab56-7ec889 b89a37 |
API Events |
Var 273 bytes max |
message header + TLV encoded API events |
RO |
Note
The label characteristic is a special one. It is part of the standard mandatory GAP service (0x1800) under the standard Name characteristic (0x2A00).
Message encoding
Item |
length |
payload |
|---|---|---|
transport header |
2 bytes |
index (1 byte) total (1 byte) |
nonce |
16 bytes |
message nonce, irrelevant if security is turned off |
mic/mac |
2 bytes |
message integrity check if encryption is enabled or simple sum of bytes of the payload if encryption is disabled |
payload |
from 0 to 255 bytes |
Value or TLV encoded frame (depends on particular characteristic) |
Operation mode
Use API request leaps_cfg_get to read current configuration. Use leaps_cfg_anchor_set and leaps_cfg_tag_set API request to set UWBS configuration.
Location data
Use API request leaps_loc_get to read location data containing position, distances or both. Use requests leaps_pos_set and leaps_pos_get to manipulate the UWBS position alone.
Enable event “location data ready” by leaps_ble_evt_cfg_set and receive notifications on the characteristic “events” to automatically get current position and distances from the UWBS.
Location data encoding, received as BLE notification of characteristic “events” |
|||||
|---|---|---|---|---|---|
type |
length |
value |
|||
int32_t- little endian, is x coordinate in millimeters |
int32_t- little endian, is y coordinate in millimeters |
int32_t- little endian, is z coordinate in millimeters |
uint8_t- is position quality factor in percents (0-100) |
||
0x41 |
0x0D |
0x4b 0x0a 0x00 0x00 0x1f 0x04 0x00 0x00 0x9c 0x0e 0x00 0x00 0x64 |
|||
Residue of the frame from previous table |
|||||||
|---|---|---|---|---|---|---|---|
type |
Length |
value |
|||||
uint8_t - number of distances encoded in the value |
uint16_t - UWB address in little endian |
uint32_t - distance in millimeters in little endian |
uint8_t - distance quality factor in percents (0-100) |
position in standard 13 byte format (x,y,z,qf) |
… |
||
0x49 |
0x51 |
0x04 |
position and distance nr. 1 |
nr. 2, 3, 4 |
|||
Type 0x49 means position and distances of ranging anchors
Proxy positions
To overcome limitation of concurrently connected nodes to the CDEV, the passive node can stream/notify about tag position updates via one of the events or via API request leaps_proxy_pos_get.
Enable event “proxy position ready” by leaps_ble_evt_cfg_set and receive notifications on the characteristic “events” to automatically get current proxy position from the UWBS.
Proxy positions encoding, received as BLE notification of characteristic “events” |
|||||
|---|---|---|---|---|---|
type |
length |
Value (see status codes) |
type |
length |
Value (byte 0) positions count (bytes 1 - 496 max) encoded proxy positions in a row |
0x40 |
0x01 |
0x00 |
0x57 |
0x0F |
0x01 0xAB 0xCD …. |
proxy position encoding |
||||
|---|---|---|---|---|
node ID |
little endian, x coordinate in millimeters |
little endian, y coordinate in millimeters |
little endian, z coordinate in millimeters |
is position quality factor in percents (0-100) |
2 bytes |
4 bytes |
4 bytes |
4 bytes |
1 byte |
User Data
Enable event “user data ready” by leaps_ble_evt_cfg_set and receive notifications on the characteristic “events” to automatically receive BLE user data from the UWBS automatically.
BLE user data encoding, received as BLE notification of characteristic “events” |
||
|---|---|---|
type |
length |
value |
max 128 bytes |
||
0x51 |
0x80 |
0x01 0x02 0x03 … 0x7F 0x80 |
Node id
Use request leaps_node_id_get to read the address of the UWBS.
Network id
Use requests leaps_panid_set and leaps_panid_get to manipulate the ID of the network.
Reset or reboot
Requests which reset the UWBS like leaps_reset or leaps_factory_reset will disconnect the BLE central before reset. The central should wait 1 sec before connecting again.
Anchor list
See request leaps_anchor_list_get.
Device info
See request leaps_dev_info_get to read the version of firmware, hardware and configuration.
Update rate
See request leaps_upd_rate_set and leaps_upd_rate_get to change the update rate of the tag node.
Auto-positioning
The BLE API also makes it possible to initiate an auto-positioning process. The auto-positioning process is finished (positions are computed) on the CDEV. The BLE API just makes it possible to initiate distance measurement and retrieval. The workflow is as follows:
Measure:
Initiator is found and verified (the node must be a real initiator, not just configured as initiator, see Operation mode and BLE Advertisements)
Connect to initiator.
Enable “location ready” event by leaps_ble_evt_cfg_set if not enabled already (don’t forget to enable BLE cccd notifications on characteristics).
Start autopositioning by leaps_autopos_start request.
Received all measured distances from the initiator, save the measured distances to the matrix.
Disconnect from initiator.
Get distances from all other (non-initiator) nodes:
Connect
Get location data from UWBS using API request leaps_loc_get and save the distances to the matrix.
Disconnect
Evaluate the measure distances, check orthogonality, and compute positions.
Save the computed positions to nodes on user request (use leaps_pos_set request).
BLE Advertisements
BLE advertisement is a common way for a peripheral device to let others know its presence. According to BLE specification, The broadcast payload is made of triplets, i.e. [length, type, <data>].
The UWBS will broadcast basic information about their presence and operation mode. The BLE advertisement is not long enough to also include the position info.
In the BLE advertisement there are 31 bytes to be used:
3 bytes are mandatory flags (one AD triplet).
The rest 28 bytes can be used by the app to fill in AD record (each record has 2 bytes length+type overhead)
Presence Broadcast
The BLE on the UWBS module works in connectable undirected mode. It advertises the presence broadcast, which contains the availability of service and some service data. The presence broadcast follows the BLE advertisement frame structure and makes use of 28 bytes to present information. The device name is placed in the scan response and requires active scanning.
The presence broadcast and the scan response encoding are described in the table below.
Advertising |
value |
|---|---|
LEN |
0x02 |
TYPE |
0x01 (Flags) |
VALUE |
Device/Advertisement flags - connectable |
LEN |
0x19 (25 dec) |
TYPE |
0x21 (33 dec, Service data) |
VALUE |
680c2 1d9-c946-4c1f-9c11-baa1c21329e7 (16 bytes) |
PAN ID (2 bytes) |
|
Node ID (2 bytes) |
|
Flags (1 byte)
Bit layout: OXSEIBUU O -
operation mode (tag 0,
anchor 1)
X - reserved
S - security_enabled
E - error indication
I - initiator_enabled,
B - bridge_enabled
UU - UWB mode: off (0),
passive (1), active (2)
|
|
Change counter (1 byte) - change counter changes each time the important internal state of the UWBS change (e.g. configuration) |
|
UWB counter (1 byte) - counting-down counter used by low-power devices. When this counter on a LP device reaches 0, the device’s UWB activity is disabled. When anchor detects this counter on a device reaching below a configured low water mark value, anchor connects to the device and resets the counter to keep device’s UWB active. |
|
UWBS Flags (1 byte)
Bit layout: FUSR
F - Firmware Type (2 bits, 0=BLDR,
1=ELDR, 2=MAIN)
U - UWB System (2 bits, 0=LEAPS RTLS,
1=FIRA)
S - UWB Sub System (2 bits, 0=UCI,
1=NIQ)
R - reserved,
|
|
Customer information (1 byte) Specific information for customer |
Scan response |
|
|---|---|
LEN |
0x16 (22 dec) |
TYPE |
0x09 (Device name, placed in scan response packet, use active scanning to detect it) |
VALUE |
“LEAPS” prefix (5 characters) + full node ID in hex format (16 characters) |
Firmware Update
Firmware update functionality is used to update the UWBS’s firmware. This section describes the control and data flow over the BLE interface. Refer to API requests leaps_fw_update_start and leaps_fw_update_xfer for more details on firmware update process.
Updating the FW binary
CDEV connects to the UWBS.
CDEV starts updating the FW by leaps_fw_update_start.
If UWBS responds with the status “ok” CDEV can skip this step. If UWBS responds with the status “again” CDEV resets UWBS and reconnects after the UWBS reboot, and the CDEV starts the update again. If UWBS responds with the status “not permitted”, then fw update is not possible. Fw update might be disabled in UWBS.
CDEV sends chunks of FW by leaps_fw_update_xfer.
CDEV resets the UWBS after the last chunk is sent successfully.
Updating the ELDR binary
CDEV reconnects after the UWBS reboot.
CDEV starts updating the ELDR by leaps_fw_update_start.
CDEV sends chunks of ELDR by leaps_fw_update_xfer.
CDEV resets the UWBS after the last chunk is sent successfully.
CDEV can connect after the UWBS reboot and observe the FW info to verify that the firmware was updated is running.
CDEV should enable notification on the API response” characteristic each time it connects to the UWBS to prevent automatic disconnection of the UWBS (see Autodisconnect).
Sudden disconnection of the UWBS during the firmware update can be handled by starting again from either step 7 or step 1, depending on the current phase of the update.
Transmitting the FW binary
The data is transferred to UWBS by leaps_fw_update_xfer after the firmware update is initiated by the leaps_fw_update_start. UWBS tells the CDEV precisely which data buffer it wants by encoding the size and the offset into the response. CDEV starts sending the requested buffer chunk using write without response, so no full round trip involved. Note that each chunk could be transmitted by more than 1 BLE transfer if the MTU of BLE transfer could not contain the requested buffer size. The chunk consists of:
Data: fw buffer with size requested by UWBS (240)
Relative offset (from the very beginning): 4 bytes.
After the data buffer is sent, CDEV waits for further instructions. During the transmission, the UWBS typically asks for a data buffer sequentially, one by one, to get a continuous byte sequence of firmware. The node might ask for an unexpected buffer if exceptions happen, for example, the current buffer transmission fails.
Firmware update is stopped in case of an error and needs to be started again.
Finishing the transmission
Once the last data chunk has been successfully received, the UWBS will let the CDEV know it has received the full firmware binary. Upon its reception:
CDEV resets the UWBS by leaps_reset command which will cause UWBS to disconnect from the CDEV.
CDEV waits 1 sec.
CDEV tries to connect to UWBS again and check its firmware status (see Device info).
Appendix - Bibliography
Appendix - migration from DWM BLE API
The following table summarizes changes in LEAPS BLE API compared to the former DWM BLE API. This is intended to make the transition to LEAPS BLE API easier. The former GATT model used in DWM BLE API is replaced with a request/response model with fewer characteristic than the former model, see the section BLE Communication With UWBS.
Former BLE GATT model
name of
former GATT
characteristic
|
DWM and LEAPS comparison |
|---|---|
Label |
DWM: Standard mandatory GAP
service (0x1800) under the
standard Name characteristic
(0x2A00)
LEAPS: no changes, stays the
same
|
Operation mode |
DWM: current configuration
of UWBS was contained in
special
characteristic
LEAPS: see Operation mode
to read/write configuration
of UWBS, see Firmware Update
to switch between
firmware 1 and firmware 2.
|
Update rate |
DWM: current update rate was contained in special characteristic LEAPS: see section Update rate to read/write current update rate configuration |
Network ID |
DWM: current network Id was contained in special characteristic LEAPS: see the section Network id to read/write current network ID |
Location data mode |
DWM: used as a setting for a special characteristic called “Location data”. LEAPS: not needed anymore, see User Data to get the location from the UWBS and see the section Auto-positioning to get distances when doing auto-positioning procedure |
Location data |
DWM: current location of UWBS (that also contained the distances when doing auto-positioning procedure) was contained in a special characteristic LEAPS: see the section Location data to get location and distances |
Proxy positions |
DWM: current proxy positions was contained in a special characteristic LEAPS: see the section Proxy positions to read positions from neighbor nodes and to receive the proxy positions notifications automatically |
Persisted position |
DWM: persisted position was
written via a special
characteristic
LEAPS: the see the section User Data
on how to write
persistent position to the
UWBS
|
Device info |
DWM: device information, like
configuration, node ID, and
firmware
version was read from a
special characteristic
LEAPS: see the section Device info
to read the node firmware
version, see the section Node id
to read the ID of the node
and see the section Operation mode
to read the node
configuration
|
Statistics |
DWM: statistics were contained in a special characteristic LEAPS: statistics are no longer supported |
MAC stats |
DWM: MAC statistics were contained in a special characteristic LEAPS: MAC statistics is no longer supported |
Cluster info |
DWM: the UWB cluster information was contained in a special characteristic LEAPS: cluster information is no longer supported |
Anchor list |
DWM: the current list of
neighbour anchor nodes was
contained in a special
characteristic
LEAPS: see the section Anchor list
to read the current list
of anchor nodes
|
FW update push |
DWM: firmware update was
started via a special
characteristic that also
used to transfer the new
firmware into the UWBS
LEAPS: see the section Firmware Update
on how to start
firmware update and on how
to transfer the firmware into
the node
|
FW update poll |
DWM: UWBS responded to the BLE
central during firmware
update using notifications
on this characteristic
LEAPS: see the section Firmware Update
on how to perform
firmware update
|
Disconnect |
DWM: BLE central disconnects
via a special characteristic,
it was workaround to deal
with the API bug
LEAPS: not supported since
the bug is fixed
|