Professional Edition
ThingsBoard Documentation
Cloud Professional Edition Community Edition IoT Gateway License Server Trendz Analytics
Try it now Pricing
SODAQ Universal Tracker / Telemetry upload using UDP Integration
Getting Started Documentation Guides Installation Architecture API FAQ

On this page

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

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:

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:
FieldFirst ByteByte 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:
FieldInput 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:

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