Using the Things Network V3 with an API Application

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:"",
	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:

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

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.

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:"",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.