Skip to content

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