The Things Industries brand-new LoRaWAN Network Server, called The Things Enterprise Stack, offers the solution to build and operate private LoRaWAN networks. Manage and monitor your remote devices and gateways with an elaborate toolset, and route telemetry data securely to your Ubidots powered IoT cloud application.
IMPORTANT NOTE: this article assumes LoRaWAN Gateways and Devices have been already provisioned within The Things Industries instance and are sending data regularly.
Abbreviations:
TTI: The Things Industries
Requirements
Ubidots trial account or Licensed account (Professional and above)
The Things Industry Instance
Gateway and devices connected to the TTI instance
1. Integration Workflow
Connecting/upstreaming data from TTI with/to Ubidots is known as an HTTP Cloud-to-Cloud Integration. Those integrations often, if not always, require middle steps to ensure compatibility between the sender and receiving cloud data formats. In this case, TTI’s integration with Ubidots is not the exceptions as it requires a parsing step to convert TTI’s native JSON format into an Ubidots-compatible one. That parsing step is where Ubidots Functions as a Service (FaaS) module, UbiFunctions, comes in to take TTI’s native JSON format and make it an Ubidots API compatible one.
The below image depicts this workflow:
2. Ubidots Setup: UbiFunctions
From the UbiFunctions module follow the below steps to create and launch the UbiFunction which will handle TTI’s native JSON format conversion into an Ubidots’ compatible one:
Step 1: Click the “+” button in the upper-right corner
Step 2: Name your UbiFunction. For example, “TTI Integration”
Step 3: Select POST as the Method
Step 4: Select Python 3.6 as the default Runtime
NOTE: Leave the “Time-base trigger” option disable
Step 5: Enter the below code in the Editor
import requests
import json
import time
BASE_URL = "https://industrial.api.ubidots.com"
TOKEN = "····" # Enter an Ubidots account token here
def main(args):
# Prining args from TTI
print(f'[INFO] Args from TTI:\n {args}')
# Parsing data
payload = parse_tti_data(args)
dev_label = tti_dev_eui(args)
print(f'[INFO] Parsed data:\n {payload}')
print(f'[INFO] TTI Dev_EUI data:\n {dev_label}')
# Posting to Ubidots
req = update_device(dev_label, payload, TOKEN)
print(f'[INFO] Request to Ubidots Status code: {req.status_code}')
print(f'[INFO] Request ti Ubidots JSON:\n {req.json()}')
return {
'status_code': req.status_code,
'response_json': req.json()
}
def parse_tti_data(data):
return data['uplink_message']['decoded_payload']
def tti_dev_eui(data):
return data['end_device_ids']['device_id']
def update_device(device, payload, token):
"""
Updates device with payload
"""
url = "{}/api/v1.6/devices/{}".format(BASE_URL, device)
headers = {"X-Auth-Token": token, "Content-Type": "application/json"}
req = create_request(url, headers, attempts=5, request_type="post", data=payload)
return req
def create_request(url, headers, attempts, request_type, data=None):
"""
Function to make a request to the server
"""
request_func = getattr(requests, request_type)
kwargs = {"url": url, "headers": headers}
if request_type == "post" or request_type == "patch":
kwargs["json"] = data
try:
req = request_func(**kwargs)
status_code = req.status_code
time.sleep(1)
while status_code >= 400 and attempts < 5:
req = request_func(**kwargs)
status_code = req.status_code
attempts += 1
time.sleep(1)
return req
except Exception as e:
print("[ERROR] There was an error with the request, details:")
print(e)
return None
Step 6: Enter an Ubidots account token where asked (line 6)
Step 7: Click on the “Make it live” button.
Step 8: Copy the “HTTPS Endpoint URL” by clicking the “Copy” icon and Save it for later.
3. TTI Device and App Payload Formatters
Payload formatter, also known as Decoder, is the feature built-in within TTI’s v3 Stack allowing the hexadecimal encoded data coming from Devices to be parsed and converted to readable numerical values, as well as structure it as JSON object compatible with upstream platforms such Ubidots. Payload formatters in v3 are similar to those in TTN Community Edition but with the addition of per Device Payload Formatter.
It is IMPORTANT TO NOTE that Device Payload Formatter takes precedence over the Application wide Payload Formatter.
Device Payload Formatter
Oppose to TTN Community Edition where there’s a general Payload Formatter per application, TTI v3 Stacks allows setting up a Payload Formatter for each single Device within an Application, hence, extending the range and types of devices a single Application can support.
Logged in to the TTI instance, head to the Application you’d like to integrate with Ubidots and follow these steps to create a Device Payload Formatter:
Step 1: Click “Devices” option on the left panel
Step 2: Select the Device you’d like to create a Payload Formatter for
Step 3: Open the “Payload Formatters” tab
Step 4: Select from the available decoder options:
– None
– JavaScript
– GRPC Service
– CayenneLPP
– Repository
NOTE: Most of the time JavaScript is the option that allows more flexibility to structure the output JSON. In Ubidots integration, JavaScripts decoder allows parsing the hexadecimal data frame into a Ubidots compatible JSON.
Step 5: Click on “Save changes”
After completing these steps, every time the selected device sends an uplink message, it will trigger this Payload Formatter decoder
Application Payload Formatter
Application wide Payload Formatter works the same as its counterpart in Devices, the difference is this one will only be trigger for those Devices whose own Payload Formatter have been set to None.
Follow the below steps to set a Application wide Payload Formatter:
Step 1: Click “Payload Formatters” and the “Uplink“ option on the left panel.
Step 2: Select from the available decoder options:
– None
– JavaScript
– GRPC Service
– CayenneLPP
– Repository
NOTE: Most of the time JavaScript is the option that allows more flexibility to structure the output JSON. In Ubidots integration, JavaScripts decoder allows parsing the hexadecimal data frame into a Ubidots compatible JSON.
Step 3: Click on “Save changes”
4. TTI HTTP Uplink Integration
Having the UbiFunction and the Device and/or Application wide Payload Formatter setup, is time to complete the integration to start forwarding data to Ubidots. To that, these steps will get you through this final process:
Step 1: Click “Integrations” and the “Webhooks” option on the left panel
Step 2: Add a new one with the “+ Add Webhook” button.
Step 3: Enter the information as follows:
– Webhook ID: alphanumerical characters and dashes only
– Webhook format: JSON
– Base URL: https://parse.ubidots.com
Step 4: Select the Uplink checkbox
Step 5: Enter the UbiFunction path from Section 2.
NOTE: The path should have this structure:
/prv/{UbidotsUsername}/{UbifunctionName}Where the {UbifunctionName} most be all lowercase and spaces replace with dashes (“-”)
Step 6: Click the “Add Webhook” button
