Star
Try it now
Solutions
Customers
Use Cases
Partners
About Us
Pricing Docs Guides

SODAQ Universal Tracker / Telemetry upload using UDP Integration


ThingsBoard PE Feature


Only ThingsBoard Professional Edition supports Platform Integrations feature.

See ThingsBoard PE Installation Options to install ThingsBoard PE.

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

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:

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.

    "010145292a2bfbfc0000000000000000e6e3355c751a879de31e6535d10306005600d00402"
{
    "reports": [{
          "value": "010145292a2bfbfc0000000000000000e6e3355c751a879de31e6535d10306005600d00402"
    }]
}
        /** 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;


{
    "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:

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

Step 2. Integration configuration

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

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