Ubidots and The Things Industries have partnered to create a pre-built integration, allowing users to easily forward sensor data from The Things Stack's network server to Ubidots using plugins.
This plugin is optimized to automatically decode The Things Stack v3 Uplink JSON schema (parsing items such as gateways' metadata so you don’t have to!), while still allowing for full decoder customization using NodeJS.
Requirements
An active Ubidots account. This plugin is available to our free STEM users too 😎
An active The Things Stack account.
1. Creating a TTS Plugin
A TTS plugin is a serverless function that exposes a private HTTP Endpoint URL optimized to decode The Things Stack's uplink JSON payloads. Every time an HTTP POST request is received at such URL, a pre-defined decoding function will be executed.
To create your private HTTP endpoint URL:
In your Ubidots account, go to the "Devices" tab, click on "Plugins", then click on the "+" icon to create a new Plugin. Search for the TTS Plugin and click on it:
2. The plugin instructions will appear. Click on the "Next" icon, then review the input parameters:
Ubidots device type: An Ubidots device type will be created and linked to this plugin. This allows you to make batch changes to all of the devices that receive data through this plugin.
Ubidots token: Select the Ubidots token you'd like to use for this plugin. We recommend creating a new token dedicated to this plugin only, in case you need to increase its rate limit in the future.
3. Finish the process and a new plugin will appear in the Plugins list:
4. Click on the newly-created TTS Plugin, click on the "Decoder" tab, and copy the "HTTPs Endpoint URL". The structure of the URL is as follows:
https://dataplugin.ubidots.com/api/web-hook/<PLUGIN-ID>
5. Finally, go to your The Things Stack account, click on the desired Application then on "Integrations" => "Webhooks", then click on "Add webhook" => "Ubidots" and fill in these fields:
Webhook ID: Pick a name for your webhook.
Plugin ID: Unique identifier (
<PLUGIN-ID>) found in your plugin’s HTTPS URL.Ubidots token: Token used to authenticate Ubidots' API requests.
Finally, the webhook should look something like this:
2. Decoding payloads from TTS-connected devices
After creating a TTS plugin and clicking on it, you will see a "Decoder" tab which contains a "Decoding Function" that you can edit at will, in order to decode your data frames.
By default, you will see a pre-loaded sample decoder that does the following:
Logs RSSI and SNR to an Ubidots variable; one for each gateway receiving a signal from your device.
Logs a Frame counter and Port to Ubidots variables.
If found, the JSON key "uplink_message.decoded_payload" will be forwarded as-is to Ubidots, assuming it has an Ubidots-friendly format. If not, then a custom decoder can be used to decode the base64 frame sent in "uplink_message.frm_payload".
Ubidots will automatically create a device every time a payload from a new device is received. This saves you the need to manually create hundreds or thousands of devices, or copy-and-paste DevEUI's from one platform to the other.
See here's how a sample TTS' JSON payload is mapped to an Ubidots device and its variables:
Note that you can change some, but not all of the above mappings:
2.1. Data mapping that CAN be edited from the decoding function:
Gateway metadata: You may choose to drop unwanted gateway data such as SNR or RSSI.
Variables: You may choose to drop variables, or even create new ones using NodeJS 10 (see supported libraries).
Timestamp: You may choose to ignore the payload's "received_at" timestamp and have Ubidots' API assign one automatically upon reception.
2.2. Data mapping that CANNOT be edited in the decoding function:
Device label and name: The plugin always uses TTS' "device_id" as Ubidots' device label. Upon creation, Ubidots will inherit the device name from the device label, but you can change the name later.
Device properties: The plugin always uses these keys as Ubidots' device properties: "end_device_ids.application_ids.application_id", "end_device_ids.dev_eui", and "end_device_ids.dev_addr".
If you wish to have control over these, you may want to build your own UbiFunction instead.
3. Editing the Plugin's device type
An Ubidots device type will be created and linked to this plugin. This allows you to make batch changes to all of the devices that receive data through this plugin.
For example, let's imagine you edited the decoding function to generate two variables: Temperature and Pressure. By default, these variables will contain default colors and icons, and no units. If you wish every future device to have an automatic and custom configuration for these variables, then you will want to change the device type:
4. Troubleshooting
The best way to test the plugin is by making an HTTP request to the plugin's URL. Just grab the sample JSON payload below, and send it in an HTTP POST request using an HTTP client of your choice (Postman or similar). Make sure you add the header "Content-Type:application/json":
Sample TTS JSON payload:
{
"correlation_ids":[],
"end_device_ids":{
"application_ids":{
"application_id":"ubidots-playground"
},
"dev_addr":"26083CC4",
"dev_eui":"AC1F09FFFE01454E",
"device_id":"wisblock-environment",
"join_eui":"0000000000000000"
},
"received_at":"2021-03-22T17:08:02.041790248Z",
"uplink_message":{
"consumed_airtime":"0.061696s",
"f_cnt":240909,
"f_port":2,
"frm_payload":"AQmKGcgAAUxNAAHd8Q==",
"received_at":"2021-03-22T17:08:01.828644502Z",
"rx_metadata":[
{
"channel_index":4,
"channel_rssi":-62,
"gateway_ids":{
"eui":"B827EBFFFE2175FD",
"gateway_id":"rak7246g-ubidots-hq"
},
"rssi":-62,
"snr":9.8,
"timestamp":4278810051,
"uplink_token":"CiEKHwoTcmFrNzI0NmctdWJpZG90cy1ocRIIuCfr//4hdf0Qw+ul+A8aDAjxneOCBhC48cKKAyC4g9Dnw/dV"
},
{
"channel_index":4,
"channel_rssi":-35,
"gateway_ids":{
"eui":"008000000000A4CA",
"gateway_id":"ubidots-hq"
},
"rssi":-35,
"snr":10,
"time":"2020-01-12T21:40:15.686786Z",
"timestamp":610171251,
"uplink_token":"ChgKFgoKdWJpZG90cy1ocRIIAIAAAAAApMoQ8/L5ogIaDAjxneOCBhC4w5yRAyC40qmI4fRc"
}
],
"session_key_id":"AXc7ndbOC6RWaEc9jlbTOA==",
"settings":{
"coding_rate":"4/5",
"data_rate":{
"lora":{
"bandwidth":125000,
"spreading_factor":7
}
},
"data_rate_index":3,
"frequency":"904700000",
"timestamp":4278810051
}
}
}
Send the above payload in an HTTP POST request to the Plugin's URL:
Note that the first time the plugin is executed, it may take a few seconds to respond. To check the plugin's logs, go to the plugin, click on the "logs" section and you should see a list of the latest executions.
