Converting Vendor-specific Data
Many BLE devices provide the values of Generic ATTribute Profile (GATT) characteristics in a vendor-specific format. To convert the data from these vendor-specific formats to a standard format for Edge Xpert, you can apply conversion functions that operate on the data as it is acquired from the device. The BLE Device Service provides several built-in conversion functions that you can apply to suit your data translation requirements.
The BLE Device Service provides conversion functions for specific BLE devices. We recommend that you use device-specific conversion functions where possible. If no conversion function is available for your device, you can use a generic conversion function.
BLE Conversion Functions
In BLE device profiles, conversionFunction strings are used as a lookup (with no wildcard matching) to find a corresponding function.
Conversion functions can only be used on a valid input type. For example, when getting CC22650TemperatureData, use a conversionFunction that operates on two bytes of data.
Conversion functions can only be used when a rawType attribute is specified in the device resource.
Applying a Conversion Function
Note
To apply a conversion function, you must include both the rawType and conversionFunction attributes in the device resource. If either attribute is excluded, the conversion function is not applied and the reading will be left in its original format.
The conversionFunction attribute indicates the conversion function to use, as shown in the following extract from a device profile:
The following device resource extract shows how these attributes are defined:
deviceResources:
- description: I/OConfiguration
name: CC2650HumidityData
...
attributes:
characteristicUuid: f000aa21-0451-4000-b000-000000000000
conversionFunction: CC2650Humidity
rawType: Uint16
startByte: 2
- description: I/OConfiguration
name: CC2650TemperatureData
...
attributes:
characteristicUuid: f000aa21-0451-4000-b000-000000000000
conversionFunction: CC2650Temperature
rawType: Uint16
startByte: 0
Note
The startByte attribute specifies the byte offset from which to read the value.
If the startByte plus the size in bytes of the type is greater than the number of bytes in the byte array of the raw reading, an out-of-bounds error will be produced. This is because it cannot read beyond the byte array of the raw reading.
For example, if the byte array of the raw reading is six bytes and the deviceResource has a startByte of four with a rawType of UInt32, the device service raises an error and does not process the reading.
Raw Types
The rawType attribute specifies the original data type of the reading. For example, in the device resource above, a UInt16 value is read from the raw data, and a conversion function is applied to the data to translate it to degrees Celsius (Float32). We include the UInt16 rawType so that the BLE Device Service knows how many bytes to read from the raw data.
The available options for rawType are as follows:
- UInt8
- UInt16
- UIInt32
- UInt64
- Int8
- Int16
- Int32
- Int64
- Float32
- Float64
Available Conversion Functions
The following sections describe the available conversion functions for different sensors and provide examples of their operation.
Note
You will notice that multiple names are sometimes used for the same conversion function. This is because the device name is included in the conversion function name.
See below for a list of available conversion functions.
Generic Conversion Functions
| Name | Description |
|---|---|
Conv16ToFloat |
Casts an Int16 to a FLOAT32 |
ConvU16ToFloat |
Casts a Uint16 to a FLOAT32 |
Conv32ToFloat |
Casts an Int32 to a FLOAT32 |
ConvU32ToFloat |
Casts an Int16 to a FLOAT32 |
Sensor-specific Conversion Functions
| Name | Description | Sensor |
|---|---|---|
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 |
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 |