ChirpStack is an open-source LoRaWAN network server that is being use in a coming future with Helium as a replacement of the console. This blog post explains how to install it with the companion solution I’ve built to interact with Helium router.

The Helium Chirpstack environment is still in Beta. This blog post will not be fully complete until the prod phase and you still see this orange banner. You can take a look at this post if you are curious, you will use it if you are part of the beta test. For the rest, it’s batter to come later (some part a voluntary missing).

Understand the architecture

The solution is based on different components, some managed by NovaLabs / Helium and some you will manage.

The Hotspot will soon report all the received packets to Helium router. This central router will decide to purchase the packets based on the configuration made by the Helium / Chirpstack backend.

The packets sent to the Chirpstack instance based on the OUI routing (the network support numerous LoRa Network Servers (LNS) as previously. Due to Chirpstack architecture, each region uses a different port and a different gateway bridges to handle this traffic.

Traffic goes to the LNS through a MQTT broker. The Helium / Chirpstack back-end is capturing the communication from this source for counting the DC related to this communication to invoice the end-user for this traffic.

The device addition / removal, the sessions signature are tracked by the Helium-Chirpstack to manage the configuration routing with the Helium routing service.

The Helium-Chripstack front-end allow the user to transparently use Chirpstack and manage the fleet consumption and communication payment.

Pre-requisite

Setup a virtual machine

The environment for running all the stack is a Linux server wit Docker containers. I’m installing it a on standard server with 4VCPU, 8-16GB of RAM and 128GB of storage (development sizing), running Ubuntu 22.04 LTS

Install docker & docker-compose

For this installation, i just followed the docker guide.

Install Java JDK and YARN

Java and Yarn are required to compile the helium-chirpstack interface. Let’s start with Java

[root ~]apt-get install default-jdk

Install Yarn now

[root ~] apt remove cmdtest
[root ~] curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
[root ~] echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
[root ~] apt-get update
[root ~] apt-get install yarn

Create a filesystem for storing config & data

I’ll create all the configuration and data storage into a directory located in /helium we will need some sub directories for the data files (this should be not a necessarily step in new versions)

[root ~] mkdir /helium 
[root ~] mkdir /helium/lorawan-devices
[root ~] mkdir /helium/postgresql
[root ~] mkdir /helium/mosquitto
[root ~] mkdir /helium/cli
[root ~] mkdir /helium/front
[root ~] mkdir /helium/prometheus
[root ~] mkdir /helium/grafana

Install ChirpStack with docker

Prepare your deployment

We are going to deploy the whole solution with docker-compose. This is based on chirpstack-docker project modified and with verified version.

Get the helium-chirpstack project last release. The Chirpstack comes with a docker compose template and configuration files. You can start from that point by cloning the docker template repository.

[root ~]git clone https://github.com/disk91/helium-chirpstack.git
[root ~]cd helium-chirpstack
[root ~helium-chirpstack]git checkout V0.3 # check releases on git

Copy the configuration file to the /helium directory

[root ~helium-chirpstack] cp -R chirpstack/* /helium/

Update some directory rights

[root /helium/] chown nobody:nogroup prometheus
[root /helium/] chown 472:root grafana

Setup chirpstack

Regarding PostgreSQL, I recommend to change the default password ‘chirpstack123’ by something different:

[root ~] vi /helium/configuration/postgresql/initdb/001-init-chirpstack.sh
#!/bin/bash
set -e

psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" <<-EOSQL
    create role chirpstack with login password 'fdfce449c0ba34332525';
    create database chirpstack with owner chirpstack;
EOSQL

You can use the following command to get a random string

[~] echo $RANDOM | md5sum | head -c 20; echo;

Now you need to update the chirpstack configuration file to match the database password and change the secrets.

[root ~] vi /helium/configuration/chirpstack/chirpstack.toml
[postgresql]
...
dsn="postgres://chirpstack:chirpstack123@$POSTGRESQL_HOST/chirpstack?sslmode=disable"
...

[api]
  ...
  bind="0.0.0.0:8080"
  ...
  secret="MIy62sTfjD87B8PJxaQkk5tt8dbUNH3p2CZmVwFB4F4="

You also need to setup your devaddr range for the attribution by Chirpstack

[network]

  ...

  # List devAddr range you own
  #dev_addr_prefixes=["FC014C30/28","FC014C50/28","FC014C10/29"]
  dev_addr_prefixes=["FC014C20/29"]

As a side note, this configuration file is different compared to the original one as the helium net_id is already set and it authorize unknown gateways. You can check this:

[network]
  net_id="C00053"
...
[gateway]
  allow_unknown_gateways=true

Initialize Helium Route

With the helium CLI we are going to create the route to the LNS server. For this we need to get the helium configuration service client:

[root ~] git clone https://github.com/helium/helium-config-service-cli.git
[root ~] curl https://sh.rustup.rs -sSf | sh
[root ~] apt-get install build-essential libssl-dev pkg-config protobuf-compiler
[root ~] source "$HOME/.cargo/env"
[root ~] cd helium-config-service-cli
[root ~] cargo b --release
[root ~] cp target/release/helium-config-service-cli /helium/cli/helium_cli

Currently the master version is broken you need to use the version from November 24th ( git checkout d3c79caeb5ee350ea7168a49f69ccd4743557bd1 )

The next step is to create a public / private key for protecting and authenticating the communications with the router.

[root /helium/cli] ./helium_cli generate-keypair key.bin

Once you have this key, you should be able to declare your OUI parameters.

Currently the process is in beta and I can’t detail it, out of the beta you can’t go further

Then you can configure the environment, using your own OUI. The Max copies is the maximum number of duplicates you want to receive.

[root /helium/cli]./helium_cli env-init
----- Leave blank to ignore...
Config Service Host: 
Keypair Location: ./key.bin
----- Enter all zeros to ignore...
Net ID: C00053
----- Enter zero to ignore...
Assigned OUI: 16
Default Max Copies: 15
✓ 
Put these in your environment
------------------------------------
HELIUM_KEYPAIR_BIN=./key.bin
HELIUM_NET_ID=C00053
HELIUM_OUI=16
HELIUM_MAX_COPIES=15

Create a env.sh file with the following content (adapted from what you get previously)

export HELIUM_KEYPAIR_BIN=./key.bin
export HELIUM_NET_ID=C00053
export HELIUM_OUI=16
export HELIUM_MAX_COPIES=15
export HELIUM_CONFIG_HOST=http://mainnet-config.helium.io:6080/

You can source the env file for the next use of the helium_cli command.

[root /helium/cli] source env.sh

Now we can create a route to configure the service. You will need to replace by your own device address start & stop value.

[root /helium/cli] ./helium_cli generate-route
[root /helium/cli] ./helium_cli add devaddr FC014C20 FC014C27 --commit
[root /helium/cli] ./helium_cli add protocol gwmp --host dev.helium-iot.eu --port 1700 eu868 1700 --commit
[root /helium/cli] ./helium_cli add gwmp-mapping us915 1701 --commit
[root /helium/cli] ./helium_cli add gwmp-mapping au915 1702 --commit

Possible region are us915, eu868, eu433, cn470, cn779, au915, as923_1, as923_1b, as923_2, as923_3, as923_4, kr920, in865, cd900_1a

To publish your route you need to get your public key, for this use the following command, note this key, you will require it later.

[root /helium/cli] ./helium_cli env-info
...
"public_key_from_keypair": "14pcx1R...KLBakfoLX"
...

Now you can register the route

[root /helium/cli] ./helium_cli create-route --owner <your public key> --commit

Setup & Build Helium-Chirpstack companion

Setup configuration file

You need to setup the configuration file, there are many important settings, lets review them by categories:

[root ~] vi /helium/configuration/helium/configuration.properties

There are the technical information where you setup the password you previously set for the database:

## PostgreSQL
spring.datasource.url=jdbc:postgresql://postgres:5432/chirpstack
spring.datasource.username=chirpstack
spring.datasource.password=<type here the password>

You need to setup the helium api and OUI with the public key obtained previously. The keyfile should not be changed, it is mounted in the docker-compose file. The helium GRPC server and port as not yet disclosed.

## Helium GPRC
helium.grpc.private.keyfile.path=/etc/helium/pkey.bin
helium.grpc.public.key=14pcx1R...KLBakfoLX
helium.grpc.oui=<Your OUI>
helium.gprc.server=<Helium Grpc Server>
helium.grpc.port=<helium Grpc Port>

You will need to create an API key for chirpstack, we will do this later. Right now, just makes this entry empty.

## Chirpstack API
chirpstack.api.base=http://chirpstack:8080
chirpstack.api.admin.key=

Setup the email configuration, email is required to create user accounts. Here is an example for sendgrid

## #############################################################
## Email configuration
spring.mail.host=smtp.sendgrid.net
spring.mail.port=25
spring.mail.username=apikey
spring.mail.password=G.A_Wv9...

Setup your billing information according to the documentation in the configuration file

Then you need to setup the service information, this will be used in email communication. By setting signup at true, you authorize unknown user to register on the console.

## #############################################################
## Service SETUP
helium.console.url=https://dev.helium-iot.eu
helium.console.name=Helium-Iot Console (Dev)
helium.mail.from=contact@helium-iot.eu
helium.allows.signup=true

You also need to setup the option you give to user to add DCs, you can enable DC transfer between tenants and DC purchasing with stripe. If you enable stripe, you need to specify the public and private key of your stripe account. If you don’t specify them, by default it has the stripe demo keys.

## Stripe
helium.stripe.key.private=sk_test_51H...
helium.stripe.key.public=pk_test_51Hnj...
helium.stripe.enable=true
helium.transfer.enable=true

Setup the NGINX Server

In the /helium/configuration/nginx/default.conf file, you need to change the server name to match with your server:

server {
    listen 80;
    listen [::]:80;

    server_name console.foo.bar;
    ...
    location / {
        return 301 https://www.foo.bar$request_uri;
    }

In the /helium/configuration/nginx/default.conf.withssl file, you need to change the server name to match with your server:

server {
    listen 80;
    listen [::]:80;

    server_name console.foo.bar;
    ...
    location / {
        return 301 https://www.foo.bar$request_uri;
    }
    ...
server {
    listen 443 default_server ssl http2;
    listen [::]:443 ssl http2;

    server_name console.foo.bar;
    ssl_certificate /etc/nginx/ssl/live/foo.bar/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/live/foo.bar/privkey.pem;

Build the software image

This part is going to build the back and the front part. You need to set some parameter like the Console name you want to display and the link to the user terms you want your user to accept before registering. Edit the Makefile and update the env variable

[root ~helium-chirpstack] vi Makefile
...
CONSOLE_NAME=Helium-IoT
CONSOLE_TERMS=https://...
API_HOST=
CHIRPSTACK_HOST=
...

CONSOLE_NAME is what will be displayed as a title in the console, CONSOLE_TERMS is the link given to user when registering with e service conditions. API_HOST and CHIRPSTACK_HOST are left blank with the docker-compose setup.

[root ~helium-chirpstack] make build

You can put your own favicon (it will not be override later) by copying it into /helium/front/static/front/favicon.ico

Run it

We are close to the final steps, now we can start the stack, then we will need to make the final steps

[root ~helium-chirpstack/chirpstack] docker compose up -d

The system should start, now we can request the initial ssl certificate (change with your server name)

[root ~helium-chirpstack/chirpstack] docker compose run --rm certbot certonly --webroot --webroot-path /var/www/certbot/ -d dev.helium-iot.eu

Restart with the ssl configuration

[root ~] docker stop chirpstack-nginx-1
[root ~] mv /helium/configuration/nginx/default.conf /helium/configuration/nginx/default.conf.withoutssl
[root ~] mv /helium/configuration/nginx/default.conf.withssl /helium/configuration/nginx/default.conf

Once done, you need to directly connect to chirpstack to setup admin password and API key. With your browser go on https://foo.bar/?override=true

The default user password is admin / admin. The first step is to change your admin password.

Then you can create an API key :

Give a name to the key, whatever, then copy the given token and add it into the /helium/configuration/helium/configuration.properties

## Chirpstack API
chirpstack.api.base=http://chirpstack:8080
chirpstack.api.admin.key=eyJ0eXAiOiJK...

Then restart the docker container running the backend to take it into account

[root ~] docker restart chirpstack-helium-1

At this step … you should get it working 😉

Configure invoicing

If you want to use stripe for DC purchasing, you need to setup your company profile to get the right information printed on invoices. For this, in the application, connected as admin, edit the invoice setup:

Update your letsencrypt certificate

When you will need to update you certificate, here is the command to use

[root ~helium-chirpstack/chirpstack/] docker compose run --rm certbot renew

Update from a previous release

If you upgrade Helium companion from a previous release, please make sure you review the configuration file update and add the missing config entries

[root ~helium-chirpstack] diff configuration.properties /helium/configuration/helium/configuration.properties

.