Common Packet Forwarder configuration
- How to configure and monitor the packet forwarder?

Common Packet Forwarder configuration

Since firmware 4.3.x, CPF is installed in Keros firmware

How to configure and monitor the packet forwarder?

The configuration is achieved in 3 steps:

lorad configuration
lorafwd configuration
monitoring and auto-start configuration

lorad configuration

The goal of the lorad configuration is to define the frequency plan that will be used to receive packets from the end-devices, to enable the LBT feature and to configure the class B beacons.

A few frequency plan templates are pre-installed on the gateway (under /etc/lorad/PLATFORM where PLATFORM equal to ibts, wifc, wiis, fevo, zeth, zcel): it is strongly recommended to copy the expected frequency plan templates in /etc/lorad/lorad.json file. The goal is to keep templates unmodified.
Edit /etc/default/lorad and make sure that the CONFIGURATION_FILE field links to the template you previously copied.
Edit /etc/default/lorad and make sure that DISABLE_LORAD=“no” is present in this file. If lorad is disabled consult the following page to activate the CPF: Keros application configuration - click here.
Edit the template you copied to adapt it to your needs. Since the hardware between gateways is different, the configuration on each gateway differs (although it is quite similar).

Wirnet iBTS

Wirnet iBTS gateways cannot listen to all LoRa frequencies simultaneously. Up to 16 frequencies can be handled at the same time per LoRa board. There can be up to 4 LoRa boards in an iBTS.

Templates structure

Each template contains an object and an array:

SX1301_array_conf is an array that contains the configuration of each LoRa board. 2 objects in this array should be configured to handle 16 channels
gateway_conf is an object that contains the class B configuration.

{
  "SX1301_array_conf": [
      {...}, # RF1 Chain of LoRa board 1
      {...}, # RF2 Chain of LoRa board 1
      {...}, # RF1 Chain of LoRa board 2
       ...
  ],
  "gateway_conf":{
      ...    # Class B configuration
  }
}

There are many configuration fields among the templates, but most of them are by default correctly filled.

Antennas configuration

The front-end board of each LoRa board integrates two duplicated TX and Rx paths (RF1 chain and RF2 chain). Each TX/RX path is connected to one SMB antenna port, referenced as RF1 and RF2 (Installation manual 1.5.4.4 Front-end boards). A look at the lora_specific_hardware may help to understand.

To understand every possible antenna configurations, read chapter 4.6.2.5 of the Installation manual.

rx_enable: Is used to enable or disable reception of the antennas.
tx_enable: Is used to enable or disable emission of the antennas.
antenna_gain: Is used to define the gain of the antenna. This field has to be correctly filled, otherwise, the gateway will use more power to emits packets than what was initially planned by the LNS.
insertion_loss: Is used to define the attenuation due to the cable between the gateway and the antenna.

Single antenna configuration:

"rf_chain_conf": [
  {
    "rx_enable": true,
    "tx_enable": true,
    "antenna_gain": 3,
    "insertion_loss": 0.5,
    "tx_freq_min": 863000000,
    "tx_freq_max": 870000000
  }
],

Dual antenna configuration:

"rf_chain_conf": [
  {
    "rx_enable": true,
    "tx_enable": true,
    "antenna_gain": 3,
    "insertion_loss": 0.5,
    "tx_freq_min": 863000000,
    "tx_freq_max": 870000000
  },
  {
    "rx_enable": true,
    "tx_enable": true,
    "antenna_gain": 3,
    "insertion_loss": 0.5,
    "tx_freq_min": 863000000,
    "tx_freq_max": 870000000
  }
],

Radio Frequencies configurations

Each LoRaLoc module contains two SX1301. Each SX1301 can be configured to use 10 different frequencies. However, these channels need to be contained within a 3 MHz bandwidth.

chip_center_freq: Is used to define the center frequency of the SX1301. All 10 channels will be around this particular frequency (+/- 1.5 MHz).
chan_rx_freq: Are used to define each channel's center frequency. In order to respect SX1301 bandwidth, maximum values are defined by chip_center_freq +/- 1.4 MHz.
chip_rf_chain: Defines which RF chain configuration is used by the SX1301. See antenna configuration for more details.

Single antenna configuration (16 Channels):

"SX1301_conf":[
 {
    "chip_rf_chain": 0,
    "chip_center_freq": 866000000,
    "chan_multiSF_0": { "chan_rx_freq": 865500000, "spread_factor": "7-12" },
    "chan_multiSF_1": { "chan_rx_freq": 865700000, "spread_factor": "7-12" },
    "chan_multiSF_2": { "chan_rx_freq": 865900000, "spread_factor": "7-12" },
    "chan_multiSF_3": { "chan_rx_freq": 866100000, "spread_factor": "7-12" },
    "chan_multiSF_4": { "chan_rx_freq": 866300000, "spread_factor": "7-12" },
    "chan_multiSF_5": { "chan_rx_freq": 866500000, "spread_factor": "7-12" },
    "chan_multiSF_6": { "chan_rx_freq": 867100000, "spread_factor": "7-12" },
    "chan_multiSF_7": { "chan_rx_freq": 867300000, "spread_factor": "7-12" },
    "chan_LoRa_std" : { "chan_rx_freq": 867300000, "bandwidth": 250000, "spread_factor": 7 },
    "chan_FSK"      : { "chan_rx_freq": 866900000, "bandwidth": 125000, "bit_rate": 50000 }
 },
 {
    "chip_rf_chain": 0,
    "chip_center_freq": 868000000,
    "chan_multiSF_0": { "chan_rx_freq": 867500000, "spread_factor": "7-12" },
    "chan_multiSF_1": { "chan_rx_freq": 867700000, "spread_factor": "7-12" },
    "chan_multiSF_2": { "chan_rx_freq": 867900000, "spread_factor": "7-12" },
    "chan_multiSF_3": { "chan_rx_freq": 868100000, "spread_factor": "7-12" },
    "chan_multiSF_4": { "chan_rx_freq": 868300000, "spread_factor": "7-12" },
    "chan_multiSF_5": { "chan_rx_freq": 868500000, "spread_factor": "7-12" },
    "chan_multiSF_6": { "chan_rx_freq": 868700000, "spread_factor": "7-12" },
    "chan_multiSF_7": { "chan_rx_freq": 868900000, "spread_factor": "7-12" },
    "chan_LoRa_std" : { "chan_rx_freq": 868300000, "bandwidth": 250000, "spread_factor": 7 },
    "chan_FSK"      : { "chan_rx_freq": 869100000, "bandwidth": 125000, "bit_rate": 50000 }
 }
],

(cf. /etc/lorad/ibts/EU868-FR_16CH.json on gateway)

Dual antennas configuration (2 x 8 Channels):

"SX1301_conf":[
{
    "chip_rf_chain": 0,
    "chip_center_freq": 868000000,
    "chan_multiSF_0": { "enable": true, "chan_rx_freq": 867100000, "spread_factor": "7-12" },
    "chan_multiSF_1": { "enable": true, "chan_rx_freq": 867300000, "spread_factor": "7-12" },
    "chan_multiSF_2": { "enable": true, "chan_rx_freq": 867500000, "spread_factor": "7-12" },
    "chan_multiSF_3": { "enable": true, "chan_rx_freq": 867700000, "spread_factor": "7-12" },
    "chan_multiSF_4": { "enable": true, "chan_rx_freq": 867900000, "spread_factor": "7-12" },
    "chan_multiSF_5": { "enable": true, "chan_rx_freq": 868100000, "spread_factor": "7-12" },
    "chan_multiSF_6": { "enable": true, "chan_rx_freq": 868300000, "spread_factor": "7-12" },
    "chan_multiSF_7": { "enable": true, "chan_rx_freq": 868500000, "spread_factor": "7-12" },
    "chan_LoRa_std":  { "enable": true, "chan_rx_freq": 868300000, "bandwidth": 250000, "spread_factor": 7 },
    "chan_FSK":       { "enable": true, "chan_rx_freq": 868800000, "bandwidth": 125000, "bit_rate": 50000 }
},
{
    "chip_rf_chain": 1,
    "chip_center_freq": 868000000,
    "chan_multiSF_0": { "enable": true, "chan_rx_freq": 867100000, "spread_factor": "7-12" },
    "chan_multiSF_1": { "enable": true, "chan_rx_freq": 867300000, "spread_factor": "7-12" },
    "chan_multiSF_2": { "enable": true, "chan_rx_freq": 867500000, "spread_factor": "7-12" },
    "chan_multiSF_3": { "enable": true, "chan_rx_freq": 867700000, "spread_factor": "7-12" },
    "chan_multiSF_4": { "enable": true, "chan_rx_freq": 867900000, "spread_factor": "7-12" },
    "chan_multiSF_5": { "enable": true, "chan_rx_freq": 868100000, "spread_factor": "7-12" },
    "chan_multiSF_6": { "enable": true, "chan_rx_freq": 868300000, "spread_factor": "7-12" },
    "chan_multiSF_7": { "enable": true, "chan_rx_freq": 868500000, "spread_factor": "7-12" },
    "chan_LoRa_std":  { "enable": true, "chan_rx_freq": 868300000, "bandwidth": 250000, "spread_factor": 7 },
    "chan_FSK":       { "enable": true, "chan_rx_freq": 868800000, "bandwidth": 125000, "bit_rate": 50000 }
}
],

(cf. /etc/lorad/ibts/EU868-FR_2x8CH.json on gateway).
This configuration may be useful if directive antennas are used for instance.

Listen Before Talk configuration

Listen Before Talk (LBT) is a technique used in radiocommunications whereby a radio transmitter first senses its radio environment before starting a transmission.

This feature is mandatory in a few countries (such as Japan and Korea).

enable: Enable or disable LBT.
rssi_target: The RSSI threshold to detect if channels are busy or not (dBm).
chan_cfg:
- freq_hz: The LBT channel frequency in Hz. These frequencies need to be the same as the one in the SX1301_conf array.
- scan_time_us: The LBT channel scan time to be used (only two available values: 128µs or 5ms).
- transmit_time_ms: Maximum transmission delay allowed (only two available values: 4000ms or 400ms).

"lbt_conf":{
	"enable": true,
	"rssi_target": -80,
	"chan_cfg":[
		{ "freq_hz": 922000000, "scan_time_us": 5000, "transmit_time_ms": 4000 },
		{ "freq_hz": 922200000, "scan_time_us": 5000, "transmit_time_ms": 4000 },
		{ "freq_hz": 922400000, "scan_time_us": 5000, "transmit_time_ms": 400 },
		{ "freq_hz": 922600000, "scan_time_us": 5000, "transmit_time_ms": 400 },
		{ "freq_hz": 922800000, "scan_time_us": 5000, "transmit_time_ms": 400 },
		{ "freq_hz": 923000000, "scan_time_us": 5000, "transmit_time_ms": 400 },
		{ "freq_hz": 923200000, "scan_time_us": 5000, "transmit_time_ms": 400 },
		{ "freq_hz": 923400000, "scan_time_us": 150008, "transmit_time_ms": 400 }
	]
},

Wirnet iFemtoCell, iFemtoCell-evolution and Wirnet iStation

Note that the class-B configuration does not apply to gateways Wirnet iFemtocell and iFemtoCell-evolution since they have no GPS.

The Wirnet iFemtoCell, iFemtoCell-evolution and Wirnet iStation cannot listen to all LoRa frequencies simultaneously. Up to 8 frequencies can be handled at the same time by the demodulator (SX1301).

To understand how the frequency configuration works, it is necessary to know that the Wirnet iFemtoCell, Wirnet iFemtoCell-evolution and Wirnet iStation hardware contain an RF front-ends connected to 2 SX1257 chips. A look at the lora_specific_hardware may help to understand. Each of these chips has a 0.8 MHz Bandwidth. Thus, all 8 channels must be contained within these two 0.8 MHz intervals.

To properly configure the Rx channels, the center frequencies of the chips must be defined.
Once the center frequencies are defined, each channel can be configured.
Here are a few rules/information to configure the frequencies:

Both chips are not necessarily used.
Both chips' bandwidth can overlap.
Channels can overlap.
All 8 frequencies can be contained within one single chip's bandwidth.
Not all 8 frequencies are necessarily used.
Avoid the use of the chip's center frequencies as a channel.

There are many configuration fields among the templates, but most of them are by default correctly filled.

Front-end configuration

antenna_gain: Is used to define the gain of the antenna. If you use the default Kerlink antenna don't change it. This field has to be correctly filled, otherwise, the gateway will use more power to emits packets than what was initially planned by the LNS.
insertion_loss: Is used to define the attenuation due to the cable between the gateway and the antenna. When there is no cable, the correct value is 0.
radio_n
- enable: Enable/disable SX1257.
- freq: Is used to define the center frequency of the SX1257. All channels will be around this particular frequency (+/- 0.4Mhz).
- tx_enable: Enable/disable signal emission capabilities on the SX1257. Only radio_0 must be enabled.

"lorawan_public": true,
"antenna_gain": 3,
"antenna_gain_desc": "Antenna gain, in dBi",
"insertion_loss": 0,
"insertion_loss_desc": "Insertion loss, in dBi",
"radio_0": {
	"enable": true,
	"freq": 867500000,
	"tx_enable": true,
	"tx_freq_min": 863000000,
	"tx_freq_max": 870000000,
},
"radio_1": {
	"enable": true,
	"freq": 868500000,
	"tx_enable": false
},

Radio frequencies configuration

chan_multiSF_X
- enable: Enable/disable the channel.
- radio: Define which frontend (SX1257) is used by the channel (0 or 1 expected).
- if: Intermediate frequency. Value that defines a channel frequency (value added to the center frequency).

/* Lora MAC channels, 125kHz, all SF */
"chan_multiSF_0": { "enable": true, "radio": 0, "if": -400000 },
"chan_multiSF_1": { "enable": true, "radio": 0, "if": -200000 },
"chan_multiSF_2": { "enable": true, "radio": 0, "if": 0 },
"chan_multiSF_3": { "enable": true, "radio": 0, "if": 200000 },
"chan_multiSF_4": { "enable": true, "radio": 0, "if": 400000 },
"chan_multiSF_5": { "enable": true, "radio": 1, "if": -400000 },
"chan_multiSF_6": { "enable": true, "radio": 1, "if": -200000 },
"chan_multiSF_7": { "enable": true, "radio": 1, "if": 0 },

enable: Enable or disable LBT.
rssi_target: The RSSI threshold to detect if the channel is busy or not (dBm).
chan_cfg
- freq_hz: The LBT channel frequency in Hz. These frequencies need to be the same as the one in the chan_multiSF_X JSON arrays.
- scan_time_us: The LBT channel scan time to be used (only two available values: 128µs or 5000µs).

/* Listen Before Talk */
"lbt_cfg": {
        "enable": true,
        "rssi_target": -80,
        "chan_cfg": [
                { "freq_hz": 922000000, "scan_time_us": 5000 },
                { "freq_hz": 922200000, "scan_time_us": 5000 },
                { "freq_hz": 922400000, "scan_time_us": 5000 },
                { "freq_hz": 922600000, "scan_time_us": 5000 },
                { "freq_hz": 922800000, "scan_time_us": 5000 },
                { "freq_hz": 923000000, "scan_time_us": 5000 },
                { "freq_hz": 923200000, "scan_time_us": 5000 },
                { "freq_hz": 923400000, "scan_time_us": 5000 }
        ]
},

Wirnet iZeptoCell

Note that :

the class-B configuration does not apply to gateways Wirnet iZeptoCell since they have no GPS.
the LBT configuration does not apply to gateways Wirnet iZeptoCell since they have no sniffer.

The Wirnet iZeptoCell cannot listen to all LoRa frequencies simultaneously. Up to 8 frequencies can be handled at the same time by the demodulator.

To understand how the frequency configuration works, it is necessary to know that the Wirnet iZeptoCell hardware contains an RF front-ends connected to 2 transceivers chips. A look at the lora_specific_hardware may help to understand. Each of these chips has a 0.8 MHz Bandwidth. Thus, all 8 channels must be contained within these two 0.8 MHz intervals.

To properly configure the Rx channels, the center frequencies of the chips must be defined. Once the center frequencies are defined, each channel can be configured. Here are a few rules/information to configure the frequencies:

Both chips are not necessarily used.
Both chips' bandwidth can overlap.
Channels can overlap.
All 8 frequencies can be contained within one single chip's bandwidth.
Not all 8 frequencies are necessarily used.
Avoid the use of the chip's center frequencies as a channel.

There are many configuration fields among the templates, but most of them are by default correctly filled.

Front-end configuration

antenna_gain: Is used to define the gain of the antenna. Do not modify the default value for Wirnet iZeptoCell.
insertion_loss: Is used to define the attenuation due to the cable between the gateway and the antenna. When there is no cable, the correct value is 0.
radio_n
- enable: Enable/disable transceivers.
- freq: Is used to define the center frequency of the transceivers. All channels will be around this particular frequency (+/- 0.4Mhz).
- tx_enable: Enable/disable signal emission capabilities on the transceivers. Only radio_0 must be enabled.

"lorawan_public": true,
"antenna_gain": 0.0,
"antenna_gain_desc": "Antenna gain, in dBi",
"insertion_loss": 0.0,
"insertion_loss_desc": "Insertion loss, in dB",
"radio_0": {
    "enable": true,
    "freq": 867500000,
    "tx_enable": true,
    "tx_freq_min": 863000000,
    "tx_freq_max": 870000000
},
"radio_1": {
    "enable": true,
    "freq": 868500000,
    "tx_enable": false
},

Radio frequencies configuration

chan_multiSF_X
- enable: Enable/disable the channel.
- radio: Define which transceiver is used by the channel (0 or 1 expected).
- if: Intermediate frequency. Value that defines a channel frequency (value added to the center frequency).

/* Lora MAC channels, 125kHz, all SF */
"chan_multiSF_0": { "enable": true, "radio": 0, "if": -400000 },
"chan_multiSF_1": { "enable": true, "radio": 0, "if": -200000 },
"chan_multiSF_2": { "enable": true, "radio": 0, "if": 0 },
"chan_multiSF_3": { "enable": true, "radio": 0, "if": 200000 },
"chan_multiSF_4": { "enable": true, "radio": 0, "if": 400000 },
"chan_multiSF_5": { "enable": true, "radio": 1, "if": -400000 },
"chan_multiSF_6": { "enable": true, "radio": 1, "if": -200000 },
"chan_multiSF_7": { "enable": true, "radio": 1, "if": 0 },

lorafwd configuration

The goal of the lorafwd configuration is mainly to define to which LNS LoRa packets will be forwarded to.

Edit /etc/default/lorafwd and make sure that DISABLE_LORAFWD=“no” is present in this file. If lorafwd is disabled consult the following page to activate the CPF: Keros application configuration - click here.
Edit /etc/lorafwd.toml. This configuration file is formatted using the TOML v0.5.0 language:
- Most keys are pre-configured with correct values.
- The description of each key is directly written in the configuration file. If this configuration file has been modified, use /etc/lorafwd.toml.example as a model
- Hereunder are the keys that must be changed to chose your LNS:
  - gwmp.node = “localhost”: The address of the LNS.
  - gwmp.service.uplink = 20000: The uplink port of the LNS.
  - gwmp.service.downlink = 20000 : The downlink port of the LNS.

Monitoring and auto-start configuration

By default, both lorad and lorafwd are started at boot time. If for some reason, one of the daemons stops, it will be automatically restarted by monit.

The autostart behavior is handled by the symlinks /etc/rcU.d/S50lorad and /etc/rcU.d/S51lorafwd.
The monitoring behavior is handled by the /etc/monit.d/lorad and /etc/monit.d/lorafwd files.

The daemons can be started/stopped/rebooted and monitored with monit. See monit page for more details.

Both daemons are independent. If one is stopped/restarted, the other one does not need to be stopped/restarted.

Log managment

Both daemons generates logs in the /var/log/lora.log* files.

The verbosity of the daemons can be increased using the EXTRA_ARGS field under /etc/default/lorad and /etc/default/lorafwd.

lorad:

NOTICE = -v: Displays start and stop traces
INFO = -vv:
- Displays the configuration of the hardware (frequencies, bandwidth, spreading factor, antenna, LBT, …)
- Displays the number of uplinks and beacons sent.
- Displays TAI/PPS info
- …
DEBUG = -vvv: Displays the hexdump of the packets

lorafwd:

NOTICE = -v: Displays start and stop traces
INFO = -vv:
- Displays the configuration of the forwarder (gateway ID, LNS, uplink/downlink port, GWMP configuration, …)
- Displays the uplinks and downlink meta-data
- Displays the acknowledge / heartbeat / drop traces
- …
DEBUG = -vvv: Displays the hexdump of the packets