Data converters

About data converters

In order to make the creation and management of devices within Thingsboard consistent, they created the platform assuming that all data that is used in their platform is formatted the same way. To make this possible they created something they call "Data convertes" that processes incoming data and formats the data accordingly. The converter expects a timestamp as well as a device name, any other expected fields must be defined within the data converter. The data converter is used within an integration, the device name links the upload through the integration to a device.

Creating and configuring a data converter

Adding a Data converter

To create a data converter navigate to the data converter section within Thingsboard. Press  on the left hand side followed by  in the bottom right corner. A new window in Thingsboard should now have opened for you, such as shown below.

Configuring a Data converter

Input

Here we gave the converter the name "wind-buoy-converter". The type denotes if the converter should be used for data coming in or leaving Thingsboard. Where "Uplink" means the data should be coming in. The decoder function must be created to properly format the data. It is easier to just show how this can be done, rather than explain it. The following snippet shows the format the wind-bouy publishes to the MQTT-broker, hence the data that comes in to the converter.

{
    "deviceName": "wind_Vartdalsfjorden",
    "WindGust": "10.78125",
    "latitude": "63.08813095",
    "WindSpeed": "7.96875",
    "WindDirection": "156.44531",
    "time": "2018-12-19T12:50:00.000000000",
    "longitude": "8.15624237"
}

Decoder function

In order to decode (or convert) this input the javascript added to the converter must be configured as shown below.

// Decode an uplink message from a buffer
// payload - array of bytes
// metadata - key/value object

/** Decoder **/

// decode payload to string
var data = decodeToJson(payload);
var payloadStr = decodeToString(payload);

var result = [];
// decode payload to JSON
// var data = decodeToJson(payload);

var deviceType = metadata.deviceType;



// Result object with device attributes/telemetry data
result.push({
   deviceName: data.deviceName,
   deviceType: deviceType,
   telemetry: {
       ts: data.time,
       values: {
        latitude: data.latitude,
        longitude: data.longitude,
        windGust: data.WindGust,
        windSpeed: data.WindSpeed,
        windDirection: data.WindDirection,
        rawData: payloadStr
       }
   }
});

/** Helper functions **/

function decodeToString(payload) {
   return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
   // covert payload to string.
   var str = decodeToString(payload);

   // parse string to JSON
   var data = JSON.parse(str);
   return data;
}

return result;

Output

Processing the input through the converter will yield this output.

[{
    "deviceName": "wind_Vartdalsfjorden",
    "telemetry": {
        "ts": "2018-12-19T12:50:00.000000000",
        "values": {
            "latitude": "63.08813095",
            "longitude": "8.15624237",
            "windGust": "10.78125",
            "windSpeed": "7.96875",
            "windDirection": "156.44531",
            "rawData": "{\n    \"deviceName\": \"wind_Vartdalsfjorden\",\n    \"WindGust\": \"10.78125\",\n    \"latitude\": \"63.08813095\",\n    \"WindSpeed\": \"7.96875\",\n    \"WindDirection\": \"156.44531\",\n    \"time\": \"2018-12-19T12:50:00.000000000\",\n    \"longitude\": \"8.15624237\"\n}"
        }
    }
}]

Testing the data converter

When configuring the Data converter you get an option to test the decoder function. To test it press . A new window as shown below should present itself where you can test your decoder function and verify that it actually works.

Resources

In this page only one example of the converter is given. However, if you go to our github-repository fremtidens-rederikontor/mi-iot/thingsboard-javascripts you can inspect every converter we have created.