Custom Integrations

This document describes how you can create your own integrations based on device data received from the T-Mobile CDP platform.

Device Telemetry Data (Payload) in JSON

From the highest level the CDP reports all kinds of events in an JSON formatted body containing a set of arrays;

{
    "reports": [],
    "registrations": [],
    "deregistrations": [],
    "updates": [],
    "expirations": [],
    "responses": []
}

The reports array will contain the devices' telemetry (uplinkMsg/0/data), we will work with this one.

Of course you don't need to use these specific integrations you can create the integrations towards most platforms by yourself but generally you need to convert the data to the targets wishes. A general approach to this will also described here.

NodeRed Example

In this example I used node-red to visualise the steps needed. For instructions on installation and manuals you can visit their website (https://nodered.org/). Node-red is a flow based programming environment based on node-js. Node-red is great for prototyping but not really well suited for production grade environments.Please note that securing node-red requires special attention by default your flow will be accessible to the public.

In the next part will explain the configuration of each of the nodes

Node 0)
You can use this test message when you have not yet an working CDP account or SIM card or hardware module.

Configure the JSON payload as

{
    "reports": [
        {
            "serialNumber": "IMEI:358878080020537",
            "timestamp": 1524582877912,
            "subscriptionId": "fab4fabf-3e60-401a-bbea-cef815635d98",
            "resourcePath": "uplinkMsg/0/data",
            "value": "aabbccdd"
        }
    ],
    "registrations": [],
    "deregistrations": [],
    "updates": [],
    "expirations": [],
    "responses": []
}

Node 1)
This is HTTP receiver node is the application endpoint you register in the CDP. Using this example call.
Configure:
method : POST
url : /my_application

curl -X PUT \
  https://api.scs.iot.telekom.com/m2m/applications/registration \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic xxx' \
  -H 'Content-Type: application/json' \
  -d '{	"headers" : {	},
	"url" : "https://<this node red server>/my_application"
}
'

Node 2)
This change Node extracts the reports array from the message and discards the remainder.

Set msg.payload to msg.payload.reports

Node 3)
This split node outputs a separate message for every serialnumber. This node needs no further configuration.

Node 4)
This Javascript function node builds up the message according to the targets wishes.

In my case it contains;

msg.timestamp = msg.payload.timestamp;
msg.serialNumber = msg.payload.serialNumber;   
msg.topic = msg.payload.serialNumber.trim();   
msg.resourcePath = msg.payload.resourcePath;
msg.payload.raw =  msg.payload.value;
    
return msg;

Node 5)
This optional Javascript function node converts your payload to a readable characters. But this is of course only if you send readable / printable data.

// Convert hex to string 

var str = "";
for (var n=0; n<msg.payload.value.length; n+=2) {
    str += String.fromCharCode(parseInt(msg.payload.value.substr(n,2), 16));
}
msg.payload.value = str;
return msg;

And as a final step you can push the message forward to your preferred target. Possibly credentials or API keys should be added to the forwarded message.

This flow can be downloaded from our GitHub repository.

Extending the palette with more integrations

In node-red you can import prebuilt nodes to add to your pallette. These nodes offer default integrations. Some examples are;

PubNub

IFTT
Connect to the makerschannel of IFTTT.

Twitter

Or the IOT oriented variant;
DWEET.IO

Or even create your own dashboard with;
dashboard

For the cloud platforms IOT hubs;
Azure IOT HUB
AWS IOT HUB
Google IOT Core
IBM

Other flows directly to other components of their services are also available.

HTTP Integration Example with AllThingsTalk

Allthingstalk (https://maker.allthingstalk.com/)
For example if you want to send a message to the default HTTP receiver of AllthingsTalk this format could be used in a Javascript Function Node

msg.headers = {};
msg.headers['accept'] = 'application/json';
msg.headers['content-type'] = 'application/vnd.allthingstalk+abcl';
msg.headers['Authorization'] = 'Bearer maker:4VGS3OfUwwR4W1VeVzIblq4hTKthb1i1gaC1TRF';
msg.payload = msg.payload.raw
return msg;

And a consecutive HTTP publish node;

Configure:
method: PUT
url : https://api.allthingstalk.io/device//state

DIY - Learn how to do it!

If you want to know more about the integration of specific modules/devkits, plattforms, applications and/or off-the-shelf sensors and IoT solutions and actually start doing it yourself, please check out our "Integrations" chapter.