• I - File structure - describes file structure of the packet forwarder.

• II - Configuration - describes steps to configure the packet forwarder.

• III - Monitoring and maintenance - describes :
  • how to start / stop the packet forwarder
  • the monitoring tools
  • how to retrieve packet forwarder's informations/log
  • how to uninstall the packet forwarder

• IV - Compilation - describes steps to compile the packet forwarder from sources.

Follow the instructions of the update page to install the packet forwarder. Just replace the “.ipk” file of this example by your own.

The package installation creates several files in the system.
These files are removed when uninstalling the package.

The Packet Forwarder installation package creates common API files at runtime (internal usage) :

This chapter describes how to configure the packet Forwarder through 6 steps.

Location : /user/spf2/etc

The packet forwarder uses two configuration files config.json and local.json. To simplify the configuration, instead of directly using files named this way, two symbolic links are used :

• config.json : Contains the LoRa, the gateway and the GPS parameters.
• local.json : Contains the calibration of the frontend. This file must not be modified, it is hardware dependent.

The way the packet forwarder takes configuration files into account is the following:

1. if there is a config.json parse it, look for the next file
2. if there is a local.json parse it. If some parameters are defined in both config and local configuration files, the local definition overwrites the global config definition.
3. in our case the local.conf is automatically generated at boot time. It contains antenna configuration. Do not change this file.

There are two kinds of configurations files for the iBTS product :

• single_antenna configurations
• dual_antenna configurations

To check wether you have to use single or dual mode, read the chapter 4.6.2.4 of the Installation manual.

Step 1 - Select the correct JSON file.
Step 2 - Execute the following commands :

•     rm config.json
      # <config file> is the chosen JSON in first step
      ln -s <selected_config_file> config.json

Structure of config file.json :

In each configuration file, there are the following arrays :

SX1301 configuration : that should contain the parameters for the Lora concentrator board (RF channels definition, modem parameters, etc).

gateway_configuration : that should contain the gateway parameters (gateway MAC address, IP address of the server, keep-alive time, etc).

gps_configuration

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

Each LoRaLoc module contains two SX1301. Each SX1301 can be configured to use 10 different frequencies. However, these channels needs 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 frequencies.

• chip_rf_chain : define the rf chain used by the SX1301. The front-end 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).

"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": 0,
    "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 }
}],

Step 3 - Update the JSON configuration file with correct parameters for radio frequencies.

To understand all antennas configuration possibilities read the chapter 4.6.2.4 of the Installation manual.

• Enable fields are used to enable or disable emission and reception of the antennas. In case you only have one antenna, disable both these values for one antenna :
  • rx_enable
  • tx_enable

• The following fields are used to calibrate the antennas. These values are overwritten by the local.json. No need to change them.
  • tx_lut
  • rssi_offset
  • rssi_offset_coeff_a
  • rssi_offset_coeff_b

"rf_chain_conf":[
        {
            "rx_enable": true,
            "tx_enable": true,
            "rssi_offset": -202.5,
            "rssi_offset_coeff_a": 20,
            "rssi_offset_coeff_b": 2925,
            "tx_lut":[
                { "rf_power":  2, "fpga_dig_ ...
                 ...
                 ...                            }]
        },{
            "rx_enable": true,
            "tx_enable": true,
            "rssi_offset": -202.5,
            "rssi_offset_coeff_a": 20,
            "rssi_offset_coeff_b": 2925,
            "tx_lut":[
                { "rf_power": ...  
                 ...
                 ...                          }]
        }],

Step 4 - Update the JSON configuration file with correct parameters for antennas.

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 channel is 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

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)

"lbt_conf":{
            "enable": true,
            "rssi_target": -80, /* dBm */
            "rssi_shift": 142,
            "chan_cfg":[ /* 16 channels maximum */
                { "freq_hz": 920600000, "scan_time_us": 5000 },
                { "freq_hz": 920800000, "scan_time_us": 5000 },
                { "freq_hz": 921000000, "scan_time_us": 5000 },
                { "freq_hz": 921200000, "scan_time_us": 5000 },
                { "freq_hz": 921400000, "scan_time_us": 5000 },
                { "freq_hz": 921600000, "scan_time_us": 5000 },
                { "freq_hz": 921800000, "scan_time_us": 5000 },
                { "freq_hz": 923200000, "scan_time_us": 5000 },
                { "freq_hz": 923400000, "scan_time_us": 5000 }
            ]
        },

Step 5 - Update the JSON configuration file with correct parameters for LBT.

• server_address : is the address of the server to which the packets will be forwarded.

• The following fields describe the ports used by the packet forwarder to communicate with the LoRa server
  • serv_port_up
  • serv_port_down

• stat_interval is the period (in second) at which the statistics of the packet forwarder are logged.

• The following fields are Boolean that defines whether invalids packets should be forwarded to the server or not :
  • forward_crc_valid
  • forward_crc_error
  • forward_crc_disabled

• keepalive_interval is the period (in second) at which the packet forwarder will send a PUSH_DATA frame to the server.

• link_mote is a field to observe debug mote's informations.

  "gateway_conf": {
    "gateway_ID": "00AEAEFFFE000000",
    "server_address": "iotbeta.semtech.com",
    "serv_port_up": 1690,
    "serv_port_down": 1690,
    "keepalive_interval": 10,
    "stat_interval": 30,
    "push_timeout_ms": 100,
    "forward_crc_valid": true,
    "forward_crc_error": false,
    "forward_crc_disabled": false,
    "link_mote": "00CC01AF"
  },

Step 6 - Update the JSON configuration file with correct parameters for the gateway.

Send the following shell commands (debug probe or SSH connection) to configure the packet forwareder to work with the Semtech's LoRa Demonstrator LoRaWAN server http://iot.semtech.com:

<config_file> is the JSON file you have already defined to work on your station according to the First step.

sed -r -i -e "s;(\"server_address\":\ ).*$;\1\"iot.semtech.com\",;" /user/spf2/etc/<config_file>
sed -r -i -e "s;(\"serv_port_up\":\ ).*$;\11690,;" /user/spf2/etc/<config_file>
sed -r -i -e "s;(\"serv_port_down\":\ ).*$;\11690,;" /user/spf2/etc/<config_file>

monit restart spf2

The initialisation scripts installed on the gateway will open the firewall ports to allow the packet forwarder to communicate with the Semtech's LoRaWAN server.

Use the Monit process start or stop the packet forwarder.

Monit <start | stop | restart> <service>

• Check whether packet forwarder process is present or not

•  ps ww | grep spf2 

• If packet forwarder is not launched :

• monit start spf2

• If packet forwarder is launched :

• monit stop spf2

• Restart the packet forwarder :

• monit restart spf2

Once your packet forwarder is configured you can check its status using ps command.

 1000 root     13220 S    /usr/bin/monit -c /etc/monitrc
 1009 root      2744 S    {start_getty} /bin/sh /bin/start_getty 115200 ttymxc0
 1010 root      2976 S    -sh
 1012 root      2596 S    /sbin/watchdog -t 30 /dev/watchdog
 1026 root      2740 S    {execute_spf2.sh} /bin/sh -e /user/spf2/bin/execute_spf2.sh
 1028 root     52136 S    /user/spf2/bin/spf2 -g /dev/nmea1 -y
 1029 root      2964 S    logger -p local1.notice -t spf2

For more detailed information with monit you can use these commands :

# monit -v : Gives basic information on the SPF2 process
# ======================================================
monit -v | grep -A 2 spf2
Process Name          = spf2
 Pid file             = /var/run/packet_forwarder.pid
 Monitoring mode      = active
--
 Start program        = '/user/spf2/bin/execute_spf2.sh' timeout 30 s
 Stop program         = '/usr/bin/killall -q spf2' timeout 30 s
 Existence            = if does not exist then restart

# monit status : Gives informations about resources consumption, pid files and monitoring status.
# ===============================================================================================
monit status | grep -A 18 spf2
Process 'spf2'
  status                       Running
  monitoring status            Monitored
  monitoring mode              active
  on reboot                    nostart
  pid                          1028
  parent pid                   1026
  uid                          0
  effective uid                0
  gid                          0
  uptime                       13m
  threads                      7
  children                     0
  cpu                          0.8%
  cpu total                    0.8%
  memory                       0.8% [1.9 MB]
  memory total                 0.8% [1.9 MB]
  data collected               Tue, 04 Jul 2017 07:42:59

Location : /user/spf2/var/log

While deploying packet forwarder on your board, the package installer configures syslogd to manage SPF logs in the /user/spf/var/log directory. This folder will contain activity traces of the packet forwarder. A logrotate feature is used to limit disk space used :

• maximum files : 10.
• maximum size per file : 200Kb.
• most recent file : spf2.log
• less recent file : spf2.log.9

To survey the log files:

tail -f /user/spf2/var/log/spf2.log

Opkg packages (.ipk) can be removed thanks to dedicated procedure: Software updates:package removal.

SPF2 package is an ipk which install SPF2 on the board.
This chapter describes the procedure to compile the packet forwarder and generate the IPK from the source file spf2-4.0.0-klk7.tar.gz, available in the SPF v2 Resource wiki page.
Procedure hereunder is dedicated to Linux operating systems (32 bits and 64 bits). There is no embedded compiler in Wirnet iBTS.

• build-essential
  
• tar
  
• opkg-build (which can be downloaded from https://git.yoctoproject.org/cgit/cgit.cgi/opkg-utils/plain/opkg-build)

Ensure that these tools are in the $PATH.

• spf2-4.0.0-klk7.tar.gz (SPFv2 4.0.0 Resources)
  
• libloragw2-4.0.1-klk3.tar.gz (HALv2 4.0.1 Resources])
  

Set up the environment as describe in the toolchain page.

This build is using 2 sources packages (spf2 and libloragw2). To manage this specifity the pkg-config utility is used. In order to avoid issues, the toolchain sysroot is not used, please modify the toolchain environment file (use your own toolchain directory):

# cat << EOF >> /opt/toolchains/lpbs/environment-setup-cortexa9hf-neon-poky-linux-gnueabi
unset PKG_CONFIG_SYSROOT_DIR
EOF

Source the toolchain environment :

source /opt/toolchains/lpbs/environment-setup-cortexa9hf-neon-poky-linux-gnueabi

It is necessary to build and install the LoRa HAL in order to build the SPF2:

• Extract the sources

Begin by extracting the sources and change directory (libloragw2-4.0.1-klk3.tar.gz from HALv2 4.0.1 Resources page):

# tar xzf libloragw2-4.0.1-klk3.tar.gz
# cd libloragw2-4.0.1-klk3/

• Configure the build:

# ./configure --host=arm-poky-linux-gnueabi --prefix=/tmp/libloragw2
checking for...
...
configure: creating ./config.status
config.status: creating ...
config.status: executing depfiles commands

• Install the library:

 
# make install
...
 /bin/mkdir -p '/tmp/libloragw2/lib'
 /usr/bin/install -c -m 644  libloragw2.a '/tmp/libloragw2/lib'
 ( cd '/tmp/libloragw2/lib' && arm-poky-linux-gnueabi-ranlib libloragw2.a )
 /bin/mkdir -p '/tmp/libloragw2/include'
 /usr/bin/install -c -m 644 libsx1301ar/inc/sx1301ar_hal.h libsx1301ar/inc/sx1301ar_aux.h libsx1301ar/inc/sx1301ar_dsp.h libsx1301ar/inc/sx1301ar_err.h libsx1301ar/inc/sx1301ar_gps.h libsx1301ar/inc/sx1301ar_lbt.h libsx1301ar/inc/sx1301ar_radio.h libsx1301ar/inc/sx1301ar_reg.h i2c_functions/i2c_linuxdev.h spi_functions/spi_linuxdev.h '/tmp/libloragw2/include'
 /bin/mkdir -p '/tmp/libloragw2/lib/pkgconfig'
 /usr/bin/install -c -m 644 libloragw2.pc '/tmp/libloragw2/lib/pkgconfig'

• Extract the sources

Begin by extracting the sources and change directory (spf2-4.0.0-klk7.tar.gz from SPFv2 4.0.0 Resources page):

# tar xzf spf2-4.0.0-klk7.tar.gz
# cd spf2-4.0.0-klk7/

• Export the path:

# export PKG_CONFIG_PATH=/tmp/libloragw2/lib/pkgconfig

• Configure the build:

# ./configure --host=arm-poky-linux-gnueabi --prefix=/user/spf2
checking for...
...
checking for LORAGW2... yes
...
configure: creating ./config.status
config.status: creating ...
config.status: executing depfiles commands

• Create the ipk package:

# make ipk
...rm -rf vi
  GEN      spf2_4.0.0-klk7_4.0.1-klk3_klk_lpbs.ipk