Wirnet™ i-series

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Kerlink Basic Station Packet Forwarder ======

===== What is the Kerlink Basic Station Packet Forwarder ? =====

Similarly to legacy (GWMP) packet forwarder, the Basic Station Packet Forwarder is a program 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 from [[wiki:lora:cpf|Common Packet Forwarder]].

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 [[https://lora-developers.semtech.com/build/software/lora-basics/lora-basics-for-gateways/|Semtech LoRa Basics™ Station]] reference implementation.

{{:playground:lora:basicstation_overview.png?800|}}


===== What are the differences with Semtech LoRa Basics™ Station ? =====

The [[https://lora-developers.semtech.com/build/software/lora-basics/lora-basics-for-gateways/|Semtech LoRa Basics™ Station]] is a nice reference implementation. But, as the original packet forwarder, it has the same drawbacks: It's a monolithic approach, designed to be hardly linked to the gateway radio architecture and to be used on one Network Server.

In other words, Kerlink Basic Station Packet Forwarder is the same package for all Kerlink iSeries gateways and can be configured while another previously-configured LNS is still functional.

Main features of reference implementation are implemented in Kerlink Basic Station Packet Forwarder, including:
  * CUPS and LNS protocols support
  * TLS and Token-based Authentication
  * Support for Class A and C on all gateways
  * Support for main radio regions: EU868, US915, AS923, AU915 and IN865

The features **not** supported are listed below:
  * timesync message: A ntpd daemon is embedded in all kerlink gateways and is much more precise than this time synchronization.
  * Remote shell / remote command

The additional features:
  * Packet buffering: Kerlink Basic Station Forwarder embeds a database to store uplink packets in case of LNS/Network disconnections.
  * Multiple LNS connection: Kerlink Basic Station Forwarder can be used in same time than legacy (GWMP) forwarder allowing multiple LNS connections (see [[wiki:lora:multiforwarder]] for further details)



===== Installation and configuration =====

<note>Kerlink Basic Station Packet Forwarder application requires KerOS version 5.x. 

If [[wiki:support:faq#how_to_read_software_version|the software version of your gateway]] is not compatible, refer
to [[wiki:resources:resources|resources section]] to upgrade to 5.x </note>


<note important>For gateways configured with version 4.4.1 for AWS, it's necessary to install [[https://wikikerlink.fr/wirnet-productline/doku.php?id=wiki:firmware:lastversion#download|Liveburner IPK 5.X]] and [[https://wikikerlink.fr/wirnet-productline/doku.php?id=wiki:lora:bspf_ressources#download|Basic Station Packet Forwarder]]. \\
Please see on [[wiki:lora:aws|AWS IoT Core for LoRaWAN - Kerlink documentation]] for more information</note> 

==== Installation ====

  - Download last version of Kerlink Basic Station Packet Forwarder from the [[bspf_ressources|Basic Station resources page]].
  - Install the ''basicstation_X.Y.Z_klkgw.ipk'' file using the instructions of the [[wiki:keros_custo:sw_updates|software updates page]].

The installation of the //"basicstation"// package adds the following content on the file system:
++++Content|
<code bash>
/
├── etc
│   ├── default
│   │   └── station
│   ├── init.d
│   │   └── station
│   ├── logrotate.d
│   │   └── station
│   ├── monit.d
│   │   └── station
│   ├── profile.d
│   │   └── station
│   ├── rcK.d
│   │   └── K52station -> ../init.d/station
│   ├── rcU.d
│   │   └── S51station -> ../init.d/station
│   ├── rsyslog.d
│   │   └── station
│   └── sysupgrade.d
│       └── basic_station.conf
└── user
    └── basic_station
        ├── bin
        │   ├── klk_bs_config
        │   └── station
        ├── etc
        │   └── station.conf.example
        └── lib
            └── python3.10
                └── site-packages
                    ├── basicstation
                    │   └── [...]
                    └── basicstation-X.Y.Z-py3.10.egg-info
                        └── [...]

</code>
++++

==== Configuration ====

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

As explained by [[https://lora-developers.semtech.com/build/software/lora-basics/lora-basics-for-gateways/?url=authmodes.html|Semtech documentation]], the procedure to connect to server may differ depending on authentication mode used by server.

=== No authentication on LNS server ===

  - URI of LNS server should be written in ''/user/basic_station/etc/tc.uri'' config file.
  - Activate basicstation forwarder.

A tool named ''klk_bs_config'' is used to handle these steps.

++++Example:|
With a Chirpstack-based LNS server named ''lns.local''

<code bash>
klk_bs_config --enable --lns-uri "ws://lns.local:3001"
</code>

<note> Please note that "simple" websocket is used in this case. URI MUST start with "ws://" (and not "wss://") </note>
++++

=== 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 Chirpstack-based LNS server named ''lns.local'' with a reference certificate named ''ca_cert''
<code bash>cp ca_cert /user/basic_station/etc/tc.trust
klk_bs_config --enable --lns-uri "wss://lns.local:3001"
</code>

2 - With a CUPS server named ''cups.local'' with a reference certificate named ''ca_cert'':
<code bash>cp ca_cert /user/basic_station/etc/cups.trust
klk_bs_config --enable --cups-uri "https://cups.local"
</code>
++++

=== 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:|
<note>
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.
</note>
  - Push key ''xxx.private.key'' and certificate ''xxx.cert.pem'' on gateway
  - Rename them as cups credentials: <code>cp xxx.private.key /user/basic_station/etc/cups.key
cp xxx.cert.pem /user/basic_station/etc/cups.crt
</code>
  - Activate basicStation forwarder: <code bash> 
klk_bs_config --enable --cups-uri "https://XXX.cups.lorawan.eu-west-1.amazonaws.com"</code>
++++


<note warning>
If the main server needs to be modified, all credentials must be removed first to avoid confusion (like using key and certificate on a non-TLS connection):
<code bash>klk_bs_config --disable
rm -f /user/basic_station/etc/*.key /user/basic_station/etc/*.trust /user/basic_station/etc/*.crt
# Then, follow procedure depending on your LNS type
</code>
</note>


===== Advanced configuration =====

==== Kerlink Basic Station Packet Forwarder 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 ''/user/basic_station/etc/station.conf''.

It allows to:
  * Change log level (for whole application or component by component)
  * Set router EUI
  * Change CUPS request interval
  * Activate packet buffering (database)

An example of this configuration file is provided in ''/user/basic_station/etc/station.conf.example''.


==== Router EUI (for debug/test purpose) ====

Default **Router EUI** is the gateway EUI64 (printed on box and available in ''/tmp/board_info.json'').

However, it can be overridden by setting it in this configuration file:
  - Copy ''/user/basic_station/etc/station.conf.example'' to ''/user/basic_station/etc/station.conf''
  - Edit ''/user/basic_station/etc/station.conf'' and locate ''[router]'' section
  - In this section, enter the line ''id = <WANTED_EUI>''
  - Save file
  - Restart application ''/etc/init.d/station restart''


==== Packet buffering (Beta version) ====

Packet buffering allows to store all uplink packets not correctly transmitted to LNS server.

Application will then retry periodically to re-connect to LNS Server and as soon as the connection is back, all stored packets will be pushed in FIFO mode (First In, First Out) to respect packets chronology.

In order to activate it:
  - Copy ''/user/basic_station/etc/station.conf.example'' to ''/user/basic_station/etc/station.conf''
  - Edit ''/user/basic_station/etc/station.conf'' and locate ''[database]'' section
  - Un-comment ''enable = True'' line
  - Save file
  - Restart application ''/etc/init.d/station restart''
Wirnet™ i-series

User Tools

Site Tools

Page Tools
