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 configuration files for the Wirnet™ iBTS product :

• single_antenna configuration.
• dual_antenna configuration.

To check whether 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.json file :

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

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 seconds) 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 seconds) at which the packet forwarder will send a PUSH_DATA frame to the server.

• link_mote: Is a field to observe debug mote's information.

  "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 forwarder 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 gateway 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 initialization 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 the packet forwarder is configured its status can be checked 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 these commands can be used :

# 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 the Wirnet™ iBTS, 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.

Fine timestamps are the nanosecond accurate dates at which a packet are received by the gateway. Fine timestamps are generally used for Geolocalization algorithms.

1. An end-device - sends a packet.
2. The Gateway
   • Receives the packet from the end-device.
   • Retrieve the date at which it received the packet thanks to its GPS chip.
   • Splits the date (e.g. 2017-10-23 13:37:45 186ms 118µs 527ns) in two parts :
     • The classic timestamp: contains second-accurate timestamp (e.g. 2017-10-23 13:37:45).
     • The nanosecond number: is the number of nanosecond elapsed since the classic timestamp (e.g. 186118527).
   • Encrypts the nanosecond number with an hardcoded AES key.
3. The Packet Forwarder
   • Retrieves the classic timestamp and the nanosecond number.
   • Sends them to the LNS.
4. The LNS
   • Decrypts the nanosecond number.
   • Sums the nanosecond number with the classic timestamp.

Step 1 - Retrieve the FPGA identifier(s).

• Connect to your Wirnet™ iBTS gateway.
• Type the following command: cat /tmp/sys_startup_status.json | grep “fpga_cid”.
• This will display an output: “fpga_cid”: “0x00F14086286FFF07”,.

Step 2 - Contact Semtech and provide them the fpga_cid of each loraloc module (up to 4 fpga _cid, depending on the product).

The GPS is used by the gateway to retrieve fine timestamps. GPS synchronization (Fix) can be monitored through NMEA frames and especially $GNGGA frames.

command: cat/dev/nmea2
parameters:

• 7th field - GPS fix 0=no fix, 1=fix GPS.
• 8th field - Connected satellites number of connected satellites.

$GNGGA,132911.00,4809.08287,N,00135.18250,W,1,04,4.47,96.1,M,47.7,M,,*69

A GPS fix value equal to 1 is required to use the fine timestamp feature.
If Fix value is not equal to one, the following error will be displayed in the packet forwarder:
ERROR: [BRD0] timestamp is out of range!.

The packet received by the gateway is sent to the LNS in a JSON array as below:

[2017-10-23 15:38:13.439] [1508765865700627] JSON up [1] [CDC6]: 
{"rxpk":
     [{"tmst":64679556,
     "time":"2017-10-23T13:37:45.570488Z",
     "brd":0,
     "aesk":0,
     "freq":868.100000,
     "stat":1,
     "modu":"LORA",
     "datr":"SF12BW125",
     "codr":"4/5",
     "size":30,
     "data":"gFr/ADAAGAIB3Z7VMLH56+YXOwKjMNBjojD0hj3D",
     "rsig":[{
          "ant":1,
          "chan":21,
          "rssic":-112,
          "lsnr":-14.0,
          "etime":"7xkP+6rs/F/Y845JaB5pnQ==",
          "ftime":186118527,
          "ft2d":-323,
          "rfbsb":100,
          "rs2s1":93,
          "rssis":-127,
          "rssisd":0,
          "foff":-2091
          }]
     }]
}

• time: classic timestamp: “time”:2017-10-23T13:37:45.570488Z.
• etime: nanosecond number - encrypted time. “etime”:“7xkP+6rs/F/Y845JaB5pnQ==”.
• ftime: decrypted nanosecond number, this field is used for debug purposes. “ftime”:“186118527”.

The AES Key provided by semtech is used to decypher the etime field.

AES key:

• Algorithm: AES-ECB.
• Key length: 128 Bits.

The timestamp is decyphered by the Application server of the LNS.
Hereunder is an example of script that decrypts the nanosecond number using OpenSSL.

This example is presented as is. It is not written to cover every possible exception. It is up to the user to adapt it to its needs.

The etime field is an hexadecimal value which has been base 64 encoded. There are 32 clock ticks each nanosecond. Therefore, to retrieve the number of nanosecond from the etime value, the value needs to be divided by 32.

etime_dec.sh

#!/bin/bash
 
#checking parameters
if [[ $# -ne 2 ]];then
    echo 'Usage : ./etime_dec.sh <etime value> <AES 128-ecb-key>'
    exit
fi
 
ETIMEFIELD=$1
AESKEY=$2
 
# OpenSSL decyphering (convert from base64 to decimal, decypher, convert from bin to hex, remove trailing '0'
RESULT=$(echo -n $ETIMEFIELD | base64 -d | openssl enc -d -aes-128-ecb -K $AESKEY -nopad | xxd -u -p | sed 's/^0\+/0x/')
 
# Display data
echo "etime decyphered = $RESULT"
echo -n "etime real value = "
printf "%d / 10^9 / 2^5\n" $RESULT | bc -l

The following is an example of decyphering using the script mentionned above. For etime and ftime values refer to the previous JSON message:

• “etime”:“7xkP+6rs/F/Y845JaB5pnQ==”.
• “ftime”:186118527.

chmod u+x etime_dec.sh
dos2unix etime_dec.sh
./etime_dec.sh 7xkP+6rs/F/Y845JaB5pnQ== 5FEAFD3647351BEB423F93CEF14A5DDB
etime decyphered = 0x162FE2FEE
etime real value = .18611852743750000000

Note that etime value and ftime are the same.

In order to check if the application server works properly, its results can be compared to the ftime fields. To activate the ftime field the AES key provided by Semtech must be defined in the packet forwarder configuration:

• location: /usr/spf2/etc/<config.json>.
• field: “aes_key”: “ABCDEF0123456789ABCDEF0123456789” # Default value.

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-5.1.0-klk2.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-5.1.0-klk2.tar.gz (SPFv2 5.1.0 Resources)
  
• libloragw2-5.1.0-klk1.tar.gz (HALv2 5.1.0 Resources])
  

Set up the environment as described 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-5.1.0-klk1.tar.gz from HALv2 5.1.0 Resources page):

# tar xzf libloragw2-5.1.0-klk1.tar.gz
# cd libloragw2-5.1.0-klk1/

• 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-5.1.0-klk2.tar.gz from SPFv2 5.1.0 Resources page):

# tar xzf spf2-5.1.0-klk2.tar.gz
# cd spf2-5.1.0-klk2/

• 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_5.1.0-klk2_5.1.0-klk1_klk_lpbs.ipk