Skip to main content

Run a LoRaWAN Network Server

OpenLNS is the platform that enables any LoRaWAN Network Server (LNS) to use Helium's IoT Network. In this guide, we'll walk you through the process of setting up and configuring OpenLNS.

What to Expect​

There are two major steps to run your LNS.

  1. Register as a Helium Organization
  2. Set up your LNS
  3. Set up your routing rules so the network infrastructure knows where to send your sensor data to.

Register as a Helium Organization​

Before getting started, make sure you have the following:

  • Helium Network Organizationally Unique Identifier ("OUI")
  • Helium LoRaWAN devAddr slab (if you have your own LoRa Alliance NetID, please refer to the roaming setup guide)
  • LoRaWAN Network Server ("LNS"). A popular option is ChirpStack. We will show you how to set up a Chirpstack instance on the Helium Network.

Purchasing OUI and devAddr Slab​

Before you can purchase an OUI and devAddr Slab, you need to do the following.

  • Generate an owner key pair
  • Generate a delegate key pair
  • Make sure you have a Helium Wallet

You can create a Helium Wallet following the guide here. Let's now generate the key pairs

  1. Run this to pull & build the config service cli:

    $ git clone https://github.com/helium/helium-config-service-cli.git
    $ curl https://sh.rustup.rs -sSf | sh
    $ source "$HOME/.cargo/env"
    $ brew update
    $ brew install protobuf
    $ cd helium-config-service-cli
    $ cargo b --release

  2. You can then find the built binary file helium-config-service-cli under ./target/release inside the helium-config-service-cli directory. We would recommend renaming it into something short such as main so you can type less words (you can rename it by running mv helium-config-service-cli main)

  3. Now that we have the CLI binary, let’s just put it in a separate folder. This is recommended only for simplicity's sake. Just copy main into the folder you created. You can reference the following commands:

    $ cd ..
    $ mkdir cli-testing
    $ cd cli-testing
    $ cp ../helium-config-service-cli/target/release/main .

  4. Let’s generate the keypairs you’ll be using to authenticate your interactions with the config service, so only you can create/modify/delete routes. Run this command twice for 1) owner keypair and 2) delegate kepair and name files accordingly. Run ./main env generate-keypair <key file name>.bin. and you should find a file called <key file name>.bin. Print out the public key of your keypair by running:

    $ ./main env info --keypair <key file name>.bin

    Delegate Keypair: The delegate key is actively used to create and manage routes. In case it is ever compromised, it can be updated using the owner key.

    Owner Keypair: The owner key is irreplaceable and should be kept safe, secure, and private at all times. If lost or compromised, you could lose your OUI.

Now, please send an email to hello@helium.foundation with

  • The public key of your owner key pair
  • The public key of your delegate key pair
  • The Helium Wallet address
  • The number of devAddr you want

The OUI costs $100 paid in Data Credits ("DC"), while the devAddr slab mandates a minimum of 8 devAddrs that cost $100 each.

Set up Your LNS​

Set Up Chirpstack Docker​

  1. git clone https://github.com/chirpstack/chirpstack-docker.git
  2. Open configuration/chirpstack/chirpstack.toml
    1. Under [network] Change net_id to 0x00003C
    2. Under [network], add dev_addr_prefixes with the devAddr slab assigned to you. First run ./main org get --OUI <your OUI> to get your OUI's DevAddr constraints. Then run ./main subnet-mask <your OUI's starting DevAddr> <your OUI's ending DevAddr> to find your subnets. In the chirpstack toml file put in dev_addr_prefixes = [<your subnets>], which is formatted with the following rule: starting devAddr/32-log2(devAddr slab size). Let's say you requested 8 devAddr slab and the starting devAddr is 00000000, then you would input dev_addr_prefixes = ["00000000/29"]
    3. Under [gateway], add a line allow_unknown_gateways=true

Set Up Supported LoRaWAN Region​

You need to deploy a gateway bridge for each LoRaWAN region you plan on supporting on Chirpstack. By default, Chirpstack only supports EU868. This tutorial will show you how to add support for US915, and you can replicate the same process for other LoRaWAN regions.

Open docker-compose.yml, you will find a container called chirpstack-gateway-bridge-eu868. Add the following.

chirpstack-gateway-bridge-us915:
    image: chirpstack/chirpstack-gateway-bridge:4
    restart: unless-stopped
    ports:
      - 1701:1700/udp
    volumes:
      - /helium/configuration/chirpstack-gateway-bridge-us915:/etc/chirpstack-gateway-bridge
    depends_on:
      - mosquitto
    logging: *logs

Now head over to configuration/chirpstack-gateway-bridge and create a directory called chirpstack-gateway-bridge-us915. In that directory, create a file called chirpstack-gateway-bridge.toml. In that file, put down the following.

# See https://www.chirpstack.io/gateway-bridge/install/config/ for a full
# configuration example and documentation.

[integration.mqtt.auth.generic]
servers=["tcp://mosquitto:1883"]
username=""
password=""

[integration.mqtt]
event_topic_template="us915_1/gateway/{{ .GatewayID }}/event/{{ .EventType }}"
state_topic_template="us915_1/gateway/{{ .GatewayID }}/state/{{ .StateType }}"
command_topic_template="us915_1/gateway/{{ .GatewayID }}/command/#"

Make sure you have port 1700 and 1701 both open on your server.

Run Your Chirpstack​

Run docker-compose up and you should be able to log in with the default credential:

  • username = admin
  • password = admin

Set up Routing Rules​

How to Get Traffic to Your Chirpstack​

While Chirpstack is up and running for you, you need to let Config Service know of its existence. First, let’s initialize some environment variables so that you don’t have to tell the CLI the same thing over and over again:

Run ./main env init

  1. Fill in http://mainnet-config.helium.io:6080/ for Config Service Host
  2. Fill in the relative path of your delegate key pair file for Keypair Location
  3. Fill in 0x00003C for Net ID
  4. Fill in your OUI for Assigned OUI
  5. Fill in the number of multi-buy you want for Default Max Copies as a default for your routes.
  6. Then export the environment variables. This needs to be done manually. You will see something like this and just add export to each line and run it. For instance, you would run export HELIUM_MAX_COPIES=15 variable. Do NOT put a space around the = sign
Setting environment variables as shown in a terminal window.

Now, you are ready to generate your first route. Routes contain the necessary information for us to know how to route a packet — DevEUI+AppEUI (for routing join requests), DevAddr range (for routing uplinks), Endpoint (so we know where to send the packet to), etc.

  1. Run ./main route new --commit
  2. You can then see the empty route template. It should look like this, except that you should be seeing your own Net ID, assigned OUI, max_copies in there:
Route Creation as shown in a terminal window.

Next, let’s define the endpoint that you use for ingesting traffic. You can run:

$ ./main route update server --host <server ip> --port 1700 --route-id <route-id> --commit

Finally, let's make sure you specify the port for each LoRaWAN region you plan on supporting on your Chirpstack. In our example, run

$ ./main route update add-gwmp-region —route-id <route-id> us915 1701 eu868 1700 --commit

How to Add Your First Device​

In this example, we will show you how to add an US915 OTAA Class A Device. On Chirpstack, navigate to Device Profiles, and hit Add device profile. Name it something descriptive like US915 OTAA Class A, and change the Region to US915 in the drop down. Leave everything else as default.

The navigate to Applications, add an application if you don't have one yet. In that application, hit Add device. Fill in the Name, Device EUI and select the device profile you just created.

Now that the device is successfully created on Chirpstack, you need to let Config Service know about it, you need to run

$ ./main route euis add --route-id <route-id> -d <dev-eui> -a <app-eui> --commit

While this allows your device to join on the Helium Network, you also need to specify a DevAddr range on that route so the device can also send uplink. It is recommended to set your route DevAddr to be the devAddr slab of your OUI. Run

$ ./main route devaddrs add -s <start devAddr> -e <end devAddr> --route-id <route-id> -- commit

Upcoming Tutorials​

There will be an upcoming tutorial around session-key-filter (SKF).

The Config Service can be used to manage an OUI and devAddr. There are two ways to interact with the Config Service:

  1. Using the Command-Line Interface ("CLI") detailed below.
  2. Alternatively, you can also write scripts to interact with the Config Service directly through GRPC APIs for a more programmatic approach