IMBUILDINGS Comfort Sensor

Describes how to integrate the Comfort Sensor from IMBUILDINGS with your application.

IMBUILDING (https://www.imbuildings.com/) provides a Ready for IoT Creators comfort sensor which can be shipped with a IoT Creators SIM card and is already pre-integrated with IoT Creators SCS. The sensor measures CO2, temperature, humditiy and body sense.
In this chapter I explain you how to decode the sensor data to integrate it into your application or IoT platform.

The sensor provides its measurement values as a single data package in hex format. This data is forwarded by the SCS to your application URL as the value element as part of the following JSON payload.

{
    "reports":[{
        "serialNumber":"IMEI:351938100106687",
        "timestamp":1600439712734,
        "subscriptionId":"fa37d89c-a7e2-4f3d-b12f-6002a3642b4c",
        "resourcePath":"uplinkMsg/0/data",
        "value":"0101d880396f026e000153a509520ead061a01"
    }],
    "registrations":[],
    "deregistrations":[],
    "updates":[],
    "expirations":[],
    "responses":[]
}

To get the measurement values of the sensor into your application you need to decode the hex data of the value element to the actual measurement values.

Payload Specification

No matter if you can receive JSON payload from IoT Creators SCS directly in your application or if you have to switch an additional message transformation service in between you have to implement (or to configure) data decoding according to the data specification of IMBUILDING.

As shown in the next picture the payload of the comfort sensor is devided into the four blocks

  • type of payload
  • version of payload format
  • device info
  • measurement data
Major payload structure of IMBUILDING Comfort SensorMajor payload structure of IMBUILDING Comfort Sensor

Major payload structure of IMBUILDING Comfort Sensor

In the following image you see the detailed payload specification of the Comfort Sensor.

Payload specification of IMBUILDING Comfort SensorPayload specification of IMBUILDING Comfort Sensor

Payload specification of IMBUILDING Comfort Sensor

In the following you will get a simple sample how you can decode payload of the Comfort Sensor for your application.

Decoding the Payload

Generally IMBUILDINGS provide for all its sensors JavaScript code to decode the sensor data at
https://github.com/IMBUILDINGS/PayloadParser/blob/master/ttn-decoder.js .
In the following I give you some source code examples how to decode the sensor data of the comfort sensor with JavaScript and Python.

📘

Don't forget that the data in the value element of the forwarded JSON message is in hex format. By this each byte consists of two character.

JavaScript Sample

function decode(hexString) {
        
  //split the hex string into an array by two-characters tuples
    hexData = hexString.match(/..?/g);

  typeVersion = hexData[0] + hexData[1]
    
    if (typeVersion == '0101') {
        
        d = {
            "status"      : parseInt(hexData[8], 16),
            "batteryV"    : parseInt(hexData[9] + hexData[10], 16) / 100.,
            "temperature" : parseInt(hexData[12] + hexData[13], 16) / 100.,
            "humidity"    : parseInt(hexData[14] + hexData[15], 16) / 100.,
            "co2"         : parseInt(hexData[16] + hexData[17], 16),
            "presence"    : parseInt(hexData[18], 16)
        };
        
    } else {
        throw new Error("Unsupported type and version " + typeVersion);
    }
        
    return d;
}

For the payload of 0101d880396f026e000153a509530d51043201 the decoding function provided me the following result:

{
    "status":0,
    "batteryV":3.39,
    "temperature":23.87,
    "humidity":34.09,
    "co2":1074,
    "presence":1
}

Python Sample (V >= 3.2)

def decode(hexString):
    a = bytearray.fromhex(hexString)
    type = a[0]
    version = a[1]
    if type == 1 and version == 1:
        d = {
            "status"      : a[8],
            "batteryV"    : int.from_bytes(a[9:11], "big") / 100.,
            "temperature" : int.from_bytes(a[12:14], "big") / 100.,
            "humidity"    : int.from_bytes(a[14:16], "big") / 100.,
            "co2"         : int.from_bytes(a[16:18], "big"),
            "presence"    : a[18]
        }
        return d
    else:
        raise Exception("Unsupported type %d and version %d" % (type, version))

For the payload of 0101d880396f026e000158a50a4b121503d301 the decoding function provided me the following result:

{
  'status': 0, 
  'batteryV': 3.44, 
  'temperature': 26.35, 
  'humidity': 46.29, 
  'co2': 979, 
  'presence': 1
}

Did this page help you?