Star

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 to have a very basic knowledge about ThingsBoard, so we do recommend to complete the Getting Started 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.

    "010145292a2bfbfc0000000000000000e6e3355c751a879de31e6535d10306005600d00402"
{
    "reports": [{
        "value": "01014294292BE0E50000000000000000FBE61D5D56268710211F249E150319000100000901"
    }]
}
    /** 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;
      telemetryObj.values.imei = result.deviceName;
      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": "0123456789",
    "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 Uplink data converter
Downlink data converter (empty)
Port 12345
So Broadcast option 128
Charset Name UTF-8
Handler Configuration Handler Type | HEX

Step 3: Post telemetry and verify the Integration configuration

Before we rush to T-Mobile IoT platform configuration, 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 commands below and also take the value of the key named ‘value’ from json above Let’s execute the following command:

payload=01014294292BE0E50000000000000000FBE61D5D56268710211F249E150319000100000901

echo $payload | xxd -r -p | nc -u $URL_THINGSBOARD_CLOUD_HOST 12345

you need to replace $URL_THINGSBOARD_CLOUD_HOST with actual cloud host URL

Device with name ‘13845261746254392’ should be created:

Now you can delete this dummy device if needed.

Step 4: Check Integration Debug Events

Navigate to Integration Debug Events, similar to Step 3 and double check that data from real devices arrives and is processed successfully. Please note that it may take some time (up to 30 minutes based on our experience) for new message to start arriving.

Next steps