Getting Started with LoRa and Atmosphere

This guide teaches you how to get started with sending device data using LoRa from an Atmosphere project via The Things Network. This includes connecting The Things Network console to Atmosphere, creating an Atmosphere project, setting up a LoRa 2 click element to have data sent from the device to The Things Network, and then viewing the device data forwarded from The Things Network in Atmosphere.

In the guide you’ll first run a project that reads the LoRa 2 Click board’s device EUI, and then you’ll build a new application that reads temperature and sends the data over LoRa to The Things Network, where it’s then forwarded to Atmosphere.

Prerequisite: You should already have both an Atmosphere account and The Things Network account.

It's highly recommended to have a moderate understanding of The Things Network console before enabling Atmosphere and other third party services to communicate to your Things Network account.

Hardware Requirements

For the purposes of this guide, we used the PIC-IoT WG for ease of use since it comes with an onboard temperature sensor, but any Atmosphere-supported development board that is compatible with the LoRa 2 Click board will work. Currently, the LoRa 2 Click board is exclusively supported in Atmosphere with connecting to The Things Network.

To work alongside The Things Network, the LoRa 2 Click board needs to connect to a gateway registered on The Things Network in order to send data to the network. This can either be a gateway you register yourself or a public gateway within range that it can connect to. In the event a public gateway is used, the connection will automatically go through the nearest gateway if more than one is within range. This guide presumes you have access to a gateway in either capacity to send data from your LoRa 2 Click board.

If there aren't public gateways available to connect to and you need to register your own to get started, head over to The Things Network docs for information on running a gateway on The Things Network.

Software Requirements

In order to use the LoRa 2 Click board with The Things Network, the board needs to be registered as a device on The Things Network console. During registration, the device EUI is needed. This is the universal ID that identifies the device within the LoRa address space, and is unique to the board. However, the LoRa 2 Click board doesn’t physically display the device EUI itself and it must be digitally read from the board. To easily get your board’s EUI, we’ve included a simple project designed to read and print it to a debug console. We’ll cover how the demo works below.

The Atmosphere IoT Agent is a local application that runs in the system tray and acts as an intermediary between the computer’s connectivity protocol drivers and the browser running Atmosphere, and is used here to assist in connecting the device to Atmosphere. While the agent is running, a device with Atmosphere firmware installed on it can be registered to Atmosphere directly without the assistance from an additional connection like BLE or Wi-Fi if it’s connected to your computer.

The project in this guide doesn’t use Studio’s Application tab to build an app interface and since the PIC-IoT WG will be registered to Atmosphere directly via a UART connection with your computer, the Atmosphere IoT app is not required here. However if you’ve elected to use a development board other than the PIC-IoT WG, note you may require the app and have different programming instructions than what is detailed below.

Step 1 of 11: Open the Device EUI Reader Project

The first thing needed for using the LoRa 2 Click board is obtaining its device EUI. As detailed above, we’ll get this ID using the LoRa 2 Click Device EUI Reader Project. The device EUI is needed for registering the device on The Things Network, so this has to be done prior to building the actual project we’ll use for sending data to The Things Network.

  1. Click the LoRa 2 Click Device EUI Reader Project listed above in the Software Requirements section. This brings you into Atmosphere Studio with the PIC-IoT WG project open. LoRa 2 Click Device EUI Project The premise of the LoRa 2 Click Device EUI Reader Project is to read the device EUI from the LoRa 2 Click board, and print it onto a debug console. This is enabled through the MikroElektronika LoRa 2 Click Element MikroElektronika LoRa 2 Click element, which has been imported from the Studio Element Library. The MikroElektronika LoRa 2 Click element is connected to a Debug Print Element debug print element, which prints the read device EUI to a debug console.

Step 2 of 11: Program and Run the Device EUI Reader

With the complete LoRa 2 Click Device EUI Reader Project in hand, your PIC-IoT WG can be programmed with it. Prior to programming, ensure the LoRa 2 Click board is connected to the PIC-IoT WG, and that the device is connected to the computer via USB. It should mount as a mass storage device.

  1. Click the Compile button in the project options menu on the top-right of the screen. You’ll see a loading message on the screen indicating compiling has started, and will be notified when the project is compiled. With the project compiled, your PIC-IoT WG can be programmed.
  2. From the Embedded tab, click the Program Firmware button from the tab’s toolbar. This downloads a .hex file containing the project’s compiled firmware.
  3. Locate the downloaded file on your computer, and move it into the mounted PIC-IoT WG device. This initiates programming of the PIC-IoT WG, which is represented by a series of blinking LEDs and then it will reboot. The blue LED will then turn on, followed by the yellow LED. This indicates the device is programmed, and its application starts running.
  4. Open your debug console and configure it to read the UART data from the device. The device EUI will be displayed after initialization messages similar to the format below, under the LoRa Device EUI tag:
...

LORA UART TX: 0

Previously Joined: 0
LORA UART TX: RN2903 0.9.8 Feb 14 2017 20:17:03

LORA UART TX: ok

Setting App Key: 12345d67e8f9012bbfe3d45ff6b7dc81
LORA UART TX: ok

...
...

LoRa Device EUI: 0004A30B0020CD1A
...
...

Now that you have the device EUI, copy it for later use. This will be added to The Things Network console in the steps below.

Step 3 of 11: Connecting The Things Network Console to Atmosphere

Before a LoRa device can be used in Atmosphere, The Things Network console must be configured to forward data to Atmosphere. This involves generating an API token in Atmosphere, creating a new application within The Things Network console, and adding an HTTP integration within The Things Network.

  1. To generate an API token, open the account menu from the navigation bar and click Security.
  2. In the Security section’s Authentication Tokens area, click the Generate Token button to make a new API token. This will be the token you use to provide The Things Network the ability to send data to your Atmosphere account. LoRa Device API Token

Once you’ve created an API token, it then has to be applied to your The Things Network account through an HTTP integration.

  1. Login to The Things Network console, and navigate to the Applications page. On the page, click Add Application to create a new application.
  2. In the new application, enter the following information:
    • Application ID: The unique ID for your application; effectively the application’s name so choose an ID you like, such as atmolora.
    • Description (optional): Description of your application.
    • Application EUI: Auto-generated ID for the application on The Things network.
    • Handler Registration: Select the handler (server) that’s relevant to you (e.g ttn-handler-us-west if based in the United States). The Things Network Application When finished click Add Application to create the new application.
  3. Select your application, and from its Overview page click on the Integrations tab. On the page, click Add Integration to add a new integration.
  4. From the Add Integration list select HTTP Integration. This is where we’ll enter the API token to connect The Things Network to Atmosphere.
  5. In the new integration, enter the following information:
    • Process ID: The unique ID for the integration; effectively the integration’s name so choose an ID you like, such as atmointegration.
    • Access Key: Select Default Key from the list of available options.
    • URL: The URL the data is forwarded to. Enter the following URL: https://platform.atmosphereiot.com/user/things/protocols/thethingsnetwork.
      • If this project is being built on a platform variant that uses a different base URL (such as DK IoT Studio), replace the base URL with the variant URL.
    • Method: The HTTP method to use. Enter POST in the field.
    • Authorization: The API token you generated from Atmosphere earlier in part 1 of step 3. The Things Network Integration When finished click Add Integration to finish the integration.

With the HTTP integration created, data sent to The Things Network from devices within the application will be sent to the integration end point (Atmosphere).

Step 4 of 11: Register the Device on The Things Network

Now that we have an application and HTTP integration for Atmosphere setup on The Things Network, the LoRa device has to be registered within the application. So we’ll register the LoRa 2 Click board as a new device within The Things Network.

  1. Select your application, and from its Overview page click on the Devices tab. On the page, click Register Device to register a new device.
  2. In the new device, enter the following information:
    • Device ID: The unique ID for your device; effectively the device’s name so choose an ID you like, such as atmodevice.
    • Device EUI: The ID you read from the LoRa 2 Click board in step 2 using the LoRa 2 Click Device EUI Reader Project.
    • App Key: Auto-generated ID to secure communication between the LoRa 2 Click board and The Things network. Copy this for later use; it will be used in the project created in the steps below. The Things Network Register Device When finished click Register to add the device to your application.

With the LoRa 2 Click board registered, that finalizes the work done on The Things Network console. To this point, we’ve created a new application, setup an HTTP integration that enables data sent to the application to be forwarded to Atmosphere, and registered a device in the application. Now that the LoRa 2 Click board is registered on The Things Network, the next aspect of the guide is building the project to read and send data.

Step 5 of 11: Create a New Project

Return back to Atmosphere and navigate to Atmosphere Studio from the side menu. When you visit Studio for the first time in a session, you are brought to the Studio Projects screen.

  1. Click the New Project button. This displays a New Project window.
  2. Select the PIC-IoT WG project type (or whichever project type you’re using) and give the project a name, then click Create. This opens a new project in Studio.

Step 6 of 11: Import the LoRa 2 Click Element

Prior to building the project, the proper elements have to be added into Studio’s Element Toolbox. This project involves integrating the LoRA 2 click element, which isn’t native to PIC-IoT WG projects. So we’ll add it through the Studio Embedded tab’s Element Library.

  1. From the Embedded tab, click the Add Element Add Element button located in the bottom of the Element Toolbox. This opens the Element Library, which includes numerous elements for sensors and other devices that can be incorporated into a project. LoRa Guide Element Library
  2. In the Element Library, locate the LoRa 2 click element, and turn on the enable switch in its row. When done click Save, and the element is added into the Embedded tab’s toolbox.

Step 7 of 11: Create the Project’s Embedded Firmware

The first aspect of building this sample project is adding elements to the Embedded tab to create the project’s embedded firmware. This involves setting an interval to read the onboard temperature sensor of the PIC-IoT WG, and send that data to the LoRa network.

  1. Add the following elements to the canvas by clicking them in the Element Toolbox:
    • Interval Element Interval element: The interval element sets the project to run at the time set in the element’s properties, which by default is set to once per second (1000 ms).
    • Microchip MCP9808 Element MCP9808 element: The MCP9808 element reads temperature data. This is a temperature sensor that is onboard the PIC-IoT WG, and its element is imported in the Element Toolbox for PIC-IoT WG projects by default.
  2. Click the interval element to view its properties. In its properties area, change the Time field to 600000 milliseconds (10 minutes). LoRa is designed for small, infrequent packets of data, and The Things Network has limitations on airtime and the number of uplink messages that can be sent by a device per day. In general, sending data any more frequently than every 10-15 minutes is not recommended.
  3. Connect the interval element to the MCP9808 element. This creates an event between them, which can be seen in either the interval element’s properties, or by clicking the connector’s Configuration Button button. The event added is within the Interval trigger, with the MCP9808 ability Read Ambient Temperature (C). This means that when the interval element is triggered (which is every 10 minutes), it will read the ambient temperature in the area.
  4. Add a MikroElektronika LoRa 2 Click Element LoRa 2 click element to the canvas, which enables a LoRa 2 Click board to send data to The Things Network in the application specified in its properties. The LoRa 2 click element is also a coupled element that bridges the project between the Embedded tab and Cloud tab with a corresponding The Things Network element. In the LoRa 2 click element’s properties, change the following fields:
    • App Key (Custom): Enter the app key from your device registered in The Things Network.
    • Application EUI: Enter the application EUI from your application in The Things Network.
    • Upstream Data Type: Select Floating Point (32-bit) from the list of options. This allows the element to send data as a floating point value, which is the temperature value that will eventually be sent through it.
  5. Connect the MCP9808 element to the LoRa 2 click element, which ties the value of the temperature sensor to the LoRa network and the Cloud tab. This creates an event between the two elements in the Ambient Temperature Read trigger, with the ability Send Data. This sends the data to The Things Network from the LoRa 2 Click board.

That’s all for work in the Embedded tab. The Embedded tab’s canvas should resemble the following image:

Embedded Tab LoRa 2 Click Element
LoRa Guide Embedded Tab LoRa 2 Click Element Properties

Step 8 of 11: Enable the Project’s Data Storage

The last aspect of building this sample project is enabling Atmosphere to store data sent to it. This is done on the Cloud tab.

  1. Click the Cloud tab to move to the cloud area of the project. Notice how the Element Toolbox has changed, and as mentioned previously that the coupled The Things Network element is displayed on the canvas.
  2. Add a Cloud Storage Element cloud storage element to the canvas, and connect the existing The Things Network element to it. By default, this creates an event using the Add Data ability within The Things Network’s Data Received trigger, which allows Atmosphere to add (and store) the data sent to it from The Things Network.
  3. Within the Add Data event, modify the event’s Value field to {"Temperature": value}, which will label the incoming value as “Temperature” when displayed in Atmosphere.

That’s all for creating the project! With the added cloud storage, the project will send the ambient temperature data from the Embedded tab to The Things Network via the LoRa 2 Click board, and based on the configuration in The Things Network console, will forward that data to Atmosphere where it’s stored.

The final canvas for each tab should resemble the following images:

Embedded Cloud
LoRa Guide Embedded Tab LoRa Guide Cloud Tab

Step 9 of 11: Program and Run the Application

With the temperature application complete, your PIC-IoT WG can be programmed again to install the new project’s firmware on it. As was the case earlier, prior to programming ensure the LoRa 2 Click board is connected to the PIC-IoT WG, and that the device is connected to the computer via USB.

  1. Click the Compile button in the project options menu on the top-right of the screen. You’ll see a loading message on the screen indicating compiling has started, and will be notified when the project is compiled. With the project compiled, your PIC-IoT WG can be programmed.
  2. From the Embedded tab, click the Program Firmware button from the tab’s toolbar. This downloads a .hex file containing the project’s compiled firmware.
  3. Locate the downloaded file on your computer, and move it into the mounted PIC-IoT WG device. This initiates programming of the PIC-IoT WG, which is represented by a series of blinking LEDs and then it will reboot. The blue LED will then turn on, followed by the yellow LED. This indicates the device is programmed, and its application starts running.

Once the application is running, it begins sending temperature data to The Things Network in 10 minute intervals. However data won’t appear within Atmosphere since a device has yet to be registered in the platform.

Step 10 of 11: Register the Device on Atmosphere

With the application installed on the PIC-IoT WG, the device can now be recognized and connected to Atmosphere.

Prior to registering the device, ensure the Atmosphere IoT Agent is running in your system tray. This is needed to check your computer’s communication ports for a device it recognizes, which will find the PIC-IoT WG.

Given the PIC-IoT WG is likely already connected to your computer from programming, the Atmosphere IoT Agent may not see the device if it was opened afterward. If you didn't have the agent running prior to connecting the PIC-IoT WG to your computer, refresh your browser running Atmosphere before attempting to register the device.

To register the PIC-IoT WG:

  1. Navigate to the Devices area, and click the Register Device Add Device button in the top-right of the screen to display the Add Device window. When the window opens it automatically starts scanning for available devices within range.
  2. The list of available devices appears. Select the PIC-IoT WG you just programmed and click Register. This brings you to the Wi-Fi settings screen.
    • If the device doesn’t show up, try restarting the agent in your system tray. If you do so, refresh your browser and try adding a device again.
  3. Configure your Wi-Fi network settings to connect the device. When Wi-Fi settings are entered, the PIC-IoT WG will connect to Atmosphere over Wi-Fi and remain connected as long as the Wi-Fi connection is maintained.

The device is now registered to Atmosphere and is displayed on the page.

Step 11 of 11: View Device Data

Now that the device is registered to Atmosphere and has data forwarded from The Things Network, let’s view it through one of the many dashboard widgets available. In this guide we’ll use a data graph widget to chart the temperature data.

We’ll do this directly on the device’s console page, so click on the newly-added PIC-IoT WG to enter its console.

Due to data being sent from the device in 10 minute intervals, it may take some time for Atmosphere to receive the first data and appear as an available option to select while configuring a widget. A device's cloud storage and data options become available once they report to Atmosphere for the first time, which may take a few minutes if the device is in between its 10 minute intervals.

  1. To add a widget to the device’s dashboard, click the Configuration button on the right side of the screen. This displays the menu of available widgets. Select the Data Graph data graph widget to add a data graph to the dashboard.
  2. Once on the dashboard, click the widget’s Menu menu icon to display its menu, then click Settings.
  3. Give the data graph a name (such as “LoRa Temperature Data”), then in its Data Source field click Select and choose the following configuration options for the widget:
    • Cloud Storage: Select the cloud storage (TempData, or whatever you named your cloud storage) that is storing the temperature data.
    • X-axis Value: Select the timestamp to go along the graph’s x-axis.
    • Y-axis Value: Select the temperature’s dataset (Temperature, or whatever you named your stored value) to go up the graph’s y-axis.
  4. When finished click Save. This populates the data graph plotting the temperature value as time progresses, updated every 10 minutes as set by the project.

LoRa Guide Dashboard

If you’d like to adjust the graph’s timeline, bounds, or colors, you can edit those properties from the data graph’s menu as well.

Congratulations, you just finished a complete project sending data from a LoRa 2 Click board between The Things Network and Atmosphere!