KerOS 6

Aim

Similarly to legacy (GWMP) packet forwarder, the Basic Station Packet Forwarder is a service running on a LoRa gateway. It forwards the LoRa packets emitted by end-devices and received by the gateway to a LoRa Network Server (LNS) and vice-versa, hence its name.

The Kerlink Basic Station Packet Forwarder (BSPF) is based on lorad daemon

Once installed and configured, it is able to connect to a “LNS” or a “CUPS” server and handle all associated services (Radio configuration, Forward uplink packets, schedule downlink packets, etc.).

It implements the same protocols and authentication methods than Semtech LoRa Basics™ Station reference implementation.

Main features of reference implementation are implemented in Kerlink Basic Station Packet Forwarder, including:

The features not supported are listed below:

The additional features:

Installation

This section is obsolete since version 6.3.1.
With the newest version, basicstation package is now installed by default.
You can skip to the next step: Configuration

Using Cockpit

With pre-defined software update BasicStation Installation
It allows the subsequent use of the LoRaWAN cockpit configuration functionality

It allows the subsequent use of the LoRaWAN cockpit configuration functionality

Magic Link: curl --compressed -s https://upgrade.wanesy.com/BasicStation_Cockpit | sh

Using commands

Kerlink Basic station is not installed by default on KerOS < 6.3.1. To install it, do the command:

sudo apt update
sudo apt install basicstation

Additionnaly, there is other package installable that include a tool to connect easily to main available LNS in the market:

See LoRa use cases for more details

Configuration

Kerlink Basic Station Packet Forwarder is disabled by default. It should first be configured for the wanted server (CUPS and/or LNS) before being started.

Depending on the authentification mode

No authentication on LNS server

A tool handles these 2 steps. Run the following command:

sudo klk_bs_config --enable --lns-uri "ws://lns.local:3001"

For a LNS server named lns.local
For a simple websocket, URI must start with ws:// (and not wss://)

TLS Server Authentication

Additionally to previous mode, a *.trust file should be provided to check server authenticity. (excepting for “Publicly known”/“Globally signed” certificates like “let's encrypt”, AWS, etc…)

Examples:

1 - With a LNS server named lns.local with a reference certificate named ca_cert

sudo cp ca_cert /etc/station/tc.trust
sudo klk_bs_config --enable --lns-uri "wss://lns.local:3001"

2 - With a CUPS server named cups.local with a reference certificate named ca_cert

sudo cp ca_cert /etc/station/cups.trust
sudo klk_bs_config --enable --cups-uri "https://cups.local"

TLS Server and Client Authentication

Additionally to previous mode, *.key and *.crt files should be provided to authenticate client (gateway) on server.

Example with an AWS CUPS server:

After having registered your gateway on AWS IOT core, the following files should be available:

  • xxx.cert.pem: the (public) certificate of the gateway.
  • xxx.private.key: private key of gateway.

Additionally, the CUPS endpoint should be known. In this example https://XXX.cups.lorawan.eu-west-1.amazonaws.com will be used. The certificate of this server is globally signed so .trust file is not needed.

  1. Push key xxx.private.key and certificate xxx.cert.pem on gateway
  2. Rename them as cups credentials:
sudo cp xxx.private.key /etc/station/cups.key
sudo cp xxx.cert.pem /etc/station/cups.crt
  1. Activate Basic Station forwarder:
sudo klk_bs_config --enable --cups-uri "https://XXX.cups.lorawan.eu-west-1.amazonaws.com"

The same authentification mode can be used with TC instead of CUPS
Replace files cups.* by tc.*, and use the option --lns-uri

TLS Server Authentication and Client Token

In this mode, only a file *.key should be provided to authenticate the client. The file *.key must contain one or more HTTP header fields that contain an authorization token such as

Authorization: AZ385fgheuyuslo3due

Example with an TTN CUPS server:

Register your gateway for required authentificated connection and generate an API key for CUPS
Once the gateway registered, download the cups.key file

  1. Push key cups.key on gateway
sudo cp cups.key /etc/station/cups.key
  1. Activate Basic Station forwarder
sudo klk_bs_config --enable --cups-uri "https://eu1.cloud.thethings.network:443"

The same authentification mode can be used with TC instead of CUPS
Replace files cups.* by tc.*, and use the option --lns-uri

Advanced configuration

Global configuration

By default, Kerlink Basic Station Packet Forwarder doesn't need any configuration files excepting those described above.

However, for advanced configuration, default settings can be modified by creating a configuration file named /etc/station/station.conf.

It allows to:

An example of this configuration file is provided in /usr/share/basicstation/station.conf.example.

Packet buffering (database)
Before enabling packet buffering, make sure your LNS supports it.
The buffer database must not exceed 200 messages.

LBT/CCA specific case

For LNS which doesn't embed AS923-1 with LBT, it needs to be activated manually by using following commands:

# Disable current config
sudo klk_bs_config --disable
 
# Use "Japan" lorad configuration explicitly and prevent from reconfiguration from LNS 
sudo klk_bs_config --enable --loradconf AS923-1-JP.json --ignore-reconf

Local DevAddr Filtering

In the case the LNS does not provide any NetID filter in the router_config message, it is possible to set local filters in order to only forward LoRa uplinks provided by a subset of devices.

To configure this feature, use the -f option of the klk_bs_config tool, and provide inclusive and/or exclusive filters to indicate the sets of DevAddr to be kept and/or rejected.

(see the page for more details about filters values)

Example:

sudo klk_bs_config -e -f '24abcdef/7' -f '!24abcdef/12'

will configure basic station to forward messages provided by devices with DevAddr between 0x24000000 and 0x249fffff , or between 0x24b00000 and 0x25ffffff.

The lead “0x” is not required before the base address of the filter.

Local JoinEUI Filtering

In the case the LNS does not provide any JoinEUI filter in the router_config message, it is possible to set local filters in order to only forward LoRa Join Requests provided by a subset of devices.

To configure this feature, use the -j option of the klk_bs_config tool, and provide inclusive and/or exclusive filters to indicate the sets of JoinEUI to be kept and/or rejected.

(see the page for more details about filters values)

Example:

sudo klk_bs_config -e -j '7076FF0001000000/40'-j '!7076FF0001005555'

will configure basic station to forward Join Requests provided by devices with JoinEUI between 0x7076FF0001000000 and 0x7076FF0001005554 , or between 0x7076FF0001005556 and 0x7076FF0001FFFFFF.

The lead “0x” is not required before the base address of the filter.

Local DevAddr Filtering/Local JoinEUI Filtering

The tools klk_bs_config accepts several filtering options, such as -f and -j.
To use them together, you must write them on a single line:

sudo klk_bs_config -e -f '24abcdef/7' -f '!24abcdef/12' -j '7076FF0001000000/40'-j '!7076FF0001005555'

If you run the command with only -f or only -j, the new command will replace the previous one.
In other words:
klk_bs_config -f deletes or overwrites the previous -j configuration,
and klk_bs_config -j deletes or overwrites the -f configuration.
👉 You must therefore always specify all the desired options in the same command, otherwise the others will be lost.

Troubleshooting

Logs of basicstation are available with the command:

sudo journalctl -fu basicstation

You can activate debug logs by editing the file /etc/station/station.conf.
They can be set globally: locate the [DEFAULT]section and set log_level = DEBUG
or you can activate debug logs by section.

A restart of the basicstation is required to take changes into account:

systemctl restart basicstation

Since version 6.3.1, logs are also available in /var/log/station.log*