Ubidots and Seeed Studio have partnered to create a pre-built integration for SenseCAP LoRaWAN Sensors allowing users to easily forward data from The Things Stack 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!
Requirements
An active Ubidots account
An active The Things Stack account
1. Add a SenseCAP sensor node to TTS server
Before connecting the SenseCAP sensor with the network server, please make sure to follow the installation process based on the following documentation:
Read the QR of the sensor to get the node's DevEUI and DeviceCode:
SenseCAP sensor device’s AppEUI and AppKey have been flash into the device by Seed Studio. To retrieve them, you just need to make an HTTP API request, to the below URL.
https://sensecap.seeed.cc/makerapi/device/view_device_info?nodeEui=PUT-SENSOREUI-HERE&deviceCode=PUT-SENSOR-KEY-HERE
Make sure to enter the nodeEui and deviceCode of your own sensor, you will get a response, similar to the one below, containing the AppKey which will be necessary to add the sensor to TTS server.
{
"code": "0",
"data": {
"nodeEui": "2CF7F1212100001B",
"deviceCode": "7D497F49D0D05185",
"lorawanInformation": {
"dev_eui": "2CF7F1212100001B",
"app_eui": "8000000000000008",
"app_key": "3BF3D4C5744A057E0A1A61F4800EB09B"
}
}
}
Device provision in TTS
Step 1: In your TTI account, go to the application you'd like this Node connected to
Step 2: Navigate to the "End devices" section in the left panel
Step 3: Click on the "Add end device" button
Step 4: Fill out the form as follows
Step 6: Basic settings:
End device ID: enter an alphanumeric ID. No spaces allowed.
AppEUI: 00 00 00 00 00 00 00 00
DevEUI: Sensor Device EUI obtain in step 1
AppKey: Sensor AppKey obtain in step 1
End device ID: entered at will
Step 7: Network layer settings:
Step 8: Click the create device button:
2. Creating a SenseCAP Plugin
The SenseCAP Plugin is a serverless function that exposes a private HTTP Endpoint URL optimized to decode The Things Stack uplink JSON payload. 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:
Step 1: 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:
Step 2: The Plugin instructions will appear. Click on the "Next" icon, then review the input parameters:
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, should you need to increase its rate limit in the future.
Step 3: Finish the process and a new plugin will appear in the Plugins list:
Step 4:. Click on the newly-created SenseCAP Plugin, click on the "Decoder" tab, and copy the "HTTPs Endpoint URL". The structure of the URL is:
https://dataplugin.ubidots.com/api/web-hook/<PLUGIN-ID>
Step 5: Finally, go to your The Things Stack account, click on the desired Application then on "Integrations" => "Webhooks", then click on "Add webhook" => "Custom webhook". Pick a name for your webhook, and fill in these fields:
Base URL:
https://dataplugin.ubidots.com
Additional headers: Add an "X-Auth-Token" header with a valid Ubidots token
Uplink message: Mark this checkbox and enter the remaining portion of your Plugin's HTTPs endpoint URL. For example:
/api/web-hook/ki_XL7PPywA3mc5092DCfDC34UQ=
Finally, the WebHook should look something like this:
3. Editing the Plugin's device type
After creating a SenseCAP 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:
Create RSSI and SNR variables for each gateway receiving a signal from your device.
Create a Frame counter, and a Port variable.
If found, the decoded.payload JSON will be forwarded as-is to Ubidots.
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.
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.
The device type will be created based on the type of sensor you have created.
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 (Insomnia or similar). Make sure you add the header "Content-Type:application/JSON":
Sample TTS JSON payload:
{
"@type": "type.googleapis.com/ttn.lorawan.v3.ApplicationUp",
"end_device_ids": {
"device_id": "z4t-wsnnode01",
"application_ids": {
"application_id": "ttn-v3-playground"
},
"dev_eui": "2CF7F1212100001B",
"join_eui": "8000000000000008",
"dev_addr": "260CDBE0"
},
"correlation_ids": [
"as:up:01F6JFFV0TV120FSXQV2MFY0F2",
"gs:conn:01F679083AJCRPD5BXSQ2QNTZW",
"gs:up:host:01F679087TR2RJ39Y7M5NT2PCV",
"gs:uplink:01F6JFFTT06AA4G8XMNES2JEB8",
"ns:uplink:01F6JFFTT1RH44SDJ6W5AVQSSZ",
"rpc:/ttn.lorawan.v3.GsNs /HandleUplink:01F6JFFTT11HNAW417MEQ8R7TY",
"rpc:/ttn.lorawan.v3.NsAs/HandleUplink:01F6JFFV0TJJ0ET1529CCC0DQP"
],
"received_at": "2021-05-25T19:19:41.851389803Z",
"uplink_message": {
"session_key_id": "AXlYmE6XNV/UxGT5MHQDZA==",
"f_port": 2,
"f_cnt": 374,
"frm_payload": "AQMQKoQYAMlA",
"rx_metadata": [
{
"gateway_ids": {
"gateway_id": "ubidots-hq-rak-7246",
"eui": "B827EBFFFE2175FD"
},
"timestamp": 3827086667,
"rssi": -76,
"channel_rssi": -76,
"snr": 9,
"uplink_token":"CiEKHwoTdWJpZG90cy1ocS1yYWstNzI0NhIIuCfr//4hdf0Qy+ryoA4aDAjNm7WFBhDK 1sutAiD42ZCBsW8=",
"channel_index": 1
},
{
"gateway_ids": {
"gateway_id": "packetbroker"
},
"packet_broker": {
"message_id": "01F6JFFTXAYP6E8EJY7M176TDY",
"forwarder_net_id": "000013",
"forwarder_tenant_id": "ttn",
"forwarder_cluster_id": "ttn-v2-us-west",
"forwarder_gateway_eui": "D4ADBDFFFE9E24B0",
"forwarder_gateway_id": "eui-d4adbdfffe9e24b0",
"home_network_net_id": "000013",
"home_network_tenant_id": "ttn",
"home_network_cluster_id": "ttn-nam1",
"hops": [
{
"received_at": "2021-05-25T19:19:41.738013984Z",
"sender_address": "51.143.19.11",
"receiver_name": "router-dataplane-64c4b86866-x65r6",
"receiver_agent": "pbdataplane/1.6.0-beta.3 go/1.16.4 linux/amd64"
},
{
"received_at": "2021-05-25T19:19:41.742594635Z",
"sender_name": "router-dataplane-64c4b86866-x65r6",
"sender_address": "forwarder_uplink",
"receiver_name": "router-67c85c5489-7bnpw",
"receiver_agent": "pbrouter/1.6.0-beta.3 go/1.16.4 linux/amd64"
},
{
"received_at": "2021-05-25T19:19:41.744069512Z",
"sender_name": "router-67c85c5489-7bnpw",
"sender_address": "deliver.000013_ttn_ttn-nam1.uplink",
"receiver_name": "router-dataplane-64c4b86866-x65r6",
"receiver_agent": "pbdataplane/1.6.0-beta.3 go/1.16.4linux/amd64"
}
]
},
"rssi": -98,
"signal_rssi": -99,
"channel_rssi": -98,
"snr": 3,
"frequency_offset": "-30322",
"uplink_token":"eyJnIjoiWlhsS2FHSkhZMmxQYVVwQ1RWUkpORkl3VGs1VE1XTnBURU5LYkdKdFRXbFBh VXBDVFZSSk5GSXdUazVKYVhkcFlWaFphVTlwU2toa2VrNVVaRmRLUldSWFJuaGFNVGxvV G10R1NrbHBkMmxrUjBadVNXcHZhVlJVVW10UFYyUXlWVlYzTUZGcVZsSlNWRUp6Vlc1U1IyRkhSbFZrZVVvNUxuQnFVbU5wVUhoU1gyNUJRMmR6UmtaU1lWaHViR2N1VEZOU2FWcGxTV0ZzZGtWNVFqVm5OeTV5ZEhSaFNXUktVV0Y2YTJ4M01VVTVRbkZFYm04NFh6QTJlWGxEY2tSaVNVUk1hWGxvTVdSd1NqSTNYM2xzV1VoUlZHaGFkazFtWVVobmFqZHBSM1k1YnpsWlZtTkpNSFZ6Ukc0d1JrUkdlakJ5U2tKak0yZFZNR3RzWjJkcWFXaGtVV2hxU2pGMlVGTm1VR1JaUmxWdWNVdElkVlJGY0RCRGVEVnJlRUZmV214V2VHeFNRa2hOYVVaWlkyOW9OazA1VHpkdmVITTFkMEpJZUdKcGVFNVBaRlpyV1RreU5qVTRXbXR1TG5WcFQwcEpRakZET1ZwdFptaDNXblpMVkZVdFoyYz0iLCJhIjp7ImZuaWQiOiIwMDAwMTMiLCJmdGlkIjoidHRuIiwiZmNpZCI6InR0bi12Mi11cy13ZXN0In19"
}
],
"settings": {
"data_rate": {
"lora": {
"bandwidth": 125000,
"spreading_factor": 7
}
},
"data_rate_index": 3,
"coding_rate": "4/5",
"frequency": "904100000",
"timestamp": 3827086667
},
"received_at": "2021-05-25T19:19:41.633890100Z",
"confirmed": true,
"consumed_airtime": "0.056576s",
"version_ids": {
"brand_id": "sensecap",
"model_id": "sensecap-light",
"hardware_version": "2.0",
"firmware_version": "3.4",
"band_id": "US_902_928"
}
}
}
Send the above payload in an HTTP POST request to the Plugin's URL:
Please note the first time the Plugin is executed, it may take a few seconds to respond. To check the Plugin logs, go to the Plugin, click on the "Logs" section and you should see a list of the latest executions.
5. Feedback and suggestions
Feel free to post questions or suggestions in our community portal, or drop us a line at support@ubidots.com.
Learn more about other plugins: