Skip to content

BLE Device Service Component

The BLE Device Service components integrate the Bluetooth Low Energy protocol with Edge Xrt.

The BLE Device Service components support the following features:

  • Read and Write GATT characteristics
  • BLE Notifications for characteristics change of value
  • BLE Manufacturer Advertisement data packets
  • BLE device discovery

Prerequisites

D-Bus

D-Bus daemon is required to be running on the host machine to allow communication between the device service and the BlueZ daemon

Bluez

Linux Bluetooth module is required to be installed and running on the host machine.

BLE Device Service Configuration

Note

The core components required for running BLE (and all other device services) are contained in Device Service Component Configuration. Please refer to this page to ensure the appropriate core components are assigned before continuing.

With those components assigned, there are also the following optional BLE Driver options that can be used to configure the device service.

BLE Driver Options

Parameter Type Description Default Value
BLE_Interface String The bluetooth interface which to run the device service on. For example, hci0, hci1, hci2 … None - This is always required and cannot be left to a default value
BLE_DiscoveryDuration Unsigned Int The duration of each discovery 10
BLE_DiscoveryInterval Unsigned Int The interval between discovery 0
BLE_AdvertisementEnabled Bool Whether the device service should process advertisement packets True

A template of the BLE Device Service configuration file is provided below, where the driver options have been set to demonstrate their usage:

{
  "Library": "libxrt-ble-device-service.so",
  "Factory": "xrt_ble_device_service_factory",
  "Name": "ble",
  "TelemetryTopic": "xrt/devices/ble/telemetry",
  "RequestTopic": "xrt/devices/ble/request",
  "ReplyTopic": "xrt/devices/ble/reply",
  "DiscoveryTopic": "xrt/devices/ble/discovery",
  "StateDir": "./deployment/state",
  "ProfileDir": "./deployment/profiles",
  "Scheduler": "sched",
  "Logger": "logger",
  "ThreadPool": "pool",
  "Bus": "bus",
  "Driver": {
    "BLE_Interface": "hci0"
  }
}

BLE Device Profile

Details on general profile usage can be found on the Device Profiles page.

The following sections will cover how device resources are mapped to BLE Characterisitics.

Attributes

The attributes used in a BLE device resource are described in the following table:

Attribute Description Valid Values
characteristicUuid Mandatory, unless isAdvertisement or isNotification is true.
The UUID of the device's characteristic. 		String
serviceUuid The UUID of the service to which the characteristic belongs. String
isAdvertisement Indicates that the resource is an advertisement packet. Bool
isNotification Indicates that the resource controls a notification. Bool
deviceResource Mandatory if isNotification is true.
References an already existing device resource which supports BLE notifications. 		String
startByte Specifies the byte offset from which to start reading the value. Unsigned Int
conversionFunction Defines which conversion function to use.
For more information on conversion functions, see Conversion Functions below. 		String
rawType Mandatory if conversionFunction is defined.
Defines how to interpret the data read from the BLE device to be used in the conversion function. 		String

Data Types

When a GATT attribute is read, the value is recieved as raw binary data. The following table lists the Xrt data types that the device service supports and can interpret the data as.

Xrt Data Type
Bool
Int8
UInt8
Int16
UInt16
Int32
UInt32
Int64
UInt64
Float32
Float64
String
Byte Array

Example Device Resources

The device resource below allows for read access to a Heart rate measurement:

{
  "name": "HeartRateMeasurementData",
  "description": "Heart Rate Measurement",
  "attributes": {
    "characteristicUuid": "00002a37-0000-1000-8000-00805f9b34fb",
    "serviceUuid": "0000180d-0000-1000-8000-00805f9b34fb"
  },
  "properties": {
    "valueType": "UInt64",
    "readWrite": "R"
  }
}

So that the device service will receive a notification when the heart rate measurement value changes, we can define a Notification resource that points to the above HeartRateMeasurementData resource. A put request to this resource will start or stop the production of notifications for the HeartRateMeasurementData resource.

{
  "name": "HeartRateMeasurementNotification",
  "description": "Heart Rate Notification",
  "attributes": {
    "deviceResource": "HeartRateMeasurementData",
    "isNotification": true
  },
  "properties": {
      "valueType": "Bool",
      "readWrite": "RW"
  }
}

Sometimes, we only want to read a selection of bytes from a characteristic. We can use some attributes to help us extract these bytes. Since the type of this resource is a Unsigned 64 bit integer, the device service will read 8 bytes with an offset of 4 from the start of the characteristic. 

{
  "name": "Data",
  "attributes": {
    "characteristicUuid": "00002a37-0000-1000-8000-00001bad1dea",
    "startByte" : 4
  },
  "properties": {
    "valueType": "UInt64",
    "readWrite": "R"
  }
}

The device service provides conversion functions for some supported devices. The following resource example will read the raw UInt16 value from the device and then use the CC2650Temperature conversion function to produce a Float32 Degrees Celsius reading.

{
  "name" : "CC2650HDC1000Temperature",
  "attributes": {
    "characteristicUuid": "000aa21-0451-4000-b000-000000000000",
    "startByte" : 0,
    "rawType" : "Uint16",
    "conversionFunction" : "CC2650Temperature"
  },
  "properties": {
    "valueType": "Float32",
    "readWrite": "R"
  }
}

Advertisement resources are structured in a similar way. The following example is of type UInt8Array with no startByte attribute set, meaning the resource refers to all the device's advertisement data. 

{
  "name": "All",
  "description": "All the devices advertisement data",
  "properties": {
    "value": {
      "type": "Uint8Array",
      "readWrite": "R"
    }
  },
  "attributes": {
    "isAdvertisement": "true"
  }
}

The next example demonstrates an advertisement resource of type UInt8 with startByte set to 1 in order to access one byte of data at this chosen offset.

{
  "name": "Battery",
  "description": "Battery lvl in % of voltage",
  "properties": {
    "value": {
      "type": "Uint8",
      "readWrite": "R"
    }
  },
  "attributes": {
    "isAdvertisement": "true",
    "startByte": "1"
  }
}

Conversion Functions

conversionFunction Strings are used as a lookup to find a corresponding function. Usually they are device- or sensor-specific and are used to convert a raw reading to a meaningful value.

Below is a table of available conversion functions.

Name Description Sensor
Conv16ToFloat Casts a INT16 to a FLOAT32 N/A
ConvU16ToFloat Casts a UINT16 to a FLOAT32 N/A
Conv32ToFloat Casts a INT32 to a FLOAT32 N/A
ConvU32ToFloat Casts a INT16 to a FLOAT32 N/A
CC2650Temperature Converts a raw temperature reading (UINT16) from a HDC1000 sensor to degrees Celsius (FLOAT32) Texas Instruments CC2650
CC2650Humidity Converts a raw humidity reading (UINT16) from a HDC1000 sensor to relative humidity (FLOAT32) Texas Instruments CC2650
CC2650IRTemperatureAmbience Converts an ambience temperature reading (UINT16) from a TMP007 sensor to degrees Celsius (FLOAT32) Texas Instruments CC2650
CC2650IRTemperatureObject Converts an object temperature reading (UINT16) from a TMP007 sensor to degrees Celsius (FLOAT32) Texas Instruments CC2650
CC2650BarometricTemperature Converts a raw temperature reading (UINT32) from a BPM280 sensor to degrees Celsius (FLOAT32) Texas Instruments CC2650
CC2650BarometricPressure Converts a raw pressure reading (UINT32) from a BPM280 sensor to degrees Celsisus (FLOAT32) Texas Instruments CC2650
CC2650OpticalSensor Converts a raw optical sensor reading (UINT16) from a OPT3001 sensor to Light Intensity (LUX) (FLOAT32) Texas Instruments CC2650
CC2650Gyroscope Converts raw gyroscope data readings (INT16) from a MPU9250 sensor to Degrees/second (FLOAT32) Texas Instruments CC2650
CC2650Accelerometer2G Converts raw accelerometer data readings (INT16) from a MPU9250 sensor to (2G) Gravity (FLOAT32) Texas Instruments CC2650
CC2650Accelerometer4G Converts raw accelerometer data readings (INT16) from a MPU9250 sensor to (4G) Gravity (FLOAT32) Texas Instruments CC2650
CC2650Accelerometer8G Converts raw accelerometer data readings (INT16) from a MPU9250 sensor to (8G) Gravity (FLOAT32) Texas Instruments CC2650
CC2650Accelerometer16G Converts raw accelerometer data readings (INT16) from a MPU9250 sensor to (16G) Gravity (FLOAT32) Texas Instruments CC2650
CC2650Magnetometer Converts raw magnetometer data readings (INT16) from a MPU9250 sensor to magnetism in micro Tesla's (FLOAT32) Texas Instruments CC2650
AgoraLSM9DS1Magnetometer Converts raw magnetometer data readings (UINT32) from a LSM9DS1 sensor to magnetism in micro Tesla's (FLOAT32) STMicroelectronics LSM9DS1
AgoraLSM9DS1Gyroscope Converts raw gyroscope data readings (UINT32) from a LSM9DS1 sensor to Degrees/Second (FLOAT32) STMicroelectronics LSM9DS1
AgoraLSM9DS1Accelerometer Converts raw accelerometer data readings (UINT32) from a LSM9DS1 sensor to Gravity (FLOAT32) STMicroelectronics LSM9DS1
AgoraICM20602Accelerometer Converts raw accelerometer data readings (UINT32) from a ICM20602 sensor to Gravity (FLOAT32) TDK Invensense ICM-20602
AgoraICM20602Gyroscope Converts a raw gyroscope data reading (UINT32) from a ICM20602 sensor to Degrees/Second (FLOAT32) TDK Invensense ICM-20602
AgoraBME680Temperature Converts a raw temperature reading (INT16) from a BME680 sensor to degrees Celsius (FLOAT32) Bosch BME680
AgoraBME680Humidity Converts a raw humidity reading (INT16) from a BME680 sensor to Relative Humidity (FLOAT32) Bosch BME680
AgoraBME680Pressure Converts a raw pressure reading (INT16) from a BME680 sensor to Hectopascals (FLOAT32) Bosch BME680
AgoraSI7021Temperature Converts a raw temperature reading (INT16) from a SI7021 sensor to degrees Celsius (FLOAT32) Silicon Labs Si7021-A20-GM
AgoraSI7021Humidity Converts a raw humidity reading (INT16) from a SI7021 sensor to Relative Humidity (FLOAT32) Silicon Labs Si7021-A20-GM
AgoraDistance Converts a raw distance reading (UINT16) from a VL53L0X sensor to Meters (FLOAT32) STMicroelectronics VL53L0X

Device Commands

See the Device Profiles page for details on how to define device commands for grouping device resources for fewer requests.

BLE Device Provisioning

The following section will explain how to configure a device for the BLE Device Service.

Note

For information on dynamic device additions, removals, and updates, please see the MQTT API Guide.

Provisioning

To provision a BLE device, the BLE protocol must be used along with the MAC protocol property which specifies the MAC address of the BLE device.

A basic example of a BLE device provision within the devices.json file is provided below:

{
  "BLESimulator": {
    "name": "BLESimulator",
    "profileName": "ble-simulator-profile",
    "protocols": {
      "BLE": {
        "Address": "00:01:BA:D1:DE:A5"
      }
    }
  }   
}

Device Protocol Properties

There are some additional protocol properties that can be used to configure a device:

Parameter Type Description Default Value
MAC String Mandatory

The mac address of the device in the format: AA:BB:CC:DD:EE:FF 		N/A
Alias String Optional

The alias of the device 		N/A
Name String Optional

The name of the device 		N/A

BLE Device Service Interaction

For information on how to dynamically execute reads, writes, setting up schedules, triggering device discovery and much more, please refer to the MQTT API Guide.

For interactive examples of the BLE Device Service refer to BLE Xrt Example. Follow the instructions in those links which will demonstrate many features of Edge Xrt with the device service running against a BLE simulator.

Run the BLE Device Service

Standalone on Command Line

Find details on how to run the BLE Device Service on the Run Device Services page.

Docker Container

Find details on how to run BLE Device Service in a docker container at Run BLE Docker