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 Common Packet forwarder ======

===== What is the Common Packet Forwarder =====

A 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.

In other words, the packet forwarder is the bridge between the LoRa technology and the IP technology. This is the main program of a LoRa gateway, it has to be installed to implement a LoRaWAN network. 

The Common Packet Forwarder (CPF) is an open source packet forwarder developed by Kerlink. It is a set of two daemons (working together) : //"lorad"// and //"lorafwd"//. 

//"lorad"// is responsible for the LoRa hardware. Its main purpose is to provide an abstraction of the LoRa devices to other processes. It initializes the hardware, configures it (channel frequencies, LBT, diversity, ...), and uses it to send/receive LoRa packets or to achieve frequency scans. 

//"lorafwd"// is responsible for the communication to the LNS. It handles the connexion to the server. In case the connexion to the server is lost (for example if there is a network issue), it will automatically try to reconnect to it. To prevent the loss of packets when the LNS cannot be reached, the //"lorafwd"// embeds a database. Once the connexion is back, the packets stored in the database are forwarded to the LNS (by default this feature is disabled). 
//"lorafwd"// uses the [[wiki:GWMP|GWMP protocol]] developed by Semtech over UDP to communicate with the LNS.


===== How to install the Common Packet Forwarder? =====

  - Choose the packet forwarder to install from the [[resources_ibts:resources#common_packet_forwarder|Wirnet iBTS resource page]] or [[resources_ifemto:resources#common_packet_forwarder|Wirnet iFemtoCell resource page]]. Choosing the latest version of the packet forwarder is recommended.
  - Download the //"lorad"// and //"lorafwd"// ''.ipk'' packages files.
  - Install the ''.ipk'' files using the instructions of the [[wiki:sw_updates|software updates page]]. Packages can be installed simultaneously.
//The CPF installation on an iBTS takes some time since the FPGA is updated during this process. Expect approximately 15 to 30 minutes, depending on the number of connected modems. //

The installation of the //"lorad"// and //"lorafwd"// packages adds the following files on the system:

<code bash>
├── etc
│   ├── default
│   │   ├── lorad   # overall lorad configuration
│   │   └── lorafwd # overall lorafwd configuration
│   ├── init.d
│   │   ├── lorad   # script to start/stop lorad
│   │   └── lorafwd # script to start/stop lorafwd
│   ├── monit.d
│   │   ├── lorad   # configuration of the lorad monitoring 
│   │   └── lorafwd # configuration of the lorafwd monitoring
│   ├── rcK.d
│   │   ├── K50lorad
│   │   └── K51lorafwd
│   ├── rcU.d
│   │   ├── S50lorad   # autostart of lorad
│   │   └── S51lorafwd # autostart of lorafwd
│   └── sysupgrade.d
│       ├── lorad.conf 
│       └── lorafwd.conf
└── user
    ├── etc
    │   ├── lorad
    │   │   ├── AS923-JP_16CH.json   # Frequency plan template
    │   │   ├── AU915-AU_16CH.json   # ...
    │   │   ├── EU868-FR_16CH.json   # ...
    │   │   ├── EU868-FR_2x8CH.json  # ...
    │   │   ├── IN865-IN_8CH.json    # ...
    │   │   ├── misc
    │   │   │   └── remote-api.json
    │   │   ├── RU864-RU_16CH.json   # ...
    │   │   ├── US915-US_16CH.json   # ...
    │   │   └── US915-US_64CH.json   # ...
    │   └── lorafwd
    │       └── lorafwd.toml         # LNS configuration
    ├── sbin
    │   ├── lorad                    # lorad binary
    │   ├── lorafwd                  # lorafwd binary 
    │   ├── lorafwdctl               
    │   └── loramodem         # Only for iBTS
    └── share                 
        └── lorad             
            └── fpga_v61.bin  # Only for iBTS
</code>
===== 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 configure the class B beacons.

  * A few frequency plan templates are pre-installed on the gateway (under ''/user/etc/lorad''): choose the one that suits the most your requirement.
  * Edit ''/etc/default/lorad'' and make sure that the ''CONFIGURATION_FILE'' field links to the template you previously chose.
  * Edit the template you chose to adapt it to your needs. Since the hardware of iBTS and iFemtoCell gateways is different, the configuration on each gateway differs (although it is quite similar).

++++ 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 templates contains an object and an array:
  * ''SX1301_array_conf'' is an array that contains the configuration of each LoRa board.\\
  * ''gateway_conf'' is an object that contains the class B configuration.\\

<code>
{
  "SX1301_array_conf": [
      {...}, # LoRa board 1
      {...}, # LoRa board 2
       ...
  ],
  "gateway_conf":{
      ...    # Class B configuration
  }
}
</code>

\\
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 path and RF2 path). 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 [[wiki:lora_features#lora_specific_hardware|]] may help to understand.\\

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

  * ''rx_enable'' is used to enable or disable emission of the antennas. 
  * ''tx_enable'' is used to enable or disable reception 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 initialy 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:__
<code>
"rf_chain_conf": [
  {
    "rx_enable": true,
    "tx_enable": true,
    "antenna_gain": 3,
    "insertion_loss": 0.5,
    "tx_freq_min": 863000000,
    "tx_freq_max": 870000000
  }
],    
</code>

__Dual antenna configuration:__
<code>
"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
  }
],  
</code>

**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 2 Mhz bandwidth.

  * ''chip_enable'' : enable/disable SX1301.
  * ''chip_center_freq'' : is used to define the center frequency of the SX1301. All 10 channels will be around this particular frequency (+/- 1Mhz). 
  * ''chan_rx_freq'' : are used to define each channel frequency.
  * ''chip_rf_chain'' : defines which rf chain is used by the SX1301. See antenna configuration for more details.

<code>
"SX1301_conf":[
 {
    "chip_enable": true,
    "chip_center_freq": 866000000,
    "chip_rf_chain": 0,
    "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_enable": true,
    "chip_center_freq": 868000000,
    "chip_rf_chain": 1,
    "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 }
}],
</code>

\\

**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).
  * ''rssi_shift'':** Do not change this value**, this is the value to be applied to RSSI to convert RSSI in dBm to register value.
  * ''chan_cfg'': 
    * ''freq_hz'': The LBT channel frequency in Hz. These frequencies needs 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).

<code>
"lbt_conf":{
	"enable": true,
	"rssi_target": -80,
	"rssi_shift": 131,
	"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": 128, "transmit_time_ms": 400 },
		{ "freq_hz": 922600000, "scan_time_us": 128, "transmit_time_ms": 400 },
		{ "freq_hz": 922800000, "scan_time_us": 128, "transmit_time_ms": 400 },
		{ "freq_hz": 923000000, "scan_time_us": 128, "transmit_time_ms": 400 },
		{ "freq_hz": 923200000, "scan_time_us": 128, "transmit_time_ms": 400 },
		{ "freq_hz": 923400000, "scan_time_us": 128, "transmit_time_ms": 400 }
	]
},
</code>

++++

++++ iFemtoCell|

The Wirnet iFemtoCell 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 hardware contains an RF front-ends connected to 2 SX1257 chips. A look at the [[wiki:lora_features#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.
  * ''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 tx data on SX1257.

<code>
"lorawan_public": true,
"antenna_gain": 3,
"antenna_gain_desc": "Antenna gain, in dBi",
"insertion_loss": 0,
"insertion_loss_desc": "Insertion loss, in dBi",
"clksrc": 1,
"clksrc_desc": "Radio #1 provides clock to concentrator",
"radio_0": {
	"enable": true,
	"type": "SX1257",
	"freq": 867500000,
	"tx_enable": true,
	"tx_freq_min": 863000000,
	"tx_freq_max": 870000000,
	"tx_notch_freq": 129000
},
"radio_1": {
	"enable": true,
	"type": "SX1257",
	"freq": 868500000,
	"tx_enable": false
},
</code>

**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 channnel frequency (value added to the center frequency). 

<code>
/* 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 },
</code>

**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). More detailed information is available in the [[wirnet-ifemtocell:resources#documentation|Installation and Maintenance Manual]] for the concerned countries.

''enable'': Enable or disable LBT.

''rssi_target'': The RSSI threshold to detect if the channel is busy or not (dBm).

''sx127x_rssi_offset'': Offset RSSI seen by sx1257. Do not modify this field.

''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).


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

++++


==== lorafwd configuration ====

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

  * Edit ''/user/etc/lorafwd''. 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.
    * Hereunder are the keys that must changed to chose your LNS:
      * ''node = "localhost"'': The adress of the LNS.
      * ''#service.uplink = 20000'': The uplink port of the LNS.
      * ''#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 [[wiki:monitoring#monit_daemon||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 FIXME
    * ...
  * DEBUG = ''-vvv'': Displays the hexdump of the packets


==== gateway EUI ====

Gateway EUI are used by LNS to identify from which gateway messages come from. 

By default, EUI are generated this way:

  * Wirnet iBTS : 7276FF002E<last 6 characters of the CPU serial number>
  * Wirnet iFemtoCell : 7276FF00<last 8 characters of the CPU board serial number>

When lorafwd starts, a file containing the default EUI is generated.

<code bash>
cat /var/run/lora/gateway-id.toml 
gateway.id = 0x7276FF002E050789
</code>

If a new EUI has been defined under ''/user/etc/lorafwd'', then, this new EUI is used by lorafwd. Otherwise, the default EUI is used.
Wirnet™ i-series

User Tools

Site Tools

Page Tools
