All Collections
Developer Guides
Integrate your TTN data with Ubidots – Manual UbiFunction Setup
Integrate your TTN data with Ubidots – Manual UbiFunction Setup

Integrate your The Things Network's (TTN) account data with Ubidots using UbiFunctions to transform the payload and launch your IoT Solution

Isabel Lopez avatar
Written by Isabel Lopez
Updated over a week ago

Looking for the Simple Setup Developer Guide to Integrate TTN data with Ubidots? Click here for the Integration Simple Setup Guide.

The Things Network (TTN)
is a LoRaWAN network specifically designed for more efficient device communication with the internet, minimal battery requirements, and a long range and low bandwidth protocol. You can learn more about The Things Network from their official web page.   

Where does the TTN thrive?

  • Smart City Applications (environmental condition monitoring, smart parking, smart lighting, waste management...

  • Industrial Applications (sensors technology monitoring, asset tracking, leak detection...)  

  • Smart Home Applications (home security, home automation...

  • Healthcare Application (wearables technology, health monitoring devices and data-management...

  • Agriculture  (smart farming, water level sensors, irrigation control, livestock management...)

Requirements

Setup

  1. Gateway & Devices Status Verification

  2. TTN Application Management 

  3. TTN Payload Format

  4. TTN HTTP Integration with Ubidots 

  5. Ubidots Data visualization  - Result

1. Gateway & Devices Status Verification 

1. Sign in into your TTN account.
NOTE: This guide assume that you already have configured your LoRaWAN gateway  in TTN and the nodes are already transmitting data.

2. From your TTN account, press the "CONSOLE" tab located in the upper-left corner of the page.

In the CONSOLE, you will find two options. 

  • Applications- required to establish data communication with all devices. 

  • Gateways- the data communication bridge between devices (also thought of as field sensors) and The Things Network. 

As mentioned above, this guide assume that your have already configured your gateway with TTN with the devices registered in their specific applications. 

3. Verify that your Gateway is properly connected to TTN. For this, select "GATEWAYS" from the console tab and check the status of the gateway as "Connected." 

By selecting any active GATEWAY, you can look deeper into its connectivity and data transmission insights. 

4.  If your devices are transmitting data properly, all messages received will be seen in TTN. To check the incoming messages from the devices, go to the "Traffic" tab from gateway console:

2. TTN Application Management  

As you may already known, each Application within your TTN account will be applied using a host of sensors (or devices). In this tutorial we will work with temperature & humidity sensors, plus volume sensors and therefore, I need to create two applications:

  1. Temperature & humidity Application

  2. Volume reader Application  

Having as result:

For our first application, Temperature & Humidity Application, you will note that 2 devices are registered with it respective Device EUI:

  • Feather_temp_hum_1:   00xxxxxxxxxxxx73 

  • Feather_temp_hum_2:  00xxxxxxxxxxxx5E 

IMPORTANT NOTE: The Device EUI will serve as the unique identifier for each device and this same unique identifier will act as the Ubidots Device Label (the unique device identifier in Ubidots and also explained in the step #5).

Now let's start with the Payload Formats & Integrations configurations.

3. TTN Payload Formats

With the devices (sensors) properly registered and transmitting data, it is time to setup the Payload Format to decode the incoming data before it is posted to Ubidots for visualization and utilization.

1. The payload is received from the device as "bytes," found in the "Data." This payload is difficult to interpret and needs to be decoded.

2. To decode the incoming data, go to the "Payload format" tab and select "Custom" as payload format. Then, based on the structure managing the incoming data, assign the right decoder code in the code editor provided in the console.
2a. Save the changes by pressing the green button "save payload functions"

As you will find below, the sensor readings are taken using the DHT library and the values are being multiplied by 100 to send fewer bytes.

Encode (Arduino): 

uint32_t temperature = dht.readTemperature(true)  * 100; // Read temperature
uint32_t humidity = dht.readHumidity() * 100; // Read humidity
 
byte payload[4];
 
payload[0] = highByte(temperature);
payload[1] = lowByte(temperature);
payload[2] = highByte(humidity);
payload[3] = lowByte(humidity);

Then, in the payload functions we have to decode the data sent and structure the JSON payload desired to be posted later in the Ubidots.

Decode (Payload functions):

function Decoder(bytes, port) {
  var temperature = (bytes[0] << 8) | bytes[1];
  var humidity = (bytes[2] << 8) | bytes[3];
 
  return {
    temperature: temperature / 100,
    humidity: humidity / 100
  }
}

In this case, the payload function will return the following JSON with the respective value to each variable:

{
  "humidity": 60.3,
  "temperature": 57.19
}

The management of data as bytes, plus the encode & decode configurations can be a little confusing at first, but this helpful guide will help you work with bytes. It is highly recommended that you review this guide and the video below:

3. To verify the decoding is complete, go to the "Data" tab from the application console and find that the payload is being received in bytes, but also shown as the decode to the right:

4. TTN HTTP Integration with Ubidots

To push data from TTN to Ubidots to develop and deploy IoT applications, we will use TTN feature called “HTTP Integrations”, which simply forwards any incoming data received to Ubidots using an UbiFunction. For more information about forwarding TTN raw data to a 3rd party platform, check out this link.

UbiFunctions Setup

Note: an UbiFunction is a Node.js cloud function executed when a GET, POST, or HTTPS request made with function URL. A simple diagram of this activity can be found below:

Create an UbiFunction to Parse Data

  1. Go to your Ubidots account => Devices => Functions

NOTE:  Ubifunctions is included in Professional plans and above.

2. Click the blue "+" icon in the upper-right corner to create a new function: 

3. Assign a name to the function, e.g. "TTN Intergration". Then, assign the POST as the HTTP method.

4. To finish the function, press the blue button "Make it live". As you will see, the endpoint URL is generated (as is shown below). This HTTPS Endpoint URL now needs to be assigned in the configuration of the TTN HTTP Integration, for now just copy the URL and save it for later.  

5. Copy and paste the code below into the UbiFunction editor. Once pasted, assign your Ubidots Token where indicated. 

var request = require('request-promise');

// Assign your Ubidots TOKEN

var token = "xxxxxxxxxxxxxxxxxxx";

// This function build the HTTP POST request to Ubidots

async function ubidotsPost(deviceLabel, data) {

    var options = {

        method: 'POST',

        url: 'https://industrial.api.ubidots.com/api/v1.6/devices/' + deviceLabel,

        body: data,

        json: true,

        headers: {

            'Content-Type': 'application/json',

            'X-Auth-Token': token

        }

    };

    return await request.post(options);

}

async function main(args) {

    var deviceLabel = args['hardware_serial'];

    var payload = args['payload_fields'];

    // Sends the data incoming to Ubidots

    console.log(deviceLabel);

    console.log(payload);

    await ubidotsPost(deviceLabel, payload);

    return {parser_status: "OK"};

}

Save the changes by pressing "Make it live"

5. Just as reference,  the payload below  is the one returned by the TTN Integration feature:

{

   hardware_serial: '00xxxxxxxxxxxx73',

   payload_fields: {

       temperature: 75.19,

       humidity: 42.1

   },

   dev_id: 'feather_temp_hum_1',

   port: 1,

   payload_raw: 'HV8Qcg==',

   downlink_url: 'https://integrations.thethingsnetwork.org/ttn-us-west/api/v2/down/temp_hum_sensors/ubidots-parser?key=ttn-account-v2.XxxxXxxxXv7yLaMvr_y_XXxxxxX-0LeOA-MlsXxxXxAv',

   metadata:{

       modulation: 'LORA',

       data_rate: 'SF7BW125',

       coding_rate: '4/5',

       frequency: 903.9,

       time: '2018-03-22T19:25:50.257655583Z',

       gateways: [ [Object] ]

   },

   counter: 103,

   app_id: 'temp_hum_sensors'

}

So every time that a value is received in the Application, the HTTP Integration configured will post the payload above. But, as you will see from the payload returned only the parameters payload_raw  and payload_fields are used. Where the raw is the encoded data, and the fields is the JSON data of the payload configured in the “Payload Formats” section.  Also, the hardware_serial which is the Device EUI used to easily and uniquely identify the devices in Ubidots.  

4. TTN HTTP Integration 

To complete the integration between TTN and Ubidots, we will return to the TTN Console and apply the Ubidots Function to the HTTP Integration.

1. From the TTN Console, select Integration > add integration > HTTP Integration to find the following page:

2. Complete the empty fields with the following parameters:

  • Process ID: ubidots-parser

  •  Access Key: default key

  • URL: URL previously generated by UbiFunctions 

  •   Method: POST

  •  Authorization: empty

  •  Custom Header Name: empty

  •  Custom Header Value: empty

Press the "add integration" button. Once the Integration is properly added, conform the Integration overview has a "Running" status. 

5. Ubidots Application Development - Result 

At this point everything is configured and data is being securely passed from the TTN to Ubidots to be enhanced and deployed to end-users.

1. As previously mentioned, the Device EUI of the devices registered in my application "temp_hum_sensors" are:

  • Feather_temp_hum_1:   00xxxxxxxxxxxx73 

  •  Feather_temp_hum_2:  00xxxxxxxxxxxx5E  

Now, with the TTN Integration and the parsed data working as expected, your device's data is being automatically created sent to and updating the (automatically created) devices in the Devices section of your Ubidots account: 

Opening the device you will find the detailed temperature & humidity insights:

IMPORTANT NOTE: Please note that each application has to be configured (payload format & HTTP integration) to be able to communicate with the function created in Ubidots.

2. [OPTIONAL] Don't like the Device EUI as your device's name in your Ubidots display? Don't worry! You can change the name to a more friendly one, but the device label will be stay as the Device EUI to never get confused which device is which. Check out this help center article to better understand Device Labels and Device Names in Ubidots.

3.  Now create Ubidots Dashboards to visualize and understand your data to make better decisions simply and intelligently.

Did this answer your question?