SODAQ Universal Tracker / Telemetry upload using UDP Integration

ThingsBoard PE Feature

Only Professional Edition supports Platform Integrations feature.
Use ThingsBoard Cloud or install your own platform instance.

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 thingsboard.cloud 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: thingsboard.cloud.

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:

1
    "010145292a2bfbfc0000000000000000e6e3355c751a879de31e6535d10306005600d00402"

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

1
2
3
4
5
{
    "reports": [{
          "value": "010145292a2bfbfc0000000000000000e6e3355c751a879de31e6535d10306005600d00402"
    }]
}

• For this payload, the decoder has the following appearance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
        /** 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "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:

• 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:

• 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:

1
2
3
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:

1
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

• Getting started guides - These guides provide quick overview of main ThingsBoard features. Designed to be completed in 15-30 minutes.

• Connect your device - Learn how to connect devices based on your connectivity technology or solution.

• Data visualization - These guides contain instructions on how to configure complex ThingsBoard dashboards.

• Data processing & actions - Learn how to use ThingsBoard Rule Engine.

• IoT Data analytics - Learn how to use rule engine to perform basic analytics tasks.

• Advanced features - Learn about advanced ThingsBoard features.

• Contribution and Development - Learn about contribution and development in ThingsBoard.