In the past we have showed how to deploy a The Things Network (TTN) LoRa gateway with balena, and how to build an outdoor TTN LoRa gateway with balenaFin. In this blogpost, you will learn how to deploy a The Things Network (TTN) LoRa gateway running the newest Semtech Packet Forward protocol, the Basics Station.
This project runs on a Raspberry Pi or balenaFin with a RAK2245 Pi Hat, in just one click. The Basics Station protocol equips LoRa gateways with a reliable and secure communication between the gateway and the cloud.
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 TTN, with some minor changes.
Contents
- Before you start
- Tutorial
- Until next time
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 Network 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.
Hardware required
To build this project, you’ll need the following:
- Raspberry Pi (we’ve tested this on a Pi4)
- RAK 2245 pi hat
- SD card in case of the RPi 4
- USB-C cable
Software setup
For the software, you’ll need:
- A TTN account (sign up here)
- A free balenaCloud account (sign up here). Remember: your first ten devices are free and fully-featured!
- Software to flash an SD card e.g. balenaEtcher
- (Optional) If using CLI method, you’ll need the project code
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:
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. 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 Network, it’s important to know the Ethernet MAC address in order to get the EUI from the TTN 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 Network. 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 TTN LoRa gateway.
Connecting to The Things Network
First, create a The Things Network account if you haven’t already by visiting this website.
Once logged in, click the “Gateways” button. And click on the “Register gateway” link.
Check “I’m using the legacy packet forwarder” checkbox on the registration form. The Things Network still does not officially support Basics Station packet forward protocol. Checking this checkbox internally makes it work. Actually, The Things Industries supports Basics Station packet forward protocol as the standard; you can read more below where we explain how to set up a TTI LoRa gateway with balena.
Paste the EUI (from the tag on your device’s dashboard in balenaCloud) into your The Things Network console. Input all the data, and remember to introduce your frequency plan, which depends on your geographic location.
Finally, click the “Register Gateway” button. You’re now ready to set up your LoRa gateway.
Set up your LoRa gateway at The Things Network
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 TTN LoRa gateway. From there you will be able to see the information of your LoRa gateway, which you’ll notice is already connected.
On this configuration page, there are two important keys that you need to configure the LoRa gateway on the balenaCloud dashboard: the Gateway ID and the Gateway Key. These variables are needed because each TTN LoRa gateway has its own unique key and ID. Change these variables by selecting the Device Environment Variables navigation item (on the left-side menu within an application on balenaCloud).
Once your gateway has been created, copy these variables (ID and Key) from the TTN console and go back to the balenaCloud dashboard and create two new device environment variables:
GW_ID is the EUI from the balenaCloud device status screen, and…
GW_KEY it’s the Gateway Key from the TTN console.
The other parameters would automatically have been created 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.
Having said that, the gateway is created with European frequency. If you live in another LoRaWAN region, feel free to change the TC_URI with another LNS wss://lns.{eu-us-in-au}.thethings.network:443 depending on your LoRaWAN frequencies.
GW_GPS has been set to false. Change the value to true if you have GPS on your RAK Pi HAT. For example, the RAK2245 has GPS.
SPI_SPEED = 20000000, GW_RESET_PIN = 11
TC_URI= wss://lns.{eu-us-in-au}.thethings.network:443.
Once you have added these variables your device will restart and then return to a running state. To check that, go to the TTN console and check if it shows connected with a green led.
Now that you have your new TTN LoRa gateway up and running, it’s time to send data from your TTN nodes. For example, you can connect temperature sensors with TTN nodes, moisture sensors from your plants and more.
Currently you have a TTN LoRa gateway providing signal to all the sensors and nodes around your gateway. Congratulations: now you are part of the crowdsourced TTN network, helping to improve the LoRa TTN 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. TTI is a private service for enterprises who need to manage their own LoRaWAN network cloud service on their own premises. TTN 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 Network 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 TTN 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 TTN 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 TTN 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, RAK engineer, and the balena Hardware Hackers.