Skip to main content

Advanced Configuration

Session Key Filter (SKF)​

Session Key Filters (SKF) regulate device traffic on specific devAddrs by utilizing LoRaWAN device session keys. They establish conditions to either permit or restrict data flow based on the configured session keys. It essentially allows the LNS operators to accept and reject traffic on a device (session) level.

In this example scenario, consider two device addresses (devAddr) 1 and 2:

  • Provided Session Key for devAddr 1 and "ignore empty skf" = false:
    Only allows traffic through devAddr 1 if it passes Message Integrity Code (MIC) checks.
  • No Session Key for devAddr 2 and "ignore empty skf" = false:
    All traffic is allowed through devAddr 2 without MIC checks.
  • No Session Key for devAddr 2 and "ignore empty skf" = true:
    All traffic through devAddr 2 is blocked.

The SKF will regulate traffic based on session key availability and the "ignore empty skf" flag, independently per devAddr.

Check the SKF flag for a route by running

helium-config-service-cli route get --route-id <route-id>

Importance of Configuring Session Key Filters​

Configuring SKFs for devices introduces an additional layer of security on the Helium network. In instances where SKFs are not established, the network relies on the devAddr to associate packets with the respective OUI, potentially attributing unauthorized packet costs to the OUI owner.

Implementing SKFs counteracts this risk by empowering the Helium Packet Router to authenticate packets, thus preventing the delivery of unwanted payloads (and their respective DC cost).

Max Copies​

Given that LoRaWAN devices openly broadcast uplinks, it's common for multiple Hotspots to capture the same device uplink within the Helium Network. LNS operators can customize the number of duplicate uplinks they wish to receive and pay for by setting a max copies amount. Configuring the max copies setting offers two significant potential advantages for receiving identical uplinks from multiple Hotspots:

  • Better downlink performance: if the max copies setting is 10, the LNS will receive up to 10 copies of the same uplink, and the downlink will be sent by the Hotspot with the best RSSI of those 10.
  • Geolocation: It is possible to leverage Hotspot metadata to estimate the sensor location without GPS or Wi-Fi.

There are 2 levels of granularity for the max copies setting:

  1. Route level: applies to all devices registered under the route
  2. SKF level: only applies to the device with the specified network session key (NwkSKey). This configuration overrides the route-level max copies setting

As an example, if the LNS operator has a route that contains device A and B, and configures a route-level max copies setting of 2 and an SKF level max copies setting of 5 for device B. Then device A will inherit the route level max copies setting = 2, and device B will use its SKF-level max copies setting = 5.

Improve Join Performance​

Since Over-The-Air-Activation (OTAA) devices require a network joining process before they start transmitting valuable sensor data, it is beneficial to ensure the network joining process is as effective as possible.

Join performance can be improved by increasing the number of copies of the same join requests the LNS receives, because then the join accept will be delivered by the Hotspot with the best RSSI, increasing the possibility of a successful delivery.

Join requests are free on the Helium Network. LNS operators can leverage max copies to improve the join performance without additional cost overhead.

As an example, the LNS operator can define a route-level max copies setting of 20 and all SKF-level max copies setting of 1. This will have the effect of allowing up to 20 copies of join requests and 1 copy of uplink. This way, the devices will have a much better chance to join, without consuming extra DC from the uplinks once joined.

Automated EUI and SKF Route Updates​

As the ecosystem of LNS operators grows, an increasing number of developers have open-sourced their tooling for running a Helium-enabled LNS. These tools enable functionality such as EUI and SKF automation to per-tenant Data Credit accounting.

A selection of the tools are outlined below.

Helium Route Updater​

The Helium Route Updater service is a third-party service that can be run alongside a ChirpStack deployment to automate the adding/removing of EUIs as well as enabling session key filters on devices to block traffic from devices that are not yours.

You can find the service on GitHub here. There is also a section in the readme that details how to easily add it to your ChirpStack docker compose, found here.

Disk91 Helium Chirpstack​

This service includes several utilities including EUI management and per-tenant accounting.

Find the service on GitHub here

Chirpstack-hpr by Bones​

This service includes several utilities including EUI and SKF management.

Find the service on GitHub here

Config Service Interaction​

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).
  2. Alternatively, you can write scripts to interact with the Config Service directly through GRPC APIs for a more programmatic approach.

Hotspot Location Data​

Hotspot location data can be requested from the Config Service using either the CLI or GRPC APIs.

EUI Pair Wildcard​

In some applications, deployers may have many DevEUIs all associated under the same AppEUI, and it might be inconvenient to provision all those EUI pairs individually. If the LNS operator would like to receive Join Requests for all devices under a certain AppEUI, simply input 0000000000000000 for the DevEUI when adding an EUI pair.

Add and Remove Delegate Keys​

Note that only owner key can perform the actions below. OUI owners can add delegate keys by running

helium-config-service-cli org update delegate-add --pubkey <public key of the delegate key pair you are trying to add> --keypair <relative path of your **owner** keypair path> --commit

OUI owners can remove delegate keys by running

helium-config-service-cli org update delegate-remove --pubkey <public key of the delegate key pair you are trying to remove> --keypair <relative path of your **owner** keypair path> --commit

Set up NGINX for Chirpstack Docker​

NGINX can be used for web serving, reverse proxy, caching, load balancing, SSL and etc. In order to set it up on Chirpstack docker, add the following section in docker-compose.yml

nginx:
    image: nginx:latest
    container_name: chirpstack_nginx
    restart: always
    volumes:
      - "./logs/nginx:/var/log/nginx"
      - "./configuration/nginx.conf:/etc/nginx/conf.d/default.conf"
    ports:
      - 80:80
      - 443:443
    depends_on:
      - chirpstack
    networks:
      - iot-network

and then create a new file under the configuration directory called nginx.conf, with the following content

upstream chirpstack_upstream {
  server chirpstack:8080;
}

server {
  listen 80;
  server_name _;

  location ^~ /api {
    grpc_pass grpc://chirpstack_upstream;
  }

  location / {
    proxy_pass http://chirpstack_upstream;

    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_redirect off;
  }
}