Deploy a Basics Station TTS LoRa Gateway with balena

This project runs on a Raspberry Pi (3 or 4) or balenaFin with a RAK2245 (SX1301) or RAK2287 (SX1302) LoRa concentrators in just one click. The Basics Station protocol equips LoRa gateways with a reliable and secure communication between the gateway and the cloud using websockets.

Nowadays, most of the LoRaWAN operators are adopting the LoRa Basics Station Packet Forward protocol as the new standard protocol on their gateways and cloud services. Furthermore, at the end of the blogpost you will find how to deploy a Basics Station LoRa gateway at The Things Industries, the professional side of TTS, with some minor changes.

Introduction

LoRa is a long-range wide-area network technology, like cellular networks, but designed for lower energy consumption. It enables devices to send small amounts of data over long distances, for years, running on a small battery. The LoRa signal is received by gateways to offer coverage to specific areas, and the range of the LoRa gateways is 8-10km (5-6 miles) in rural areas and 1km in towns where the density of buildings is greater.

The LoRa gateway software includes a Packet Forwarder software that runs on the gateway and interacts with the LoRa chip, which receives and transmits the radio frequency packets, and the LoRaWAN network servers (LNS), which transmits the messages received from the LoRa chips to applications and from the cloud to the devices (uplink and downlink).

Basics Station is the new Semtech implementation of the LoRa Packet Forwarder protocol, using Websockets (TCP) and exchanges-encrypted JSON messages between the gateway and the cloud service. You can find more information here. The older LoRa packet forwarders are the Semtech UDP Packet Forwarder and, for the The Things Network, the non-standard TTN Packet Forwarder using TCP and protocol buffers, and others. The Things Industries is currently using Basics Station packet forwarder protocol as the official protocol.

Building a The Things Stack LoRa gateway with balena offers several advantages, including the simplicity of installing it on raw IoT devices with just a few clicks, and the ability to manage a fleet of LoRa gateways from a single dashboard. Manually upgrading the software running on the gateway can be challenging, but balena provides built-in capabilities to provision, deploy and manage everything in one place.

How to do it

Once you have created your balenaCloud account, click the Deploy with balena button below to automatically deploy the application. If you use this one-click approach, you can skip the manual step of adding device environment values later because they’ll be pre-configured for you:

https://dashboard.balena-cloud.com/deploy?repoUrl=https://github.com/balenalabs/basicstation

If you’re already familiar with balenaCloud, or want more control of how you create and deploy an app to balenaCloud, you can also code with the CLI. Get the project code from this repo.

Tutorial

Create the Application and add a device

Clicking the deploy button will create an application with all the necessary code to deploy your Basics Station LoRa gateway.

Select your board as a device type and click the button ‘Create and deploy’.

At this point, balenaCloud will automatically pull all the code from the Basics Station GitHub repository to your application, and deploy the containerized service.

Once your application has been created, you can add a device to that new application by clicking the Add device button. When you add a device, you specify your device type. It is important that the type you choose matches the device you configured for your application. If you are going to connect your gateway to a wireless network, be sure to set your WiFi SSID and password here, too.

This process creates a customized balenaOS image configured for your application and device type and includes your network settings if you specified them. When prompted, download the file to your workstation.

Flashing the LoRa gateway and deploying code

Once the balenaOS image has been downloaded, it’s time to flash your SD card (in case you use a Raspberry Pi).

You can use balenaEtcher for this. If the downloaded image file has a.zip extension, there’s no need to uncompress it before using balenaEtcher.

Once the flashing process has completed, insert your SD card into the Raspberry Pi and connect the power supply.

When the device boots for the first time, it connects to your network automatically and then to the balenaCloud dashboard. After a few moments, you’ll see the newly provisioned device listed as online.

When the device appears online in the dashboard, it will automatically start to download the LoRa Basics Station application.

Define the MODEL and more Device Variables

There are some Device Variables that will need to be changed depending on the LoRa concentrator that you are using. If you are using a RAK2287 LoRa concentrator get into the Device Variables page and change the MODEL variable to SX1302. If you are using RAK2245 you are using a SX1301 which is activated by default. SX1303 will be compatible very soon.

These parameters have been created automatically at the Application as Application Environment Variables defined during the Deploy with balena process. Go to the balenaCloud > Device Variables section and add the two new variables.

By default the device is configured to send data to The Things Stack (V3) to the European server (eu1). You can change the TTN_REGION if needed and the TTN_STACK_VERSION.

In case you are not going to use The Things Stack network server, you have the variable TC_URI that can be configured to send data to your LoRaWAN network server. In case that your network server needs different certificates you can use TC_TRUST to configure them. By default, the gateway will use The Things Stack V3 with the proper certificates.

After a few minutes, your device information screen in the dashboard should look something like this, showing the device with the basic station service running.

Before configuring the gateway on the The Things Stack, it’s important to know the Ethernet MAC address in order to get the EUI from the TTS network. The EUI is the LoRa unique identifier (64 bits, 8 bytes) for gateways, which can be used to register the gateway on The Things Stack. In some cases, the EUI can be the Ethernet mac address (6 bytes), which is unique, expanded with 2 more bytes (FFFE) as the standard way to increment the MAC address from 6 to 8 bytes.

The EUI appears on the dashboard as a TAG of the device. Copy the EUI TAG of the summary of your gateway on the balenaCloud. Now you are ready to register your TTS LoRa gateway.

Connecting to The Things Stack (V3)

First, create a The Things Stack account if you haven’t already by visiting this website.

Once logged in, click the “Go to gateways” button. And click on the “Add gateway” link.

Paste the EUI (from the tag on your device's dashboard in balenaCloud) into your The Things Stack console. Input all the data, and remember to introduce your frequency plan, which depends on your geographic location.

Finally, click the “Create Gateway” button. You’re now ready to set up your LoRa gateway.

Set up your LoRa gateway at The Things Stack V3

When the Gateway registration is done successfully you will go automatically to the Gateway Overview page. Now it’s time to set up your new TTS LoRa gateway. From there you will be able to see the information of your LoRa gateway.

Now click on API Keys, and then Add API Key.

Click Grant Individual rights and then select Link as Gateway to a Gateway Server. Copy the key generated and go back to the balenaCloud dashboard.

Paste the API Key as the Device Variable TC_KEY. The Gateway will restart and then you should be able to see your Gateway online.

Now that you have your new TTS LoRa gateway up and running, it’s time to send data from your TTS nodes. For example, you can connect temperature sensors with TTS nodes, moisture sensors from your plants and more.

Currently you have a TTS LoRa gateway providing signal to all the sensors and nodes around your gateway. Congratulations: now you are part of the crowdsourced TTS network, helping to improve the LoRa TTS coverage. It’s time to build some LoRa nodes and benefit from your own coverage. Some minutes after deploying it, my gateway was able to route 81 messages from devices.

Connecting to The Things Industries

The Things Industries (TTI) is the professional side of The Things Network and The Things Stack. TTI is a private service for enterprises who need to manage their own LoRaWAN network cloud service on their own premises. TTS runs in a multi-tenant solution with all the members of the community, while TTI enables enterprises to manage their own network with their own SLA paying a subscription.

The Basics Station packet forward protocol is the official packet forward protocol at the Things Industries, which is available as V3 at the The Things Stack.

The goal of this tutorial is to reduce friction to The Things Industries (TTI) LoRa Gateways fleet owners (or managers) providing simple basics station LoRa gateway and enhance the upgrade over-the-air possibilities of the gateways deployed in the field providing LoRaWAN coverage.

To connect your balena LoRa gateway to The Things Industries you need a premium account at The Things Industries console.

Set up your LoRa gateway at The Things Industries

To configure your LoRa gateway, set up the previous balena installation defined above.

Once your Gateway is properly running at the balenaCloud with the TTS network variables, it’s time to register the LoRa gateway at The Things Industries console.

Go to the balenaCloud and copy the device TAG with the EUI.

Check that the EUI copied is 8 bytes (16 characters) defined as a tag. And go back to the The Things Industries console to register your LoRa gateway. Paste the EUI on the Gateway EUI field.

Once the gateway is registered go to the balenaCloud and change the Device Variables to point to the TTI network and not to the TTS network.

On the The Things Industries Gateway, the variables GW_IDand GW_KEYare not needed, so you can delete them. What is needed is to change the TC_URI to the proper websockets URL enabled by your organization. That means that your TTI organization should have set up a websockets (secure) on your server to receive the LoRaWAN packages from the gateways. Use that as TC_URI.

In some cases the certificate may change from the one used at the TTS gateway. In that case, set up the variable TC_CERT with the certificate. To check that the TTI LoRa gateway is up and running go to the TTI gateway page to analyze the Data going through the gateway.

Now the gateway is ready to receive and forward LoRaWAN packages from your sensors and nodes for your private LoRaWAN network. From here you can start introducing more gateways and manage them from balenaCloud. Remember: your first ten devices are free and fully-featured!

Until next time

We’d love to hear from you if you try this project and add more sensors. We’re always interested to see how the community puts these projects to work. Get in touch with us on our Forums, Twitter, and Instagram to show off your work or to ask questions. We’re more than happy to help.

Acknowledgements

This project is made possible by the awesome work of Jose Marcelino and Xose Pérez, RAK engineers, and the balena Hardware Hackers team.