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 example files:

In each configuration file, there are the following arrays:

SX1301 configuration: It contains the parameters for the Lora concentrator board (RF channels definition, modem parameters, etc).

gateway_configuration: It contains the gateway parameters (IP address of the server, keep-alive time, etc).

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.

Single antenna configuration:

"rf_chain_conf": [
	{
		"rx_enable": true,
		"tx_enable": true,
		"tx_freq_min": 863000000,
		"tx_freq_max": 870000000
	}
],		

Dual antenna configuration:

"rf_chain_conf": [
	{
		"rx_enable": true,
		"tx_enable": true,
		"tx_freq_min": 863000000,
		"tx_freq_max": 870000000
	},
	{
		"rx_enable": true,
		"tx_enable": true,
		"tx_freq_min": 863000000,
		"tx_freq_max": 870000000
	}
],	

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

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

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.

• keepalive_interval: Is the period (in seconds) at which the packet forwarder will send a PUSH_DATA frame to the server.

• stat_interval: Is the period (in seconds) at which the statistics of the packet forwarder are logged.

• push_timeout_ms: Push timeout value.

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

• autoquit_threshold: Enable auto-quit after a number of non-acknowledged PULL_DATA. If the packet forwarder detects X times in a row that it didn't receive feedback from the LNS, it will automatically restart.

"gateway_conf": {
	"server_address": "lns",
	"serv_port_up": 1700,
	"serv_port_down": 1700,
	"keepalive_interval": 10,
	"stat_interval": 30,
	"push_timeout_ms": 100,
	"forward_crc_valid": true,
	"forward_crc_error": false,
	"forward_crc_disabled": false,
	"autoquit_threshold": 3
}

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

From version v5.1.0-klk4_5.1.0-klk5 the gateway ID field has been suppressed from the JSON file. A default gateway ID based on the CPU serial number is automatically generated by the packet forwarder.

It is possible to use another gateway_ID instead of the default gateway_ID. To do this, a gateway_ID (16 hexadecimal digits) field need to be added in the gateway_conf array of the JSON configuration file.

    "gateway_conf": {         
        "gateway_ID": "ABABABABCDCDCDCD",
        "server_address": "52.18.106.103",
        "serv_port_up": 20000,        
        "serv_port_down": 20000,             
        "keepalive_interval": 10,           
        "stat_interval": 30,
        "push_timeout_ms": 100,
        "forward_crc_valid": true,    
        "forward_crc_error": false,   
        "forward_crc_disabled": false,       
        "autoquit_threshold": 3             
    }   

Restart your packet forwarder to apply the modification.

# monit restart spf2 

The default gateway_ID is based on the CPU serial number. To check the gateway ID used you can consult the packet forwarder logs.

Case 1: No gateway_ID defined in the gateway_conf array. The default gateway_ID is used.

# grep "Gateway EUID" /user/spf2/var/log/spf2.log
Jun 13 14:27:22 klk-lpbs-050789 local1.notice spf2: INFO: Using Gateway EUID: 7276FF002E050789
Jun 13 14:28:02 klk-lpbs-050789 local1.notice spf2: I/ Using default Gateway EUID: 7276FF002E050789

Case 2: No gateway_ID defined in the gateway_conf array. The defined gateway_ID is used.

# grep "Gateway EUID" /user/spf2/var/log/spf2.log
Jun 13 14:46:11 klk-lpbs-050789 local1.notice spf2: I/ Using default Gateway EUID: 7276FF002E050789
Jun 13 14:46:11 klk-lpbs-050789 local1.notice spf2: INFO: Using Gateway EUID: ABABABABCDCDCDCD

The first line indicates the default gateway_ID: I/ Using default Gateway EUID: 7276FF002E050789.
The second line indicates the gateway_ID used: INFO: Using Gateway EUID: ABABABABCDCDCDCD.

The configure_spf2 utility is a tool to easily configure the SPF from command line.
It can be used to read or edit the default config.json or another configuration file.

Here is the help of this tool:

# /user/spf2/bin/configure_spf2 --help
Usage: configure_spf2 [OPTION...] JSON_PATH [VALUE]

-f, --file FILE           Read this file instead of the default one.
-v, --verbose             Turn on verbose output.
                          This option can be used multiple times.
    --version             Print version information and exit.
-h, --help                Print this help message and exit.

A use case of this tool is available in the next section.

Send the following shell commands (using a debug probe or an SSH connection) to configure the packet forwarder to work with the European Semtech's LNS. The field values might be outdated, make sure to use the most up-to-date IP/ports.

# /user/spf2/bin/configure_spf2 gateway_conf.server_address 52.18.106.103
# /user/spf2/bin/configure_spf2 gateway_conf.serv_port_up 20000
# /user/spf2/bin/configure_spf2 gateway_conf.serv_port_down 20000

Restart your packet forwarder to apply modifications.

# monit restart spf2 

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 mentioned 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-klk4.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

Please ensure that these tools are in the $PATH.

wget -qO- https://git.yoctoproject.org/cgit/cgit.cgi/opkg-utils/plain/opkg-build | sudo tee /usr/local/bin/opkg-build && sudo chmod 755 /usr/local/bin/opkg-build

• spf2-5.1.0-klk4.tar.gz (SPFv2 5.1.0-klk4 Resources)
  
• libloragw2-5.1.0-klk5.tar.gz (HALv2 5.1.0-klk5 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-klk5.tar.gz from HALv2 5.1.0-klk5 Resources page):

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

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

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

• 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 package
  GEN      ipk/spf2.init
...
  GEN      spf2_5.1.0-klk4_5.1.0-klk5_klk_lpbs.ipk