Managing Packet Forwarder

This chapter describes how to configure and manage the LoRaWAN packet forwarder (LRR) based on Thingpark implementation. Note that other 3rd party LoRaWAN packet forwarder may have different file structure. All examples in this section are based on Thingpark.

You can use the packet forwarder upload command to upload any *.ini files to the LXC container /etc/ folder.

LRR package can be copied to flash or usb and installed using packet forwarder command.


Note

LRR ID is the key information required to register a LoRaWAN Gateway on Thingpark Network Manager.

Uploading or Downloading Packet Forwarder

Beginning in privileged EXEC mode, follow these steps to upload or download configuration files to host or USB from LRR.

Procedure

  Command or Action Purpose

Step 1

configure terminal

Enter global configuration mode.

Step 2

packet-forwarder {upload normal <path > | download normal <filename >

Upload or download configuration files to host or USB from LRR.

Step 3

exit

Return to privileged EXEC mode.

Step 4

show packet-forwarder uploads [detail ]

Display details about uploaded files.

Managing Packet Forwarder

Beginning in privileged EXEC mode, follow these steps to manage the packet forwarder.

Procedure

  Command or Action Purpose

Step 1

configure terminal

Enter global configuration mode.

Step 2

packet-forwarder [install | uninstall ] [firmware | pubkey ]

Install or uninstall the packet forwarder. The packet forwarder can be installed from a file in USB drive or in flash.

Step 3

packet-forwarder [start | restart | stop ]

Start, restart, or stop the packet forwarder.

Step 4

exit

Return to privileged EXEC mode.

Step 5

show packet-forwarder [info |status |log [list |name ]]

Show packet forwarder details.

Example

  • The following commands install the LRR package:

    (config)#packet-forwarder install pubkey flash:lrr-opk.pubkey
(config)#packet-forwarder install firmware flash:lrr-1.8.23-ciscoms_noconfig.cpkg

  • The following commands show the packet forwarder information and status:

    #show packet-forwarder info
PublicKeyStatus : Installed
FirmwareStatus : Installed
PacketFwdVersion : 1.8.23
LRRID : 6596c32a
PartnerID : 0001
#
#show packet-forwarder status
Status : Running

  • When the packet-forwarder is shown as “running”, the LRR log files can be displayed IXM through the by using the show packet-forwarder log list command: 

    #show packet-forwarder log list
Log file     Description
======================================
lrr.ini      lrr.ini information
config       Get the detail config
radio        Radio status
trace        LRR Trace log

  • The following command specifies the numbers of log to be displayed.

    #show packet-forwarder log name config 10
11:37:41.696  (3168) sortchan frhz=913900000 index=58
11:37:41.696  (3168) sortchan frhz=914100000 index=59
11:37:41.696  (3168) sortchan frhz=914200000 index=71
11:37:41.696  (3168) sortchan frhz=914300000 index=60
11:37:41.696  (3168) sortchan frhz=914500000 index=61
11:37:41.696  (3168) sortchan frhz=914700000 index=62
11:37:41.696  (3168) sortchan frhz=914900000 index=63
$ROOTACT /tmp/mdm/pktfwd/firmware
ConfigDefault '/tmp/mdm/pktfwd/firmware/lrr/config'
ConfigCustom '/tmp/mdm/pktfwd/firmware/usr/etc/lrr'

  • The following command displays the lrr.ini file.

    #show packet-forwarder log name lrr.ini
port_crypted_k=0
ftpaddr=[58ba93ec55edaf7b8d43c8fb34bc96652abf5db92b0b675a405ad3abf93289d2]
ftpaddr_crypted_k=0
ftpuser=[df09087afa773c3dde7994ee50ab0ad9]
ftpuser_crypted_k=0
ftppass=[ed37881434753d194bbe66a8bc2de5ba]
ftppass_crypted_k=0
ftpport=[2ab6268fa568f91eaa80c4e531aabe80]
ftpport_crypted_k=0
use_sftp=0

Managing Common Packet Forwarder (CPF)

This section describes how to configure and manage the common packet forwarder (CPF) on the Cisco LoRaWAN Gateway.

Understanding Common Packet Forwarder

CPF is an agent running on the host of a LoRa gateway, forwarding RF packets received by the concentrator (uplinks) to a LoRaWAN Network Server (LNS) through secured IP links and transmitting RF packets sent by the LNS (downlinks) through the same secured IP links to some device.

Configuring Common Packet Forwarder

If the LRR packages are installed, CPF cannot be enabled. Uninstall any LRR packages before configuring CPF.

When CPF is enabled, it will perform a GPS check on bootup. This GPS check will use the currently recorded coordinates to verify that the given channel plans are valid in that location. Once a location fix is achieved, the location is stored in non-volatile memory. The location fix status can be viewed using the show gps history command. After this point, GPS is no longer required and the antenna does not need to be connected.


Note

Factory defaulting the IXM deletes this stored location information, in which case, a location fix will need to be achieved again.

Refer to the respective Release Notes for countries supported by the IXM.

Beginning in privileged EXEC mode, follow these steps to configure common packet forwarder on the Cisco LoRaWAN Gateway:

Procedure

  Command or Action Purpose

Step 1

configure terminal

Enter global configuration mode.

Step 2

common-pack-forwarder cert install gw path-to-cert path-to-key

Install IXM gateway's certification and key (mandatory if auth-mode is client-server):

path-to-cert – file path to the gateway’s cert

path-to-key – file path to the gateway’s key

Step 3

common-pack-forwarder cert install srv path-to-cert

Install IXM LNS’ CA certificate (mandatory if auth-mode is other than none):

path-to-cert – file path to the LNS’ CA cert

Step 4

common-pack-forwarder cert erase gw

Erase IXM LoRa gateway's certification and key.

Step 5

common-pack-forwarder cert erase srv

Erase LNS server's certification.

Step 6

common-packet-forwarder profile

Configure parameters for the CPF.

Step 7

ipaddr ip-address port port

Configure network server IP address and port.

ip-address – Network server IP address

port – Network server port number

Step 8

auth-mode mode

Authentication mode.

  • none: use websocket (ws), default

  • client-server: authenticate both client and server with secure websocket (wss)

  • server: server authentication, only

Step 9

gps enable

Enable CPF to utilize GPS signal.

Step 10

aeskey key

Configure AES key used for CPF.

key – AES key used for CPF

Step 11

gatewayid gateway-id

Configure gateway id used for CPF.

gateway-id – Gateway ID used for CPF

Step 12

antenna antenna-number type antenna-type gain antenna-gain loss cable-loss

Configure individual antenna properties.

antenna-number – Antenna ID <1,2>

antenna-type – Antenna type <omni, sector>

antenna-gain – Antenna gain

cable-loss – Cable loss

Step 13

region-cp lora-region-name

Configure LoRa region channel plan code per naming convention defined in LoRa Alliance RP2-1.0.2 (for example: EU868, AU915, AS923-1, AS923-2, AS923-3, IN65, RU864).

lora-region-name – LoRa region code name (optional if default one is used)

Step 14

board-bw bandwidth

bandwidth – Manually setup the board rx bandwidth if you need to change the default.

Note

 

Default board RX channel frequency and bandwidth are 866.5 MHz, 7 MHz for 800 SKU, and 908.6 MHz, 13 MHz for 900 SKU.

You need to manually configure the frequency and bandwidth for regions that use frequencies falling outside of the defaults. AU915, KR920, and AS923-x are the specific channel plans that do not work with the default settings.

Step 15

board-freq freq

freq – Manually setup the board rx frequency if you need to change the default.

Note

 

Default board RX channel frequency and bandwidth are 866.5 MHz, 7 MHz for 800 SKU, and 908.6 MHz, 13 MHz for 900 SKU.

You need to manually configure the frequency and bandwidth for regions that use frequencies falling outside of the defaults. AU915, KR920, and AS923-x are the specific channel plans that do not work with the default settings.

Step 16

tcp-user-timeout timeout

Configure TCP user timeout option:

  • timeout – TCP timeout in seconds.

Step 17

tls-sni enable

enable – Connect to LNS to compare the configured LNS server name with the one embedded in the LNS server's certificate.

Step 18

cpf enable

Start the CPF.

If prompted about a Smart License, answer "yes".

Step 19

exit

Exit the CPF profile block and update the CPF configuration.

Step 20

exit

Return to privileged EXEC mode.

Step 21

show common-packet-forwarder info

(Optional) Show CPF configuration and information.

Step 22

show common-packet-forwarder status

(Optional) Show current state of CPF and if registration with NS was successful.

Step 23

show common-packet-forwarder log list

(Optional) List available log options such as CPF configuration or trace.

Step 24

show common-packet-forwarder log name trace number-of-lines

(Optional) Display the CPF trace log.

number-of-lines – Number of lines in log to display from end of file.

Step 25

show common-packet-forwarder log name config number-of-lines

(Optional) Display the current CPF configuration.

number-of-lines – Number of lines in config to display from end of file.

Step 26

debug cpf

(Optional) Change CPF trace log level to “DEBUG”.

Note

 

The default log level is "WARNING". This command is to change CPF log level to "DEBUG".


Note

  1. Usually the country configuration is not needed and is not used by the gateway. The resident country is determined by the gps location information automatically. It is used only when the LoRa gateway is managed by Cisco IDA agent in privileged mode.

  2. Region-cp is only needed when the resident country supports multiple LoRa region channel plans and a non-default one is used (for example. in US, default channel plan is US915. If AU915 is wanted, set region-cp to AU915).

  3. Class B is supported. Refer to https://doc.sm.tc/station/tcproto.html# for more information about Class B requirements on LoRa Server side (time sync and beacon configurations).

Example

  • Example of Common Packet Forwarder Profile Block:

    common-packet-forwarder profile
 ipaddr A.B.C.D port XXXX
 gps enable
 aeskey 00AEAEFFFE000000
 antenna 1 omni gain 1.5 loss 0.2
 antenna 2 sector gain 1.5 loss 0.2
 gatewayid ::1
 cpf enable
 exit

  • Example of showing Common Packet Forwarder information and status:

    #show common-packet-forwarder info
FirmwareStatus : Installed
FirmwareVersion : 2.1.0.1
Gateway ID : ::1
Region : US915
IPAddress:Port : A.B.C.D:XX
TXLut : <NA,NA,NA,50,32,105,96,88,79,71,63,53,44,35,26,17-NA,NA,NA,48,30,102,93,85,77,69,61,52,43,34,25,16>
GPS : Enabled
AESKey : 00AEAEFFFE000000
Antenna 1 : enabled, type omni, gain 1.5, loss 0.2
Antenna 2 : enabled, type sector, gain 1.5, loss 0.2

#show common-packet-forwarder status
Enabled : Yes
Running : Yes
NS Registration : Successful

    Note

    The Enabled status simply means that CPF has been configured successfully. Running status depicts whether CPF has started successfully or not. Note that GPS signal should be available for the CPF to run correctly.

Guidelines and Limitations of Configuring RX Channel Frequency and Bandwidth

There are some constraints when you configure RX channel frequency and bandwidth on the IXM gateway. The CPF checks if the channel definition is optimal, and returns an error if it is not. It will also check if all the channels defined fit in the sx1301 (the LoRa concentrator chip) band (3 MHz) and in the AD9361 (the main radio board) radio band (4 MHz, 7 MHz, or 13 MHz depending on the region).

The following figure illustrates what is being checked when configuring a channel.

The board RX channel frequency and bandwidth can be configured through the CPF commands board-freq freq and board-bw bandwidth , if the default values do not fit your use case. Default values are 866.5 MHz, 7 MHz for 800 SKU, and 908.6 MHz, 13 MHz for 900 SKU. The sx1301 related configurations come from the LNS.


Note

  • It is not recommended to set a channel frequency to the same as the AD9361 radio center frequency (“board_freq”). It will degrade the sensitivity on this channel.

  • In the figure above, CHAN_IF_MAX is set to 1.5 MHz.

  • It is not recommended to set a channel above or below 1.3 MHz around the chip_center_freq (due to the RX digital filter).

  • There is a flexibility to allow having the sx1301 band partly outside of the radio band, if there is no channel in this “outer” band.

Debugging Common Packet Forwarder

When the CPF is running, the CPR trace log file can be displayed through the IXM by using the show common-packet-forwarder log name trace command: 

#show common-packet-forwarder log list
Log file        Description
========================================
config         CPF Configuration
trace          CPF Trace log


#show common-packet-forwarder log name trace 15
2019-04-16 09:38:40.625 [SYS:INFO] proto EUI   : ::1    (station.conf)
2019-04-16 09:38:40.625 [SYS:INFO] prefix EUI  : ::0    (station.conf)
2019-04-16 09:38:40.625 [SYS:INFO] Station EUI : ::1
2019-04-16 09:38:40.625 [SYS:INFO] Station home: /etc/cpf/      (--home)
2019-04-16 09:38:40.625 [SYS:INFO] Station temp: /var/tmp/      (builtin)
2019-04-16 09:38:40.625 [SYS:WARN] Station in NO-CUPS mode
2019-04-16 09:38:40.825 [TCE:INFO] Starting TC engine
2019-04-16 09:38:40.828 [AIO:ERRO] [4] WS connect failed: NET - The connection to the given server / port failed
2019-04-16 09:38:40.828 [AIO:DEBU] [4] WS connection shutdown...
2019-04-16 09:38:40.828 [TCE:ERRO] TC connect failed - URI: ws://10.156.154.54:6090
2019-04-16 09:38:40.828 [TCE:INFO] INFOS reconnect backoff 0s (retry 0)
2019-04-16 09:38:41.821 [AIO:ERRO] [4] WS connect failed: NET - The connection to the given server / port failed
2019-04-16 09:38:41.821 [AIO:DEBU] [4] WS connection shutdown...
2019-04-16 09:38:41.821 [TCE:ERRO] TC connect failed - URI: ws://10.156.154.54:6090
2019-04-16 09:38:41.821 [TCE:INFO] INFOS reconnect backoff 10s (retry 1)


# show common-packet-forwarder log name config 15
        "log_size":  10000000,
        "log_rotate":  3,
        "gps": "/dev/ttyS1",
        "TX_AIM_GAP":"90ms",
        "pps": "fuzzy"
    },
    "gps_conf": {
        "gw_latitude": 0,
        "gw_longitude": 0,
        "gw_altitude": 0,
        "fixed_altitude": false
    }
}
======================================
station channel plan

The command debug cpf can also be executed to increase the log level of cpf logging.