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

The BLE central device directly connects with the UWBS to set up and retrieve

parameters. It needs to connect to each device individually to configure/control. The communication with the UWBS is based on request-response model (see BLE GATT Model).

The UWBS accepts TLV API requests and notifies the central of TLV API response. The BLE central must enable notifications before any request to receive the response. The UWBS supports only one request at a time. See LEAPS API for details on encoding all TLV frames recognized by the UWBS. Besides accepting requests, the UWBS also generates events. To enable the events:

• Enable events in the UWBS by leaps_ble_evt_cfg_set.

• enable notification on dedicated characteristic

The payload of all API requests, responses and events starts with a 2-byte long TLV header where the first byte corresponds to the type of the frame, followed by second byte representing the the frame’s length. The length should be used to check if the frame is complete when streaming via the BLE characteristics.

---

BLE LUS (LEAPS UART Service) Interface

The LEAPS UWBS supports additional BLE LUS (LEAPS UART Service) interface, following steps to set up the interface.

Note

If UART shell is being opened, BLE shell will not be accessed.

1. Install the python ble-serial library with below command:

   python –m pip install ble-serial
   

   Note

   If the Windows is being used, please follow additional steps “Additional steps for Windows” in this link ble-serial.

2. Use below command to find device. LEAPS board should appear with name as “LEAPS….”.

   ble-scan
   

   and the result of successful scan:

   

3. To connect serial port, open a terminal and run below commands with MAC addresses found at above steps.

   ble-serial -d CA:E5:56:1F:57:3D -r e8573d97-6758-11e9-8860-cb4385c24b83 -w e6bfa235-6758-11e9-979f-5b24c4603eb8 -t 10
   

4. If successful, it will display as below

   

5. As the log, the script created a serial port with name as “/tmp/ttyBLE” to communicate with serial port on LEAPS board. Let’s this terminal running, open another terminal and use tools as minicom to access this serial port.

6. Press double enter to enter shell.

---

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

The system supports two modes of operation on BLE: No encryption or Encryption only (AES-OFB). The encryption features and operation are described in the following section:

• 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

Type 0x40 means request/command status

Type 0x41 means position

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

---

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:

1. Measure:

   1. Initiator is found and verified (the node must be a real initiator, not just configured as initiator, see Operation mode and BLE Advertisements)

   2. Connect to initiator.

   3. Enable “location ready” event by leaps_ble_evt_cfg_set if not enabled already (don’t forget to enable BLE cccd notifications on characteristics).

   4. Start autopositioning by leaps_autopos_start request.

   5. Received all measured distances from the initiator, save the measured distances to the matrix.

   6. Disconnect from initiator.

   7. Get distances from all other (non-initiator) nodes:

   1. Connect

   2. Get location data from UWBS using API request leaps_loc_get and save the distances to the matrix.

   3. Disconnect

2. Evaluate the measure distances, check orthogonality, and compute positions.

3. 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

1. CDEV connects to the UWBS.

2. CDEV starts updating the FW by leaps_fw_update_start.

3. 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.

4. CDEV sends chunks of FW by leaps_fw_update_xfer.

5. CDEV resets the UWBS after the last chunk is sent successfully.

Updating the ELDR binary

1. CDEV reconnects after the UWBS reboot.

2. CDEV starts updating the ELDR by leaps_fw_update_start.

3. CDEV sends chunks of ELDR by leaps_fw_update_xfer.

4. CDEV resets the UWBS after the last chunk is sent successfully.

5. 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:

1. CDEV resets the UWBS by leaps_reset command which will cause UWBS to disconnect from the CDEV.

2. CDEV waits 1 sec.

3. CDEV tries to connect to UWBS again and check its firmware status (see Device info).

Appendix - Bibliography

1. https://devzone.nordicsemi.com/question/55309/connection-issues-with-android-60-marshmallow-and-nexus-6/

2. http://stackoverflow.com/questions/37151579/schemes-for-streaming-data-with-ble-gatt-characteristics

3. What to keep in mind when developing your BLE Android app

4. Integration Guide

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
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