BLE Interface
Introduction
The Sentroller Mark 1 is BLE enabled. It is able to connect to mobile phones and exchange information. Compared to WiFi, BLE offers significant power savings and extends the battery life by an order of magnitude. In applications where a mobile app cannot be used to relay information to the internet, a custom Sentroller can be deployed to act as a BLE Internet relay.
BLE Architecture
The sentroller device exposes a subset of features in the BLE 5.0 spec.
The Sentroller BLE is configured as a Peripheral device in Server mode.
As a Peripheral device, the Sentroller advertises itself through bluetooth advertisements. The advertisements are configurable and can contain important information about the state of the product.
As a server the device can accept incoming connection requests from Clients (such as a mobile phone). Once the connection is established, the client can write to, and read data from the sentroller.
Note: The Sentroller cannot initiate a connection to a Client. A client such as the mobile device will have to initiate a connection.
MAC ADDRESS and Device ID
The BLE interface has a MAC address associated with it. This MAC address also serves as the unique device ID for the Sentroller. The BLE MAC ADDRESS IS 6 bytes, usually written in an AA:BB:CC:DD:EE:FF format.
BLE MAC address handling in Android vs iOS
The Bluetooth stack is different in Android and iOS, which impacts how devices are scanned and identified. In Android, when the application requests a scan, the BLE stack scans for devices and reports the device's hardware MAC address.
In iOS however, the stack scans for devices, but obfuscates the hardware MAC address and replaces it with a device 16 byte UUID.
From a mobile app perspective it is critical to know the device's hardware MAC address, since this is the Sentroller's uniqueID. To overcome this, the Sentroller sends its hardware MAC address in a second location BLE advertisment for redundancy.
- Default location: In the BLE spec's source hardware field, grey box name ADV ADDRESS. iOS will obfuscate this and report up the stack
- Sentroller redundancy : In the advertisment data's user field, yellow box (which iOS will not alter).
Thus by inspecting the BLE advertisment, and examining the user data field, the mobile app can determine the true MAC address of the device hardware regardless of Android or iOS.
Sentroller BLE Interface features
The mobile phone can interact with the Sentroller in two ways.
- by connecting to it, and then performing certain actions.
- by simply listening to the advertisements, which contain useful information about the product state.
Interactions with a BLE connection.
-
Provision the Sentroller. Provisioning is the process of associating a new Sentroller device with an end customer account. Usually once provisioned, an end device is assumed to be in operation and in use by the end customer. Provisioning is also a mechanism to connect a device to the Cloud via WiFi, or other connectivity channels.
-
Write data into the Sentroller. The mobile phone is able to write data into the Sentroller. The nature of data written into the Sentroller is customizable and dependent on the end application. For eg. If used in a sensing application, the Sentroller exposes a few configurable parameter such as sensing frequency, reporting intervals, sensor thresholds etc. These can be adjusted by writing to them via the BLE Interface.
-
Read data from the Sentroller. The mobile app is also able to read data from the Sentroller. The nature of data that can be read from the Sentroller is customizable and dependent on the end application. For eg. If used in a sensing application, the Sentroller exposes data such as sensor state, last sensor event, sensor thresholds, battery level etc. These data can be read via the BLE Interface
The Sentroller BLE service
The Sentroller exposes one BLE service with a read and write characteristic for all of the above 3 interaction. By varying the data payload, different functionalities can be realized. Eg, for provisioning a certain data payload is sent, while for writing sensing parameters a different payload is sent. The read and write characteristics each have a data buffer associated with it. To send data to the Sentroller, write into the write buffer. To read data from the Sentroller, read from the read buffer.
Data format for connection based interactions
Once a BLE connection is established between Client (mobile app) and Server (Sentroller/ edge device), the data format is customizable. The packet size is however fixed to 80 bytes.
The Sentroller uses a format called packed JSON data, for efficient over the air communication. Example a JSON such as
{"ssid":"netgear123","passphrase":"secret123"}
is converted to a byte array format such as:
82 a4 73 73 69 64 aa 6e 65 74 67 65 61 72 31 32 33 aa 70 61 73 73 70 68 72 61 73 65 a9 73 65 63 72 65 74 31 32 33
The conversion from JSON -> packed Byte array and packed Byte array -> JSON is handled by a small and light weight program called message pack. The mobile app developer only needs to create and handle JSONs. Message pack is available for multiple languages. Visit msgpack.org for more info.
To send data to the sentroller, create a JSON structure, invoke msgpack to serialize the data, place the resulting byte array data in the buffer of the BLE write characteristic.
Similarly, when reading data from the sentroller, read the buffer of the BLE read characteristic, pass buffer to message pack to de-serialize, which then results in JSON output.
Interactions without a BLE connection
- Reading and interpreting the BLE advertisement. The Sentroller transmits a BLE advertisement self every 300ms (configurable). This BLE advertisement, contains information such as the MAC address of the device, battery level, provisioning status, and also application related information such as sensor state, last event, thresholds etc. By monitoring these advertisment, the mobile app can track the real time state of the device, without having to connect to it. The nature of the data in the advertisment can be configured.
Data Format for connection-less interactions.
BLE advertisments are a fixed 31 byte sized packet (37 bytes in all, of which 6 are used for MAC Address). The size and format of the packet is governed by the Bluetooth specification.
The user data portion of the BLE advertisement (AD 0 to AD N) is configurable based on application need.
BLE advertisements are sent over the air as a simple byte array. Various libraries exist in application development frameworks to extract this byte array into custom data structures.
Data Format.
For BLE advertisment. BLE advertisments are a fixed 31 byte sized packet. The size and format of the packet is governed by the Bluetooth specification. Insert image here
The user data portion of the BLE advertisement is configurable based on application need. Some possible field are 1. Battery level 2. Provisioning status 3. Device Heart beat data 4. Sensor Readings
BLE advertisements are sent over the air as a simple byte array. Various libraries exist in application development frameworks to extract this byte array into custom data structures.