This is the second in a series of posts detailing how to get started using the Helium IoT LoRaWAN network. In this post, I will walk you through deploying and configuring Chirpstack, an open source LoRaWAN Network Server(LNS), to work with the Helium IoT network. After you are finished, you will be able to onboard a device in the US915 LoRaWAN region. You can view the first post on why you would want to use this network and other options if you’re not interested in deploying your own LNS here.
Requirements
You will need to have these five things below before starting this guide to complete a fully working setup.
Basic shell and SSH knowledge
US915 LoRaWAN Device
Steps
Deploy Server Instance
Deploy Chirpstack
Configure IoT Config Service
Adding a Device
Step 1. Deploy Server Instance
Although I’ll be deploying on Vultr, the steps will be very similar on any other VPS/Compute provider. I am not affiliated with Vultr in any way, I just enjoy the simplicity and performance of their service. You can use any hosting service you like, and the steps should be the same if you pick the same server OS.
Let’s deploy our server instance first. Visit https://my.vultr.com/deploy to start.
Select your server type and architecture.
Next, select the location closest to the region you will be servicing. In this case, it will be in the US.
Next, select the Operating System, we’ll be using Ubuntu 22.04 LTS x64.
Next, we’ll select the server size; the smallest will be plenty to start.
You can leave the defaults for the rest, although auto backups are not required.
Once your server is ready, visit the instance details page. We’ll grab the server IP Address and root password from this page. For an actual deployment, using the root user is not recommended. We’ll only use root because it’s the quickest way to demonstrate this setup.
Let’s SSH into the server using the IP and root password provided.
Step 2. Deploy Chirpstack
Now that you’re logged into your server instance let’s deploy Chirpstack.
First, we’ll install docker.
And then docker compose.
Next, we’re going to clone the Chirpstack docker compose configuration files.
Since we are deploying in the US LoRaWAN region, we will change the default gateway bridge starting on line 22 from EU868 to US915 in thedocker-compose.ymlfile in the current directory.
To this:
Next, we must modify the network section and add a new gateway section in the file below. Use the Helium net ID provided and replace <start_addr> with the starting DevAddr you received when you purchased your OUI.
configuration/chirpstack/chirpstack.toml
Finally, start up the Chirpstack services.
Visit the web UI at http://<your_server_ip>:8080/#/login
Use these credentials to log in:
Username / email: admin
Password: admin
If you want to shut down the Chirpstack services later, use Ctrl-C.
Step 3. Configuring IoT Config Service
The IoT Config Service provides configuration settings and values for the LoRaWAN IoT Helium network. We will next download a CLI utility to tell the IoT Config Service how to communicate with our Chirpstack LNS Server and route our device data.
Let’s download the CLI utility to start.
Go to https://github.com/helium/helium-config-service-cli/releases/latest and find the appropriate release for your local computer.
Next, open a terminal window and use wget to download the file to the current directory, unzip or untar, then enter the directory.
On Linux:
First, we will set some environment variables that will be used with the CLI for the rest of the commands. This command will interactively ask you for each of the required fields. Use the values provided below for host and net ID, and replace the <> placeholders with your specific values. You must have your delegate keypair.bin on your local computer and specify its location path below. Max copies define how many gateways you want to receive a device uplink from if it is heard by more than one. This can be useful for geolocating applications.
Use the following command below to add the environment variables to your shell environment.
We’ll start by telling IoT Config Service to create a route ID for our OUI. We’ll use this ID in all our commands to let the Config Service know which configuration we are referring to.
Next, let's tell the config server the host address of our LNS server. This is the IP address of your Vultr instance.
Next, set the GWMP region. This tells the config service which regions of the world we want routed to our LNS server. We’ll just be doing US915 for North America here, but you can repeat this for any other regions you wish to support. For each additional region you add, be sure to match the configuration port in your Chirpstack config.
Next, we’ll tell the config service which DevAddr range to assign to our route. Your DevAddr range will be supplied to you when you purchase your OUI. See the docs here for more information on what DevAddrs are.
Last, we need to tell the Config Service where to route our first LoRaWAN device packets. We’ll just be specifying the App/Join and Dev EUI here; when you add the device in Chirpstack, you will either add or create the AppKey there.
We have now given the Config Service enough information to route the packets for a single US915 LoRaWAN device to our LNS using the Helium IoT network.
Step 4. Adding a Device
The very last step is to add the device in Chirpstack.
To do this, we need to do three things.
First, we need to create a device profile. This specifies things like the LoRaWAN device region, version, and class.
Next, we need to create an application. Devices are grouped by applications in Chirpstack.
Last, we will add the device to the application with the App/Join EUI and DevEUI we used above.
Finally, add or create an AppKey for your device.
Initiate a join on your device, and you should see frame events in this view.
You have just deployed your very own Helium LoRaWAN network server. Nice work!
If you need help, join us in the Helium Discord server and ask away in the #openlns channel.