SODAQ Universal Tracker / Telemetry upload using UDP Integration

This guide contains step-by-step instruction how to to connect your SODAQ NB-IoT boards to ThingsBoard Professional Edition (PE) through the T-Mobile NB IoT network. We will use free ThingsBoard PE demo server cloud.thingsboard.io in this guide. This guide will be useful for anyone who wants to connect their SODAQ NB-IoT boards or other hardware to T-Mobile NB IoT network.

Prerequisites
Integration overview
Step 1. Data Converter configuration
Step 2. Integration configuration
Step 3: Post telemetry and verify the Integration configuration
Next steps

Prerequisites

We assume you have at least one of SODAQ NB-IoT Trackers in your lab that is already connected to your T-Mobile IoT network. We also assume you already have a ThingsBoard PE server or free demo account. Otherwise you can register for a 30-days free demo account here: cloud.thingsboard.io.

We expect you have a very basic knowledge about ThingsBoard. Otherwise we do recommend to complete the following guides:

Getting Started guide.
Platform Integrations guide.

Integration overview

ThingsBoard Platform Integrations feature allows to push data from various platforms and connectivity solutions to ThingsBoard. We will use “UDP” platform integration to consume data from T-Mobile NB IoT Network and automatically register devices in ThingsBoard. Besides configuring the integration, we will also setup ThingsBoard to decode incoming data, store it in the database, visualize on the dashboard and generate alarms based on configurable thresholds.

Step 1. Data Converter configuration

In order to create an Integration, we should create the Uplink Data Converter first. The converter will decode incoming telemetry payload data from T-Mobile NB IoT that contains in encoded hex string to human readable, simplified ThingsBoard data format.

Input data from T-Mobile NB IoT Platform is a byte sequence and after converting them to a hexadecimal string-type look like this:

    "010145292a2bfbfc0000000000000000e6e3355c751a879de31e6535d10306005600d00402"

UDP integration passes the above hexadecimal string to JSON, to get the following payload:

{
    "reports": [{
          "value": "010145292a2bfbfc0000000000000000e6e3355c751a879de31e6535d10306005600d00402"
    }]
}

For this payload, the decoder has the following appearance:

        /** Decoder **/
        
        // The field of input json
        var reports = decodeToJson(payload).reports;
        
        // Result object with device attributes/telemetry data
        var result = {
           deviceName: {},
           deviceType: "tracker",
           telemetry: []
        };
        
        for (var i = 0; i < reports.length; i++) {
          result.deviceName = parseInt(reports[i].value.substring(2, 16), 16);
          var telemetryObj = {
              ts: {},
              values: {}
          };
          timestamp = stringToInt(reports[i].value.substring(32,40))*1000;
          v = stringToInt(reports[i].value.substring(40,42))/100 + 3;
          t = stringToInt(reports[i].value.substring(42,44));
          lat = stringToInt(reports[i].value.substring(44,52))/10000000;
          lon = stringToInt(reports[i].value.substring(52,60))/10000000;
          alt = stringToInt(reports[i].value.substring(60, 64));
          speed = stringToInt(reports[i].value.substring(64, 68));
          sat = stringToInt(reports[i].value.substring(68, 70));
          ttf = stringToInt(reports[i].value.substring(70, 72));
           
          telemetryObj.ts = timestamp;
          telemetryObj.values.batteryVoltage = v;
          telemetryObj.values.temperature = t;
          if(lat !== 0) {
                telemetryObj.values.latitude = lat;      
          }
          if(lon !== 0) {
                telemetryObj.values.longitude = lon;      
          }
          if(alt !== 0) {
                telemetryObj.values.altitude = alt;      
          }
          telemetryObj.values.speed = speed;
          telemetryObj.values.satellitesObserved = sat;
          telemetryObj.values.timetToFirstFix = ttf;
          result.telemetry.push(telemetryObj);
        }
        
        /** Helper functions **/
        
        function stringToInt(hex) {
            return parseInt('0x' + hex.match(/../g).reverse().join(''));
        }
        
        function decodeToString(payload) {
           return String.fromCharCode.apply(String, payload);
        }
        
        function decodeToJson(payload) {
          // convert payload to string.
          var str = decodeToString(payload);
        
          // parse string to JSON
          var data = JSON.parse(str);
          return data;
        }
        
        return result;

After decoding output data will look like this:

{
    "deviceName": 357518080211964,
    "deviceType": "tracker",
    "telemetry": [{
        "ts": 1547035622000,
        "values": {
            "batteryVoltage": 4.17,
            "temperature": 26,
            "latitude": 51.8233479,
            "longitude": 6.4042341,
            "altitude": 6,
            "speed": 86,
            "satellitesObserved": 208,
            "timetToFirstFix": 4
        }
    }]
}

Few things to notice:

The IMEI from the incoming message will become the Device Name in ThingsBoard;
ThingsBoard will automatically create device with type “tracker” and name equal to IMEI;
Timestamp and sensor readings are decoded from incoming hex string.
The following table shows the first byte position and the number of bytes for each encoded field that includes in the incoming hex string:

Field	First Byte	Byte length
deviceName	2	7
ts	16	4
batteryVoltage	20	1
temperature	21	1
latitude	22	4
longitude	26	4
altitude	30	2
speed	32	2
satellitesObserved	35	1
timetToFirstFix	36	1

Go to Data Converters -> Add new Data Converter -> Import Converter
Import following json file: SODAQ UDP Uplink Data Converter (left click on the link and then ‘Ctrl+S’ to download) as described on the following screencast:

Step 2. Integration configuration

Create new integration based on the screencast below.

Please, note that you should copy Integration key and Integration secret as described in the UDP Integration Setup guide.

Fill in the fields with the input data shown in the following table:

Field	Input Data
Name	SODAQ UDP Integration
Type	UDP
Debug mode	True
Uplink data converter	SODAQ UDP Data Uplink Converter
Downlink data converter	(empty)
Port	11560
So Broadcast option	64
Handler Configuration	Handler Type \| HEX

After filling all fields click the ADD button.

Step 3: Post telemetry and verify the Integration configuration

Before we rush to T-Mobile IoT platform configuration, make sure that you complete the Remote integration installation steps.

Also, let’s make sure ThingsBoard is properly configured using simple echo command and netcat utility. We will simulate messages from the T-Mobile IoT platform using the command below. Let’s execute the following command:

echo -e -n '$PAYLOAD' | xxd -r -p | nc -q1 -w1 -u $URL_THINGSBOARD_CLOUD_HOST $PORT

You need to replace $PAYLOAD, $URL_THINGSBOARD_CLOUD_HOST and $PORT respectively with the actual payload, cloud host URL and port.

Sample:

echo -e -n '010145292a2bfbfc0000000000000000e6e3355c751a879de31e6535d10306005600d00402' | xxd -r -p | nc -q1 -w1 -u 127.0.0.1 11560

Navigate to Integration Debug Events and check that data real arrives and is processed successfully.

Device with name 357518080211964 should be created.

Next steps

入门指南 - 这些指南提供了ThingsBoard主要功能的快速概述。
安装指南 - 了解如何在各种操作系统上安装ThingsBoard。
设备连接 - 了解如何根据您的连接方式或解决方案连接设备。
数据看板 - 这些指南包含有关如何配置复杂的ThingsBoard仪表板的说明。
数据处理 - 了解如何使用ThingsBoard规则引擎。
数据分析 - 了解如何使用规则引擎执行基本的分析任务。
高级功能 - 了解高级ThingsBoard功能。
开发指南 - 了解ThingsBoard中的贡献和开发。