A downlink message comprehends the last mile in the IoT communication cycle, it enables devices, connected to the application layer through protocols requiring intermediary platforms, to be controlled or setup-modified from afar. Such an example are devices using LoRaWAN communication protocol and The Things Stack V3, TTS, as a network server. TTS provides an API triggered by POST requests to forward messages from the cloud down to devices, that is, downlink messages.
Following this guide, you will be able to send messages from Ubidots platform to a TTS-connected device using the events module and TTS downlink API.
Requirements
LoRaWAN Gateway & Devices already transmitting data to TTS and Ubidots (see Plugins: Connect The Things Stack to Ubidots)
A Control variable within your device in Ubidots to trigger the downlink event.
Table of Contents
1. Setup a downlink event in Ubidots to TTS
The below steps indicate how to create an event in Ubidots to perform a downlink message to the TTS V3 back-end, and hence control devices from Ubidots UI.
Step 1: Open Events module located under the Data dropdown.
Step 2: Create a new event and setup the condition to be triggered based on the control variable’s values.
Step 3: Next, in the Actions section, select "Trigger Webhook" action.
Step 4: Head to your TTS console and select the application hosting the device you want to make a downlink to.
Step 5: Extract the below information from your application console panel:
Region: The region where your TTS resides.
Application ID: found in the Application overview
Application Access Key: The TTS V3 console doesn’t allow seeing existing API Keys. Therefore, unless you already have an existing API Key saved in a secure place, you will have to create a new API Key. The “Write downlink application traffic” right is mandatory to allow downlink traffic.
Device ID: Found on the “End devices” tab.
Step 6: Enter the required information in the webhook options panel of the event action. This information corresponds to the information sent in the POST request to TTS V3 back end:
– HTTP Method And URL
Community edition:
POSThttps://<region>.cloud.thethings.network/api/v3/as/applications/<application-id>/devices/<device-id>/down/push=> you'll need to replace <region>, <application-id> and <device-id> with the information obtained in the previous step.
Pro TIP: If using the TTS plugin, you can add the <device-id> dynamically by adding the Device Label bookmark.
Cloud and Dedicated Cloud:
POSThttps://<tenant-id>.<region>.cloud.thethings.industries/api/v3/as/applications/<application-id>/devices/<device-id>/down/push=> you'll need to replace <tenant-id>, <region>, <application-id> and <device-id> with the information obtained in the previous step.
– Headers: you'll need 2, one for the Content-Type and for the Authorization. It follows the structure “key: value”
Content-Type : application/jsonAuthorization : Bearer <API Key>=> You'll need to replace <API Key> with the TTS v3's API Key.
Step 7: Enter the JSON body. This is the JSON expected by the TTS V3 back end. You can send either a base-64 payload or a human-readable payload.
base-64 payload
{"downlinks":[{"frm_payload":"<base-64-payload>","f_port":<port>,"priority":"NORMAL"}]}
You'll need to replace <base-64-payload> with the payload formatted in base-64, <port> with the listening port of your device.Human-readable payload
{"downlinks":[{"decoded_payload":<key-value payload>, "f_port":<port>,"priority":"NORMAL" }]}
You'll need to replace <key-value payload> with the payload to be sent formatted as key:value pairs, for instance{"power":50 , "activation":"true"}; and <port> with the listening port of your device.
Step 8 (optional): Set the "Back to normal" option if required, just the same as in Step 7 . This will trigger a second downlink message once the event condition is no longer true.
Step 9: Follow to the last step in the event creation and name it.
2. Results
After setting up your downlink event to be triggered once the condition is met, you should see something similar to the below GIF in your TTS Live Data tab.
We setup this event example to be triggered when a control variable is 1, sending a JSON Payload fields :
{"variable": 1}
And then, when control variable is switch off and value is 0, performs a second downlink messages sending a Raw payload base64 encoded:
SG9sYQ==
