Using the Things Network V3 with an API Application – Atmosphere Documentation Hub

Using The Things Network V3 with an API Application


 

In this guide you will learn how you can get data from The Things Network (TTN) streaming into Atmosphere IoT. We will cover creating an API application, adding a device event and setting it up as an integration point,  going over the basics of processing the LoRa payload data, and creating an application in TTN console and connecting via the integration webhooks into Atmosphere IoT.

Prerequisite

– A LoRaWAN end device that you can connect to TTN (You can simulate uplink data from the TTN console as well) you can sign up here.

– An account on The Things Stack (Community Edition is free with sign up)

– In physical range of TTN gateway if using actual hardware.

Step 1 of 6: Create a New Project

 

Before we can start viewing our data in Atmosphere IoT, we need to create an API Application that will create the required logic to take the incoming data, process, and store it for our device. Each application in Atmosphere IoT represents all the application logic for a type of device managed by the system. One application can be used to deploy many of the same kinds of devices for management into Atmosphere IoT. In this case we are creating the application for our TTN based LoRaWAN device.

Navigate to Atmosphere IoT Studio from the side menu. When you visit IoT Studio for the first time in a session, you are brought to the IoT Studio Applications screen.

1. Click the add button. This displays a New Application window.

2. Select the API Application type and give it a name, then click Create.

Now we have defined a new type of device in Atmosphere IoT, by creating this application, we can now start to define its behavior. Before we continue, however, we will want to make a note of the Application’s UUID which is used to identify the application and the type of device in the system. To find the UUID, you can click on the “Info” button in the application studio and then highlight and copy the Application UUID that is displayed in its info area.

 

 

Step 2 of 6: Creating the logic

 

Now that we have a project, we need to add into it all the required elements to provide the necessary logic to process the LoRa payload and store the results into the device’s cloud storage.

We are going to be using a Device Event as the incoming point at which data will flow into our application’s design. To make the Device Event’s element process events for a LoRa integration, we will have to configure the device event as such in its properties. Once we do that, all data coming from the TTN network will flow through the device event during its “Event Received” trigger and will generate a value formatted as follows.

{
	payload:"<base64 encoded binary payload>",
	timestamp:"<UTC Timestamp>"
}

We can then use this data coming from our Device Event Element and process it in an Expression Element to confirm the base64 encoded data and to process it into useful human readable information to store in the device’s cloud storage using a Cloud Storage Element.

1. Go to the “Cloud” tab of the application.

2. Click the “Device Event” element  in the toolbox to add it to the workspace.

3. Also click to add an “Expression” element 

4. Also click to add a “Cloud Storage” element 

5. Now in the left designer view, drag out and make a connection between the Device Event element and the Expression element that was added to the workspace.

6. Now connect the Expression element to the Cloud Storage element – should appear similar to below:

 

Connected elements in project

 

7. Select the Device Event element in the designer view. In the properties section, select “LoRa” in the “Integration” drop down menu.

 

Device event properties

 

8. Continue reading to learn how to use the expression element to process the payload.

At this point, the application is almost complete. However, additional code is needed in the Expression element to process the raw binary data from TTN into something useful.

 

 

Step 3 of 6: Use the Expression element to process the payload

 

In this example we are going to assume that we are processing a very simple binary payload from a LoRaWAN sensor. However, in practice, the payloads for LoRaWAN devices can be far more complicated. But the Expression element logic can be updated to process the data as needed by your specific use-case. You may need to output an array of data after processing your particular LoRa payload and send it to a “For Each” element to then add one at a time into the “Cloud Storage” element. Please browse other tutorials about how to use those elements for more information, but for now in this tutorial, we are going to assume we have a very simple payload of 3 bytes. Below you can find a table to describe the payload format.

 

Byte [#]            Description
0   Message type ID as an unsigned integer
1   Temperature reading’s whole degrees Celsius value as an unsigned integer
2   Temperature reading’s remaining hundredths of degrees Celsius value as an unsigned integer

So with the following assumptions about the data above, we could write into our expression element the following code. To do so, click on the Expression Element in the designer view and in the Properties area, copy and paste the following code snippet:

(function() {

	// |Byte \[#\] |Description                                                                                |
	// |:-----     |:-----	                                                                                   |
	// |`0`        |Message type ID as an unsigned integer	                                                   |
	// |`1`        |Temperature reading's whole degrees Celsius value as an unsigned integer                   |
	// |`2`        |Temperature reading's remaining hundredths of degrees Celsius value as an unsigned integer |

	// Convert our base64 string into a binary buffer of raw payload data.
	let rawPayloadData = new Buffer(values.payload, 'base64');

	let messageID = parseInt(rawPayloadData[0]);
	let finalTemperature = parseInt(rawPayloadData[1]) + (parseInt(rawPayloadData[2]) / 100.0);
	let timestamp = new Date(values.timestamp);

	// From the binary data generate a human friendly object to store.
	return {
		"messageID":messageID,
		"Temperature (°C)":finalTemperature,
		"_timestamp":timestamp
	}

})()

When an expression element has its “Evaluate” ability targeted by an event, then the code written in the property of the expression element is executed. The code is executed in a sandbox with a global variable of values available for use inside the expression. The values variable is an object which stores the element’s currently saved values. These values can be added, assigned and removed with other abilities, but for this tutorial we just need to know that our values in the expression code is equal to the value that came from our original Device Event of {payload:"<base64>",timestamp:"<UTC Timestamp>"} in this case. An example of what the output from the expression element could be is below:

{
	"messageID":6,
	"Temperature (°C)":22.57,
	"_timestamp":Date("2021-07-28T17:22:59.305Z")
}

The application is now structured such that any time data is received, the expression element will process the data into the resulting document above. The processed data will then be stored in the device’s cloud storage. Dashboard widgets can now be used to display the data stored in the cloud storage once it is received.

 

Step 4 of 6: Create an Application on The Things Stack

 

Now that we have everything on the Atmosphere IoT side ready to receive and process our data, we can now configure TTN. TTN divides your LoRa devices into Applications. Each Application is responsible for capturing and formatting data from a type of a LoRaWAN device. So for each Atmosphere IoT application you create for a type of device you would also create an application in TTN to correspond with it.

To get the data into Atmosphere IoT from TTN we will be using a WebHook integration in TTN to forward our data through the Atmosphere IoT device event integration API. This API allows Atmosphere IoT to forward and process the incoming data from a third party and forwards the payloads to the correct devices as Device Events. The API can also automatically register new devices that haven’t been added into the system yet, which is what we will be doing for this example.

1. Log into the Thing Network Stack console with your credentials

2. Go to the “Applications” section

3. You will now be asked to set the “Application ID” and “Application Name”. You can name these what ever you would like, however, it’s recommended to make it match the name of the type of devices you are adding.

4. Click “Create Application”

5. Now that you are in the Application overview area you can use the “Add end device” to add a device to the Application.

6. Follow the instruction from the LoRa device’s manufacturer to register it.

 
 

Now that we have our devices registered and our Application created, we can proceed to connecting our TTN application to Atmosphere IoT using the custom webhook integration.


Step 5 of 6: Add a Webhook Integration to the TTN Application

If we watch the live data in the TTN console, we should begin to see our data streaming in at this point. However, we haven’t connected our TTN account to our Atmosphere IoT account so that we can start to get our data there. To do this, we will use an API security token from Atmosphere IoT, as well as its integration API to start passing data into the system.

1. Log into your Atmosphere IoT account and navigate to your User Account security tab. This can be found by clicking on your user icon in the bottom left.

2. Under the Security tab you can under “Authentication Tokens” click “Generate Token.” If you already have a token generated, you can simply use the one there already.

3. In the TTN console under the Application Overview (for the Application you created in the previous step under integration in the left menu), go to “Webhooks”

4. Click on “Add Webhook”

5. Select from the list of options “Custom Webhook”

6. For the field “Base URL” enter the following: https://platform.atmosphereiot.com/v2/events

7. Under “Additional Headers”, you need to add the following pairs of information which will be the same for all TTN applications you may add in the future.

deviceTag with value of loraDevEUI

deviceTagValueRef with value of $.end_device_ids.dev_eui

eventPayloadMapRefs with value of {"payload":"$.uplink_message.frm_payload", "timestamp":"$.uplink_message.received_at"}

eventsRef with value of $

integration with value of lora

8. Under “Additional Headers”, we need to add our user specific authorization token with a field of authorization and then copy your authorization token into the value for it.

9. And as well under “Additional Headers” we need to add the field projectUuid and populate with the Application UUID that we created in Step 1.

10. Under Enabled Messages, check “Enabled” for the “Uplink message” and enter into the field /integrations

11. Click “Save Changed”

The order of the headers does NOT matter, so for example,

Example of applcation headers

With that we have connected a stream of data coming from the TTN that will flow through the Device Event we adding in our project and process the data. Additionally, if the integration API cannot find a matching device for the incoming LoRa payload, it will automatically register one on Atmosphere IoT with the application you supplied for “applicationUuid”. If you don’t supply the application UUID to be used to register the new device, no devices will be automatically registered and they will have to be registered manually into Atmosphere IoT.

If you want to learn more about the integrations API, you can find more in our HTTP API documentation.


Step 6 of 6: Wait for data and create a dashboard

In the final step we are now just waiting for data to arrive from TTN into Atmosphere IoT. You can check the “Storage” tab for the device in question to see if any data has been added to its data store. Once data has been added, you can start adding widgets into the device’s dashboard to see and report on the data that is being collected.