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, also known as
"multibuy." Configuring the max_copies setting offers several significant advantages:
- 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, per the selection mechanism of the LNS.
Helium reports Hotspots' responses in chronological order, which can be challenging for scheduling downlinks because the first Hotspot to report may not necessarily be the closest or have the strongest RSSI/SNR attributes. This is important for downlink scenarios such as Class-C devices, ADR, confirmed uplinks, or standard downlinks on Class-A devices. Leveraging multibuy ensures that there is a strong Hotspot available to deliver the downlink message. - Geolocation: It is possible to leverage Hotspot metadata to estimate the sensor location without GPS or Wi-Fi.
- Multilateration: For devices that do not have internal location-solving abilities (GPS), the metadata of the packet report and Helium Network can be leveraged to solve for a device location.
The Helium Network charges for each response for a given payload. Each Hotspot that reports a payload from a given device is eligible to be rewarded. The LNS operator can choose how many reports they would like to buy. For instance, for a multibuy value of 10 on a device that only receives 8 reports, the OUI would be charged 8 DC ($0.00008 USD). This assumes the payload was less than 24 bytes.
There are two levels of granularity for the max copies setting:
- Route level: Applies to all devices registered under the route.
- SKF level: Applies only 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 of 2, and device B will use its SKF-level max copies setting of 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:
- Using the Command-Line Interface (CLI).
- 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;
}
}