KerOS firmware

i-series gateway firmware

FW 4.3.3

1
1. Overview 8. Embedded Applications

2. How to connect the gateway ? 9. Common Packet Forwarder

3. How to access the gateway ? 10. Troubleshoot the gateway

4. Web Interface 11. How to factory reset ?

5. SMS Commands 12. Network management

6. HTTP REST API 13. Network monitoring

7. How to update a gateway ?

2
Q&A

3
KerOS - Overview
Modifiez le style du titre

KerOS is a Linux-based Operating System

• Used on Kerlink i-series gateways (iFemtoCell, iBTS, iFemtoCell-evolution, iStation)
• Based on an ARM architecture (freescale iMx6 Solox processor)
• Based on open-source applications
• Implements Overlay filesystem

Cross-toolchain, libraries and header provided in order to build customer

applicative software

No SDK available

KerOS is the Kerlink Operating System used on i-series Gateways as iFemtoCell, iBTS,
iFemtoCell-evolution and iStation.
KerOS is a Linux-based Operating System developed by Kerlink working on ARM
architecture (freescale i.MX 6SoloX processor).
Keros is mainly based on open-source applications (Busybox as an example).
There is no SDK available for KerOS. That means that a user cannot rebuild KerOS. But
a cross-toolchain, libraries and header compatible with KerOS are provided in this
wiki allowing the compilation of an application.

4
KerOS - Capabilities
Modifiez le style du titre

Security
Access to gateway
• Secure tunnels : support of IPSEC
• Web interface
and OpenVPN protocols
• SSH
• Trustzone : secure storage of
• File transfer (SFTP/SCP)
keys, certificates…
• Debug Probe
KerOS
Update mechanism Capabilities
• USB autorun
Embedded Application
• Web interface monitoring
• SSH
• File transfer (SFTP/SCP)
• Debug Probe
Radio scanning
Network management
• Ethernet / GSM / Wi-Fi
configuration Recovery mechanism
• Backhaul management and
monitoring

KerOS offers several ways to access the gateway for installation, upgrade,
configuration or logs gathering.
It could be either through a Web interface or using SSH or File transfer (such as
SFTP/SCP). Debug probes can be also used to access the gateway and do
troubleshooting.
At last, USB key can be used for installation, upgrade or logs gathering.

Keros offers a way to manage, configure and monitor the backhaul, either Ethernet,
GSM or Wi-Fi. Wi-Fi is only available on iFemtoCell.

Backup restore and Stock restore operations are available and avoid bricking the
gateway in case of software failure.

KerOS supports IPSEC and OpenVPN protocols in order to manage secure tunnels.

KerOS also manage a trustzone to store keys, certificates, secrets securely.

It offers radio scanning feature.

5
Since version 4.3, KerOS firmware is delivered with Kerlink Common Packet
Forwarder and WMC Embedded applications. These applications are disabled by
default.

5
Filesystem - Overview
Modifiez le style du titre

System partition rootfs mounted using the overlayFS file system

• a read-only filesystem ( /.rootfs.ro) that contains kernel system
libraries and binaries
• a readable and writable ext4 layer filesystem
(/user/.rootfs_upper) that contains system modification files
• Overlay is the union of all the filesystems (RO and R/W) and is
R/W

User partition (/user mountpoint)

• Readable and writable
• Mounted directly in RW in EXT4 filesystem type

Device Mount point Size Format Usage Recommendations

eMMC /.rootfs.ro 45Mb Ext4 (RO) system System binaries/libraries
eMMC /user 6Gb Ext4 (R/W) User Application binaries, data files, System
application config, logs

Since KerOS version 4, both system and user mountpoints are readable and writable.
FW 4.3.3 is based on a linux kernel 4.14.9.
Rootfs is mounted using the overlayFS file system (kernel >= 3.18, 2014). An overlay-
filesystem presents a filesystem which is the result of overlaying one filesystem on
top of the other.
On KerOS, the base layer (lowerdir) is defined by /.rootfs.ro. This base layer is read-
only and backed-up. A second layer (upperdir), that overrides the base layer, is
defined under (/user/.rootfs_upper). This second layer is customizable by the user.
The result of these two layers is a fully customizable rootfs with a full backup
containing all the original files before they are customized by the user.
Applications are recommended to be installed in user partition.

6
How to connect to
the gateway ?

7
How tostyleidentify
Modifiez le du titre a Kerlink gateway ?
Kerlink gateways can be identified either by
• Their Hostname
• klk-lpbs-XXXXXX for iBTS
XXXXXX are the last six hexadecimal digits of the CPU module ID.
If a Wirnet iBTS has 729ATf061ECD as CPU module ID, the hostname will
be: klk-lpbs-061ECD
• klk-wifc-XXXXXX for iFemtoCell
XXXXXX are the last six hexadecimal digits of the Board ID
If a Wirnet iFemtoCell has 704BEc1234AB as board ID, the hostname will be: klk-wifc-1234AB
• klk-wiis-XXXXXX for iStation
XXXXXX are the last six hexadecimal digits of the Board ID
• klk-fevo-XXXXXX for iFemtoCell-Evolution
XXXXXX are the last six hexadecimal digits of the Board ID

• Their IP address

Kerlink gateways can be identified either by their hostname or their IP address.

The hostname is the combination of a prefix which depends on the type of gateway
and 6 digits.
The 6 digits are the last six hexadecimal digits of the CPU module ID for iBTS and the
last six hexadecimal digits of the Board ID for iFemtoCell, iStation and iFemtoCell-
Evolution.
CPU module ID and Board ID can be found on the stickers on the gateways.

8
How tostyleconnect…
Modifiez le du titre Credentials
Credentials used for SSH, SFTP, Debug Probe
• Login : root
Full access to any tools, files and devices.
Can change all passwords.
Default password: pdmk-$serialno
• Last six hexadecimal digits of the CPU module ID for iBTS
CPU module serial number for iBTS: AT0505aE ➔ Default password: pdmk-0505AE
• Last six hexadecimal digits of the Board module ID for iFemtoCell, iStation, iFemtoCell-Evolution
CPU module serial number for iBTS: 704BEc1234AB ➔ Default password: pdmk-1234AB
It is highly recommended to change all default passwords !

• Login : support
Limited access : Read-only access
Default password: fd!15d4gd#

There are several levels of privileges to connect a gateway using SSH, SFTP or Debug
probes.

The root level gives a full access to the gateway. It also allows to change the
password.
The default password is pdmk-$serialno
Serialno corresponds to the last six hexadecimal digits of the CPU module ID for iBTS
and the last six hexadecimal digits of the Board module ID for iFemtoCell, iStation,
iFemtoCell-Evolution

The support level give a limited access to the gateway. It is a read-only access. The
default password is fd!15d4gd#

Note that it is highly recommended to change all default passwords

9
How tostyleconnect…
Modifiez le du titre Credentials

Credentials used for USB

• Login : usbuser
Full access to any tools, files and devices.
Default password: USBklkPassword

Credentials used for Web Interface, SMS command and REST API
• Login : admin
Default password: pwd4admin

It is highly recommended to change all default passwords !

The credentials used by USB is usbuser. It gives a full access to the gateway. The
default password is USBklkPassword

The credentials used for Web Interface, SMS commands and HTTP REST API is admin.
The default password pwd4admin

Obviously, it is highly recommended to also change those default passwords

10
How tostyleconnect…
Modifiez le du titre with local connection
• Available on Wirnet iFemtoCell-Evolution, Wirnet iStation and Wirnet iBTS

• Connect a computer to the Wirnet i-series gateway

• On iBTS, connect a PC to the LOCAL Ethernet port of the Wirnet iBTS with an Ethernet cable
• On iStation or iFemtoCell-Evolution, connect a PC directly to the gateway with a USB cable
(Type-C connector)

• Nominal case
PC obtains an IP address and user can start a SSH client or HTTP connection on gateway IP
192.168.120.1

• Particular case
When using a DHCP server on the computer, the gateway directly obtains an IP address. A
connection can then be done on this IP address

A local connection is available on Wirnet iFemtoCell-Evolution, Wirnet iStation and

Wirnet iBTS. It is therefore possible to directly connect a computer to those gateways.
• On iBTS, the computer is connected to the gateway through the Ethernet port with
an Ethernet cable
• On iStation and iFemtoCell-Evolution, the computer is connected to the gateway
through the Type-C USB connector with a USB cable

Then it is possible to access to the gateway by starting a SSH client on port 22 and
using the gateway default LOCAL IP address which is 192.168.120.1. If a DHCP server
is installed on the computer, the gateway gets an IP address that must be used for the
connection.

11
How tostyleconnect…
Modifiez le du titre with Wi-Fi connection
• Only available on Wirnet iFemtoCell

• A Wi-Fi access point is available at boot time for one hour

• SSID: hostname of the gateway (klk-wifc-XXXXXX)
• Passphrase : the Ethernet MAC address uppercase, without spaces 7076FFYYYYYY

• The Wi-Fi access point can only be used to access the Wirnet iFemtoCell itself

• The Wi-Fi access point does not serve as an Internet wireless access point

On Wirnet iFemtoCell it is possible to connect the gateway through Wi-Fi connection.

At boot time, a Wi-Fi access point is available for one hour.
This Wi-Fi access point can only be used to access the Wirnet iFemtoCell. It is not an
internet wireless access point.

To access the gateway, the hostname is used as SSID. As a reminder, klk-wifc-XXXXXX

where XXXXXX are the last six hexadecimal digits of the Board ID.
The Ethernet MAC address is used as passphrase without any spaces. The Ethernet
MAC address can be found on the Wirnet iFemtoCell sticker.

12
How tostyleconnect…
Modifiez le du titre with a Debug Probe
iStation & iFemtoCell evo
• Plug the Wirnet Debug probe on your gateway Type-C connector from one side and on
USB connector of your computer on the other side

• Once plugged, green equipment led on Debug probe ON (right Led) & Serial port LED on
PC side are ON or blinking
iBTS
• Connect the debug probe (WIRMA2_DEBUG_TOOL) with a standard ethernet cable to
the “DEBUG” port (on CPU module) and with an USB cable to the PC

It is also possible to connect to a gateway with a Debug probe.

On Wirnet iStation and iFemtoCell-Evolution, the debug probe is plugged on the

gateway Type C connector from one side and on a USB connector of the computer on
the other side.
Once plugged, green equipment led on Debug probe ON (Led on the right) & Serial
port LED on PC side are ON or blinking

On Wirnet iBTS, the debug probe is plugged on the gateway Debug port with a
standard ethernet cable from one side and on a USB connector of the computer on
the other side.

13
How tostyleconnect…
Modifiez le du titre with a Debug Probe
• On Windows, download ftdi drivers and install them
• On Linux, everything should work out of the box. The serial port is located in /etc/ttyUSB*
• Open a serial link terminal like Hyperterminal (Windows10) on the com port with the following standard parameters
baudrate : 115200
data length : 8
parity : none
stop bit : 1
flow control : none

Other tools like Teraterm, puTTY, mobaXterm, Zoc may also been used

• Credentials
• root : Full Access
e.g. root / pdmk-$serialno
• support : Read-only access
e.g. support / fd!15d4gd#

On Windows, ftdi drivers should be downloaded and installed. On Linux, everything

should work out of the box. The serial port is located in /etc/ttyUSB*.
To access the gateway, a serial link terminal like Hyperterminal (Windows10) could
be launched. Other tools like Teraterm, puTTY, mobaXterm, Zoc may also been used.
The following parameters must be set :
• baudrate : 115200
• data length : 8
• parity : none
• stop bit : 1
• flow control : none
As a reminder, the credentials to be used are either root for a full access or support
for a read-only access.

14
 How to access the
gateway ?

Once connected to the gateway, there are several ways to access it.

15
How tostyleaccess…
Modifiez le du titre by SSH
• Start an SSH client (typically Putty on
Windows)
• Enter the hostname or IP address of the gateway
• On port 22

• After getting a prompt: enter login/password

• Credentials
• root : Full Access
e.g. root / pdmk-$serialno
• support : Read-only access
e.g. support / fd!15d4gd#

The first way to access the gateway is by using a SSH client, typically Putty on
Windows.
The hostname or IP address of the gateway is used on port 22.

After getting a prompt, a login/password must be entered.

As a reminder, the credentials to be used are either root for a full access or support
for a read-only access.

16
How tostyleaccess…
Modifiez le du titre File transfer (SFTP/SCP)

• Start an SFTP client (typically WinSCP, FileZilla Client on Windows)

• Enter the hostname or IP address of the gateway
• On port 22

• Credentials
• root : Full Access
e.g. root / pdmk-$serialno
• support : Read-only access
e.g. support / fd!15d4gd#

Another way to access the content of the gateway is by using a SFTP client, typically
WinSCP or FileZilla Client on Windows.

The hostname or IP address of the gateway is used on port 22.

As a reminder, the credentials to be used are either root for a full access or support
for a read-only access.

17
How tostyleaccess…
Modifiez le du titre by Web Interface

• Open an internet browser

• Enter IP address or the hostname of the gateway into your browser’s URL bar
Gateway model URL template

Wirnet iFemtoCell http://klk-wifc-XXXXXX/

Wirnet iStation http://klk-wiis-XXXXXX/

Wirnet iFemtoCell-evolution http://klk-fevo-XXXXXX/

Wirnet iBTS http://klk-lpbs-XXXXXX/

• Enter login/password
• Credentials
• Login : admin
• Default password: pwd4admin

The last way to access the gateway is by using the Kerlink Web Interface.
The IP address or the hostname of the gateway must be used into a browser’s URL
bar.

After getting a prompt, a login/password must be entered.

As a reminder, the credentials to be used are admin/pwd4admin.

18
Web Interface

19
Web Interface
Modifiez le style du titre - Functionalities
• Useful to change network configuration or update gateways

Overview tab
• Network Status
Ethernet, Wi-Fi, GSM
• Gateway Information
Hardware serial number and Firmware version
• System Status
CPU, RAM, User disk, Temperature

Administration tab
• Network configuration
• Gateway update
• Reboot/shutdown/factory reset
• Time settings
• Web Interface password management

The kerlink Web Interface is a user-friendly application useful to change network

configuration or update gateways.
It is composed of 2 main tabs, the Overview tab and the administration tab.

The Overview tab displays the network status on Ethernet, GSM and Wi-Fi. It also
gives information on gateway, the Hardware serial number and the Firmware version.
Finally, it also gives System information as CPU, RAM, User disk and Temperature.

The Administration tab allows to configure the backhaul, update the gateway,
reboot, shutdown or factory reset the gateway. It also allows to configure time
settings and change the Web Interface password

20
Web Interface
Modifiez le style du titre – Network configuration
Ethernet
• Enable/disable the Ethernet configuration
• Choose which IPv4 configuration should be set
• DHCP
• Manual: use a static IP
• OFF: turn OFF IPv4 configuration

GSM
• Enable/disable the feature
• Add operators in the list
• Add PIN code
• Save Configuration & Reboot the gateway

Wi-Fi
• Choose Wi-Fi access point in the list
• Click on the access point name and fill the passphrase in the
newly opened window
• The Wi-Fi network appears connected in front of the network name

The network can be easily configured thanks to the web interface.

The Network configuration menu allows to enable or disable the Ethernet
configuration. The user can choose either DHCP configuration or Static IP. It is also
possible to turn off the IPV4 configuration.

The GSM menu allows to enable or disable GSM feature. It is possible to add
operators in the list and configure PIN code. Once the configuration saved, the
gateway must be rebooted.

The Wi-Fi menu allows to enable or disable Wi-Fi feature. It allows to choose a Wi-Fi
access point in the list by clicking on the expected access point. The passphrase must
be entered in the opened window.

21
Web Interface
Modifiez le style du titre – Gateway update
• Drag & drop an ipk file and click on UPDATE GATEWAY

• A reboot is required to finalize the update, click on REBOOT GATEWAY

The update menu allows to easily update the gateway. The user must only drag and
drop the ipk file and click on UP GATEWAY button.
A reboot of the gateway is required to finalize the update. For it, the user must click
on REBOOT GATEWAY button.

22
Web Interface – Gateway configuration
Modifiez le style du titre

• Web Interface password management

• Time settings change (NTP)

• Gateway turn-off

• Gateway reboot

• Gateway factory reset (a gateway

reboot is required to initiate the
factory reset)

The Gateway menu allows to configure it.

It is possible to change the password of the Web Interface.

Time configuration fields allows to change the time settings (NTP) : the address of
NTP servers and the used timezone.

It is also possible to turn off the gateway, reboot it or factory reset it by a simple click
on the interface

23
SMS Commands

24
SMS
Modifiez Commands
le style du titre - Overview
Feature description
• Most features available from the web interface and the HTTP REST API can be
activated/configured over SMS
• System and configuration command list available in the Kerlink Wiki
• Network configuration
• Time configuration
• Gateway management

Examples
[admin:pwd4admin] [reboot] system/reboot
• Reboot command
[reboot:ok]

• Get GSM IP address [admin:pwd4admin] [getgsm] configuration/get_value statm.gsm.address

[getgsm:ok] "10.172.108.48"
• Set admin user password
[admin:pwd4admin] [newpwd] configuration/set_value sysma.password "mynewpassword"
[newpwd:ok]

Wirnet™ i-series gateways can be configured using SMS commands. Most features
available from the web interface and the HTTP REST API can be activated or
configured over SMS. It can allow to manage and configure the network, the time
settings and the gateway.
The list of available commands is given in the Kerlink WIKI.

Note that Sending update, restore stock and restore backup SMS commands will only
set up a flag used to record the request.
The action will only be triggered only after a board reboot. The reboot can be done
manually or by sending a reboot SMS command.

To reboot the gateway, the SMS to be sent is login:password between brackets reboot
between brackets system/reboot.
The answer received is reboot:ok between brackets

25
SMS
Modifiez Commands
le style du titre - Syntax
Command syntax [login:password] [sms_command_id] sms_command sms_field sms_value

• login: The login used for the board configuration. This value is always admin
• password: The password is the same as the web interface password (pwd4admin by default)
• sms_command_id: ID defined by the customer to identify the SMS command. There is no default value. This ID is
mandatory and must be 6 characters long
• sms_command: The command to be executed with / separated fields
• sms_field: The configuration field to be set/get (Optional)
• sms_value: The value that as to be set to a configuration field (Optional)

[sms_command_id:sms_command_status] sms_error_info
Response syntax
• sms_command_id: The value of this field is equal to the value of the sms_command_id field used in the command. The
purpose of this field is to match the command with the response
• sms_command_status: “ok” or “error”
• sms_error_info: SMS error information (Optional)

The syntax of the commands must be respected.

The brackets must be kept.
The login/password is the one corresponding to SMS feature. By default, it is admin
for login and pwd4admin for password.
The sms_command_id is a free ID defined by the user to identify the SMS command.
There is no default value. This ID is mandatory and must be 6 characters long
sms_command, sms_field and sms_value are described in the documentation
available on Kerlink WIKI.

The status of the command execution is transmitted in the SMS received in response.
An error information is also transmitted in case of issue.

26
HTTP REST API

27
HTTP
Modifiez leREST API - Overview
style du titre

Feature description
• KerOS comes with an HTTP REST API used for
• Network configuration
• Time configuration
• Gateway management
• Request and associated responses in KerOS web services documentation

Authentication
• The use of the API is bound to a fresh token
• A login request with both the login and the password is necessary
• The gateway sends back a unique token. This token is valid for 8 hours
• This token must be then used to authenticate each request

KerOS comes with an HTTP REST API. It is used for:

•Network configuration.
•Time configuration.
•Gateway management (reboot, updates, restore…)
The requests and their associated responses are detailed in the KerOS web services
documentation available in the Kerlink WIKI.

The use of the API is bound to a fresh token.

The API version level is requested by the client using the accept HTTP header. Then a
login request with both the login and the password is necessary.
The gateway answers with a unique token which is valid for 8 hours.
This token must be used in each request for authentication.

28
HTTP
Modifiez leREST API - Examples
style du titre

Authentication
curl -s '192.168.4.112/application/administration/login’ \
Request: -X POST \
--data-binary '{"login":"admin","password":"pwd4admin"}' \
| jq .

{
Response: "token_type": "Bearer",
"expiration_date": 1538169670,
"token": "eyJhbGci ------ ghlK1HwrCYlZGADCdH1Q"
}

Ethernet configuration
curl -s '192.168.4.112/application/administration/lan' \
Request: -H 'Authorization: Bearer eyJhbGc4 ---- wrCYlZGADCdH1Q' \
-X GET \
| jq .

{
Response "ipv4_netmask": "",
"ipv4": "dhcp",
"ipv4_dns": "",
"ipv4_address": "",
"enable": true,
"ipv4_gateway": "",
"available": true
}

Here are 2 requests given as an example.

jq is used to prettify the JSON output so that it is readable and indented.

29
How to update a
gateway ?

30
Gateway Update
Modifiez le style du titre - Overview
Packages
• KerOS Distribution supports OPKG packages
• OPKG packages use .ipk extension

Trigger mechanism
• Over Network
• Over USB
• Web interface

KerOS mechanism must always be used

• OPKG package must be used for installation and removal of packages
• Recovery mechanism relies on it
• Gateway customization is kept

KerOS mechanism => use the commands “keros –u”, “keros –s”…

The KerOS Distribution supports OPKG packages. OPKG packages are used to install
customer applications and firmware upgrades. OPKG packages use the .ipk extension.

Update can be done in 3 different ways :

• Over the Network
• Over USB
• Or through the Web interface

KerOS mechanism must always be used for installation, update and removal of
packages since the backup mechanism relies on it.
Updating with KerOS mechanism ensures the user to kept their gateways
customization.

31
Gateway
Modifiez le style duUpdate
titre - Firmware
Packages
• KerOS ipk
• Liveburner ipk

KerOS package
• Does not reset the password
• Does not erase the user partition
• Does not update the stock restore version
• Creates “-opkg” files if a configuration file has been previously modified

Liveburner package
• Erases the whole partition to reinstall the firmware
• Updates stock restore version with FW version of the Liveburner
• Resets the default password on your gateway

2 types of package come into play when updating gateways, the KerOS ipk and the
liveburner ipk.

The KerOS ipk allow to update the gateway in a new FW version. It does not reset the
password, neither the user partition nor the stock restore version.
In case of configuration modification, it creates –opkg files to save the configuration
before the modification.

The liveburner ipk is a specific package that allows to erase the whole partition in
order to reinstall the firmware as if it left the factory.
The liveburner ipk also updates the stock restore version with the FW version of the
applied Liveburner.
Let’s take an example :
• The gateway has been installed with a 4.1 firmware version. Its stock
restore version is 4.1.
• If we upgrade it with a 4.2 KerOS ipk, it does not erase stock restore
version. If there is a factory reset, the firmware will be 4.1
• Now, if the user applies a Liveburner 4.2 to upgrade the gateway in 4.2,
then the stock restore version will be erased and replaced by a 4.2 version.

32
 Then, if there is a factory reset, the firmware will be 4.2.
Note also that the liveburner resets the passwords of the gateway.

KerOS and Liveburner ipk are delivered in Kerlink WIKI, section Resources.

32
Gateway Update
Modifiez le style du titre - Over USB

Create USB 1.1 stick Plug USB stick Check the installation
• Copy the package(s) • Wait for the led blinking • Check the logs of the
installation
keros_xxxx.ipk • Remove the USB stick
• Check the version of the
• Wait for automatic
• Copy the mandatory files installation to complete firmware
(available on the wiki) • Or check the list of the
usb.autorun installed packages
usbkey.txt (contains USB password)

How to check the software versions ?

cat /user/.update # update check
grep "sw" /tmp/sys_startup_status.json # software versions
opkg list-installed # update check
cat /etc/version #FW version

The first way to update the gateway is by USB.

The first step is to copy the update package on the stick and 2 mandatory files
delivered on the WIKI which are usb.autorun and usbkey.txt. Those 2 files are
available in the section Software updates of the wiki. usb.autorun is an auto
executable script. The file usbkey.txt contains the password of the gateway. If you
changed it, you must modify usbkey.txt.

Then, the stick is ready, plug it on the gateway and wait for the led blinking. When
fast blinking, unplug the USB key and wait for the complete installation.

At the end of the update, the user can check the logs, the version of the installed
version and have the list of the installed packages thanks to the commands given as
examples.

33
Gateway Update
Modifiez le style du titre - Over network

Copy the package Trigger the update Check the installation

• Connect over SSH or debug probe • kerosd -u • Check the logs of the
installation
• Copy/download the package in the • reboot
• Check the version of the
/user/.updates/ folder:
firmware
/user/.updates/keros_xxx.ipk
• Or check the list of the
installed packages

How to check the software versions ?

cat /user/.update # update check
grep "sw" /tmp/sys_startup_status.json # software versions
opkg list-installed # update check
cat /etc/version #FW version

The 2nd way to update the gateway is to connect to it directly through the network
either over SSH or debug probe.
The KerOS package must be copied in /user/.updates. Once ready, trigger the update
which will be executed after the next reboot with kerosd –u command.
Reboot the gateway.
Wait for the complete installation.

At the end of the update, the user can check the logs, the version of the installed
version and have the list of the installed packages thanks to the commands given as
examples.

34
Gateway Update
Modifiez le style du titre - Over web interface

Go in the update Menu Trigger the update Check the installation

• Drag and Drop the • Check the logs of the
update ipk file installation
• Click on Upgrade • Check the version of the
• Click on the reboot firmware
button
• Or check the list of the
installed packages

How to check the software versions ?

• Directly in the Web interface
• Overview TAB

The last way to update a gateway is through the web interface.

The user must only drag and drop the ipk file and click on UP GATEWAY button.
A reboot of the gateway is required to finalize the update. For it, the user must click
on REBOOT GATEWAY button.

At the end of the update, the user can check the installed version directly in the web
interface, in the Overview tab, section Information.

35
Gateway Update
Modifiez le style du titre - Package removal
A specific package can be removed with a specific “.ipk” package
• This package is generated with the tool “gen_remove_ipk” provided by Kerlink
• It generates 2 IPK files
• <package name to remove>-remove.ipk
Remove the package from the running configuration
• <package name to remove>-remove-backup.ipk
Remove the package from the running configuration and from the backup

ubuntu1404@KLK344_ubuntu1404_64:~/Desktop/Integration/iBTS/v3.0.0$ tar -xzvf gen_remove_ipk-1.0.0.tar.gz

gen_remove_ipk
ubuntu1404@KLK344_ubuntu1404_64:~/Desktop/Integration/iBTS/v3.0.0$ ls
gen_remove_ipk gen_remove_ipk-1.0.0.tar.gz
ubuntu1404@KLK344_ubuntu1404_64:~/Desktop/Integration/iBTS/v3.0.0$ ./gen_remove_ipk hello
Package hello-remove.ipk created
Package hello-remove-backup.ipk created
ubuntu1404@KLK344_ubuntu1404_64:~/Desktop/Integration/iBTS/v3.0.0$ ls
gen_remove_ipk gen_remove_ipk-1.0.0.tar.gz hello-remove-backup.ipk hello-remove.ipk

The easiest way to remove packages is to use the factory reset feature.
If the user wants to only remove a specific package and not all the packages, 2
specific ipk can be generated by using the tool “gen_remove_ipk” that is provided by
Kerlink on its WIKI.
remove.ipk allows to remove the package from the running configuration.
remove-backup.ipk allows to remove the package from the running configuration
and from the backup.

36
 Embedded
Applications

37
Configuration
Modifiez le style du titre of embedded applications
Since version 4.3, KerOS is delivered with embedded applications
• Kerlink Common Packet forwarder application (CPF)
• WMC embedded applications

How to configure embedded application?

• These applications are disabled by default
• Use klk_apps_config script on the gateway to configure embedded applications
• Reboot the gateway after using klk_apps_config to enable/disable an application
• 4 actions available
--activate-wmc activate WMC embedded apps and CPF
--deactivate-wmc deactivate WMC embedded apps and CPF
--activate-cpf activate lorad and lorafwd
--deactivate-cpf deactivate lorad and lorafwd

Since version 4.3, KerOS is delivered with embedded applications, the Kerlink
Common Packet forwarder application also called CPF and the WMC embedded
applications.
These applications are disabled by default. klk_apps_config script available on the
gateway allows to activate/deactivate embedded applications (WMC and CPF).
The reboot of the gateway is mandatory after to finalize the activation/deactivation.

38
Configuration
Modifiez le style du titre of embedded applications
Which parameters are available in addition to the 4 previous actions ?
• 6 parameters
--lns-server address of the LNS server
--lns-dport LNS downlink port
--lns-uport LNS uplink port
--loradconf path of the lorad configuration file (radio frequencies)
-s WMC server
-p WMC port

Examples
CPF Deactivation
klk_apps_config --deactivate-cpf

CPF Activation with LNS parameters

klk_apps_config --activate-cpf --lns-server router.eu.thethings.network
--lns-dport 1700 --lns-uport 1700 --loradconf /etc/lorad/my_lorad.json

WMC Activation with WMC server parameters

klk_apps_config --activate-wmc -s wmc-poc.wanesy.com –p 1194

6 parameters are available in addition to the 4 actions of activation/deactivation

previously presented.
Those parameters allows to specify the address od an LNS server, define the
downlink and uplink port of the LNS. The user can also define the path of the lorad
configuration file where the radio frequencies are set. At last, it is possible to specify
a new WMC server and its port.

Some commands are given as an example.

39
Embedded application monitoring
Modifiez le style du titre

Monit tool is an open-source supervision tool root@klk-lpbs_0505AE:/ # monit status

Monit uptime: 2h 3m
used to monitor Program 'watchdog'
. . . .
• Daemons process Process 'lorafwd'
status Running
• System resources monitoring status Monitored
monitoring mode active
• Remote hosts on reboot nostart
• Programs pid
parent pid
1171
1
uid 0
effective uid 0
gid 0
Commands uptime 17h 50m

• monit status returns the status of all supervised threads

children
10
0
services cpu 0.9%
cpu total 0.9%
• monit start <name> start the process and the memory 2.5% [5.5 MB]
monitoring memory total
data collected
2.5% [5.5 MB]
Wed, 12 Jun 2019 08:05:13
• monit stop <name> stop the process and the . . . .
System 'klk-lpbs_0505AE‘
monitoring . . . .

root@klk-lpbs_0505AE:/etc/monit.d # monit start lorad

root@klk-lpbs_0505AE:/etc/monit.d # monit stop lorad

Monit is an open-source supervision tool used to monitor daemon process, System

resources, remote host and Program.
The command monit status returns the status of all supervised services.
Monit tool is also used to start or stop the monitoring of specific process. It allow to
start and stop program properly without knowing the start or stop scripts names and
without making a kill if it is not needed.

The example of monit status shows that lorafwd process is running on the gateway.
This process is currently monitored and its process identifier pid is1171.
The uptime of the process is 17 hours and 50 minutes. That can be useful in case of
troubleshooting to check if the software is rebooting.

40
Embedded application monitoring
Modifiez le style du titre

Configuration
• Monit configuration made in the directory /etc/monit.d
• Add in /etc/monit.d small scripts to describe what should be done accordingly to
monit specification
• Example with Common Packet Forwarder (CPF)

root@klk-lpbs-0505AE:/etc/monit.d # cat lorad

CHECK PROCESS lorad PIDFILE /var/run/lora/lorad.pid
start program = "/etc/init.d/lorad start"
stop program = "/etc/init.d/lorad stop"
onreboot nostart

https://mmonit.com/monit/documentation/monit.html
https://mmonit.com/monit/

The monit configuration is made in the folder /etc/monit.d.

Small script must be added to describe what should be done accordingly to monit
specification.

The script corresponding to lorad process is given as an example.

Monit online documentation provides examples and lot of information about how to
make such file.
the monit process name is lorad and it corresponds to the process
lorad.pid
start program is the command used by monit to start the program
stop program is the command used by monit to stop the program
onreboot specify if the the program must be start on reboot or not
If monit detects that the program is not running, it launches it with the start
command.

41
Common Packet Forwarder
- CPF -

42
Common
Modifiez le style duPacket
titre Forwarder - Overview
Bridge between the LoRa technology and the IP technology
• Forwards RF packets received (uplink) to a LNS (LoRaWAN Network Server)
• Transmits RF packets sent by a LNS (downlink) to end-devices
• Transmits beacon signals used by devices to time coordinate with network

Open-source Packet Forwarder developed by Kerlink based on Semtech Packet Forwarder,

composed of 2 processes
• Lorad : LoRa daemon
• Responsible for the LoRa hardware
• Initializes the hardware, configures it (channel frequencies, LBT …) and uses it to send / receive LoRa
packets
• Lorafwd : LoRa forwarder
• Responsible for the communication to the LNS
• Handles the connection to the server

The packet forwarder is a program running on a LoRa gateway. It allows to do the

bridge between LoRa technology and the IP technology.
The packet forwarder forwards the LoRa packets emitted by end-devices and
received by the gateway to a LoRa Network Server (LNS) and vice-versa.
It also transmits beacon signals that is used by devices to time coordinate with
network

The Common Packet Forwarder also called CPF is an open-source packet forwarder
developed by Kerlink based on Semtech Packet Forwarder.
It is a set of two processes “lorad” and “lorafwd”.
“lorad”, also called LoRa daemon 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” also called LoRa forwarder is responsible for the communication to the
LNS. It handles the connection to the server. In case the connection 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 connection is back, the packets stored in

43
the database are forwarded to the LNS. By default, this feature is disabled. LoRa
forwarder implements the GWMP protocol developed by Semtech over UDP to
communicate with the LNS.

43
Common
Modifiez le style duPacket
titre Forwarder - Features
Main features
• Initializes and configures the LoRa Hardware (channel frequencies, LBT, diversity, …)
• Initiates and maintains the connection to the LNS
• Retrieves the RX packets (Uplink) and forward them (both data and meta-data) to the LNS
• Retrieves the TX packets (Downlink) and queue them

Secondary features
• Achieves frequency scans
• Regularly schedules beacons
• Sends statistics to the LNS
• Checks the hardware temperature
• Collects logs
• Supports packet buffering in case of connection to LNS loss

The main features of the CPF are to initializes and configures the LoRa Hardware,
meaning channel frequencies, LBT, diversity…
It Initiates and maintains the connection to the LNS
It retrieves the RX packets (Uplink) and forward them (both data and meta-data) to
the LNS and it retrieves the TX packets (Downlink) and queue them.

The CPF is also in charge of achieving frequency scans. It regularly schedules beacon
used by Class B end-devices Note that Class B is not supported by iFemtoCell
gateways.
The CPF sends statistics to the LNS, it checks the hardware temperature and collects
logs.
The CPF supports packet buffering in case of connection to LNS loss. It allows to be
able retrieve messages even when backhaul connection is lost. 200 messages are
defined by default in the configuration.

44
lorad
Modifiez leconfiguration
style du titre

Goal of lorad configuration

• Define the frequency plan that will be used to receive packets
• Enable the LBT feature
• Configure the class B beacons

How to configure lorad?

• Few frequency plan templates pre-installed on the gateway for different areas under
/etc/lorad/PLATFORM
• Edit /etc/default/lorad and make sure that the CONFIGURATION_FILE field links to the template
• Edit the template to adapt it to your needs

Best practice
• In case of Kerlink templates usage, create a logical link (ln –s) on the configuration file rather than
copying the file (cp)
lrwxrwxrwx 1 root root 18 Apr 9 14:33 lorad.json -> wiis/AS923-JP.json

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 to configure the
class B beacons.
•A few frequency plan templates are pre-installed on the gateway
under /user/etc/lorad/PLATFORM where PLATFORM equal
to ibts, wifc, wiis or fevo. It is strongly recommended to copy the expected
frequency plan templates in /user/etc/lorad/ directory and to create a
symbolic link on this configuration file, the goal being to keep templates
unmodified. This way you know immediately which frequency plan is being
used and you don't have to open the lorad.json file.
•Then, edit /etc/default/lorad and make sure that
the CONFIGURATION_FILE field links to the expected configuration file.
•Finally, edit the configuration file to adapt it to your needs. Since the
hardware between gateways is different, the configuration on each gateway
differs although it is quite similar.

45
lorad
Modifiez leconfiguration
style du titre – Example on iStation
root@klk-wiis-020002:/etc/lorad # ls -l
drwxr-xr-x 2 root root 220 Aug 3 2020 fevo
drwxr-xr-x 2 root root 310 Aug 3 2020 ibts
lrwxrwxrwx 1 root root 18 Apr 9 14:33 lorad.json -> wiis/AS923-JP.json Configuration files in
-rw-r--r-- 1 root root 2505 Mar 29 16:38 lorad.json.bak
drwxr-xr-x 2 root root 220 Aug 3 2020 wifc /etc/lorad
drwxr-xr-x 2 root root 220 Aug 3 2020 wiis
root@klk-wiis-020002:/etc/lorad #

root@klk-wiis-020002:/etc/lorad # ls -l wiis
-rw-r--r-- 1 root root 2505 Aug 3 2020 AS923-JP.json
-rw-r--r-- 1 root root 2006 Aug 3 2020 AS923-TH-SG-HK-TW.json
-rw-r--r-- 1 root root 1902 Aug 3 2020 AU915-AU.json Templates for Wirnet iStation in
-rw-r--r-- 1 root root 2007 Aug 3 2020 EU868-FR.json
-rw-r--r--
-rw-r--r--
1 root
1 root
root
root
1866 Aug
2315 Aug
3
3
2020
2020
IN865-IN.json
KR920-KR.json
/wiis
-rw-r--r-- 1 root root 1970 Aug 3 2020 RU864-RU.json
-rw-r--r-- 1 root root 1970 Aug 3 2020 RU864-RU_Legacy.json root@klk-wiis-040023:/etc/default # cat lorad
-rw-r--r-- 1 root root 1902 Aug 3 2020 US915-US.json # Configuration file for lorad.
root@klk-wiis-020002:/etc/lorad #
#### Common configurations.

# Disable lorad (default value: no)

DISABLE_LORAD=“no"

# The extra arguments.

EXTRA_ARGS="-vv"
Configuration defined in
# The configuration file.
/etc/default/lorad CONFIGURATION_FILE="/etc/lorad/lorad.json"

# The FPGA firmware binary file.

FPGA_FIRMWARE_FILE=" /user/share/lorad/fpga_v61.bin"
root@klk-wiis-040023:/etc/default #

Here is an example of lorad configuration on iStation.

A symbolic link is done on wiis/AS923-JP.json. That means that the configuration
defined in wiis/AS923-JP.json is used.
The configuration defined in /etc/default/lorad shows that it is /etc/lorad/lorad.json
that is used for configuration consequently wiis/AS923-JP.json because of the
symbolic link

46
lorad
Modifiez leconfiguration
style du titre on IBTS

• Choose the AD9361 bandwidth

• For each SX1301
• Assign the antenna/transceiver to be used
• Choose the center frequency (baseband 3.0 MHz)
• Choose the channel frequencies within the basebands
AD9361 Baseband chip
• Choose the spreading factor Antenna Transceiver 1
FPGA
(SX1301)
Antenna Transceiver 2 Baseband chip
• Adapt the antenna gain (SX1301)

• Enable/disable LBT
AD9361 Baseband chip
Antenna Transceiver 1 (SX1301)
Antenna Transceiver 2
FPGA Baseband chip
(SX1301)

There are many configuration fields among the templates, but most of them are by default correctly filled

Wirnet iBTS gateways cannot listen to all LoRa frequencies simultaneously.

Up to 16 frequencies can be handled at the same time per LoRa board and there can
be up to 4 LoRa boards in an iBTS.

Each template 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.

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

• 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).
Possible antenna configurations are described in the Installation manual.

Each LoRaLoc module contains two SX1301.

Each SX1301 can be configured to use 10 different frequencies.

47
However, these channels need to be contained within a 3.0 Mhz bandwidth.

AD9361 has a bandwidth of 4, 7 or 13 MHz specified in the configuration.

The two SX1301 have a bandwidth of 3.0 MHz.
The center frequencies of the two SX1301 must be define in such a way that the 3.0
MHz bandwidth are included in the AD9361 bandwidth.

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

Antenna gain and insertion loss parameters are used to define the gain of the
antenna and cable insertion loss.
This field must be correctly filled, otherwise, the gateway will use more power to
emit packets than what was initially planned by the LNS.

47
lorad
Modifiez leconfiguration
style du titre on other products
• Adapt the antenna gain
• Enable/disable LBT
• For each SX1257
• Enable/disable it
• Choose the center frequency (baseband 0.8 MHz)
• For each channel
• Assign it a SX1257
• Choose the channel frequencies (difference from the center frequency)
• Choose the spreading factor range Transceiver
(SX1257)
Antenna Transceiver
FPGA SX1301
(SX1257)

There are many configuration fields among the templates, but most of them are by default correctly filled

The iStation iFemtoCell and iFemtoCell Evolution 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 gateway hardware contains an RF front-ends connected to 2 SX1257 chips.
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 is 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.

48
Antenna gain and insertion loss parameters are used to define the gain of the
antenna and cable insertion loss.
This field must be correctly filled, otherwise, the gateway will use more power to
emits packets than what was initially planned by the LNS.

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). Japan template
can be used as an example.

48
lorafwd
Modifiez le styleconfiguration
du titre

Goal of lorafwd configuration

• Define which LNS LoRa packets will be forwarded to
• Define the uplink and downlink ports of the LNS

How to configure lorafwd?

• Configuration in /etc/lorafwd.toml since v4.3.3
• Most keys are pre-configured with correct values
• Keys that must be changed to choose your LNS
WMC example
gwmp.node = “localhost”: The address of the LNS
gwmp.node : lns
gwmp.service.uplink = 20000: The uplink port of the LNS gwmp.service.uplink : 1700
gwmp.service.downlink : 1700
gwmp.service.downlink = 20000 : The downlink port of the LNS

• Lorafwdctl tool is available to easily configure the LNS parameters (all products except Wirnet Station)

lorafwdctl example
# lorafwdctl -s gwmp.node ns.eu.iot.semtech.cloud
# lorafwdctl gwmp.service.downlink 20000
# lorafwdctl gwmp.service.uplink 20000

The goal of the lorafwd configuration is mainly to define to which LNS LoRa packets
will be forwarded to.
The ports of LNS for uplink and downlink are also configurable.

The configuration file is under /etc/lorafwd.toml. It is formatted using the TOML

v0.5.0 language.
Most of the keys are pre-configured with the correct values.
The description of each key is directly written in the configuration file.
gwmp.node, gwmp.service.uplink and gwmp.service.downlink are the fields
to be configured.
gwmp.node defines the address of the LNS.
gwmp.service.uplink defines the uplink port of the LNS.
And gwmp.service.downlink defines the The downlink port of the LNS.

Lorafwdctl is a tool provided to easily edit and modify the lorafwd configuration file.
This tool is installed at the same time than the lorafwd. It can be used instead of
editing manually the configuration file.
For example, to configure GWMP node and services, type the command # lorafwdctl -
s gwmp.node ns.eu.iot.semtech.cloud

49
The value to be used to configure the Kerlink WMC are lns for gwmp.node, 1700 for
gwmp.service.uplink and gwmp.service.downlink

49
Packet Buffering
Modifiez le style du titre - Database configuration
• The lorafwd embeds a database (default: 200 messages stored)
• Prevents the loss of packets when the LNS cannot be reached
• Once the connection is back, the packets stored in the database are forwarded to the
LNS
• When the database is full, the newest message replace the oldest one

• By default, the feature is disabled

• Configuration in /etc/lorafwd.toml

• Can be enable with the lorafwdctl tool on KerOS

lorafwdctl database.enable true

To prevent the loss of packets when the LNS cannot be reached, the “lorafwd”
embeds a database. Once the connection is back, the packets stored in the database
are forwarded to the LNS,

By default, the feature is disabled, and 200 messages can be stored. If the limit of 200
message is reached, then the newest message replaces the oldest one.
The parameter to enable/disable this feature in the lorafwd configuration file
/etc/lorafwd.toml. It could easily be enable/disable with lorafwdctl tool using the
command database.enable true

50
Gateway
Modifiez le style duEUI
titre

• Need to be configured in the LNS

• Used by LNS to identify from which gateway messages come from

Wirnet iBTS: 7276FF002E<last 6 characters of the CPU serial number>
Wirnet iFemtoCell: 7276FF00<last 8 characters of the CPU board serial number>
Wirnet iStation: 7076FF00TT<last 6 characters of the CPU board serial number>
where TT=54 for 923MHz, 55 for 915MHz, and 56 for 868MHz
Wirnet iFemtoCell-evolution: 7076FF00TT<last 6 characters of the CPU board serial number>
where TT=64 for 868MHz, 65 for 915MHz, and 66 for 923MHz

• Information available in /var/run/lora/gateway-id.toml file

• When lorafwd starts, a file containing the default EUI is generated, based on information included in
/tmp/board_info.json

root@klk-lpbs-0505AE:~ # cat /var/run/lora/gateway-id.toml

gateway.id = 0x7276FF002E0505AE
root@klk-lpbs-0505AE:~ #

Gateway EUI is used by LNS to identify from which gateway messages come from.
When lorafwd starts, a file containing the default EUI is generated, based on
information included in /tmp/board_info.json

The Gateway EUI information is available in the file gateway-id.toml file under
/var/run/lora/

How obtain the EUI from the serial number of a gateway ?

On Wirnet iBTS, use the prefix 7276FF002E and add the last 6
characters of the CPU serial number
On Wirnet iFemtoCell, use 7276FF00 and add the last 8 characters of
the CPU board serial number
On Wirnet iStation, use 7076FF00, followed by 54 for 923MHz, 55 for
915MHz, and 56 for 868MHz and add the last 6 characters of the CPU
board serial number
On Wirnet iFemtoCell-evolution, use 7076FF00, followed by 64 for
868MHz, 65 for 915MHz, and 66 for 923MHz and add the last 6
characters of the CPU board serial number

51
DEVADDR / NETID filtering - Overview
Modifiez le style du titre

• Allows to forward to LNS, only LoRaWAN packets coming from a given DevAddr
range
• A DevAddr is the ID used by a LoRaWAN device to communicate on a LoRaWAN network
• End-devices have a DevAddr assigned by LNS
• NetID is a part of this DevAddr used by LNS to identify from which gateway messages come from

• Allows to save data consumption

• This feature is available from KerOS firmware 4.3 and above

• See NetID and DevAddr Prefix Assignments for the current list of NetIDs and the
corresponding DevAddr range

The filtering based on DEVADDR or NetID allows to forward to LNS, only LoRaWAN
packets coming from a given DevAddr range. This feature is useful to save data
consumption.

The DevAddr is a logical address used by a LoRaWAN device to communicate on a

LoRaWAN network. It identified the device as an object on the network.
It is the LNS that assigns the DevAddr to the End-device.
The NetID is a part of this DevAddr used by LNS to identify from which gateway
messages come from.

52
DEVADDR / NETID filtering - Configuration
Modifiez le style du titre

Configuration done by a CIDR notation of wanted mask in lorafwd configuration

• Filtering on full Type-0 (/7) Kerlink NetID (12)
lorafwdctl -s filter.lorawan.netid "0x24000000/7"
Once activated, the gateway will only forward packets from devices with DevAddr from 0x24000000 to
0x25FFFFFF

• Filtering on a specific device (/32) with DevAddr E0501234

lorafwdctl -s filter.lorawan.netid "0xE0501234/32"
Once activated, the gateway will only forward packets from the device E0501234

If buffering is used, filtering is done before archiving the message in database

Associated logs can then be observed in /var/log/lora.log* as followed

Drop message from 0x24f52627 (not in NetID range 0xE0501234/32)

The configuration is done by a Classless Inter Domain Routing notation of the wanted
mask in the lorafwd configuration.
An example is given for NetID type 0 and another one for a specific DevAddr.

Note that if the buffering feature is enabled, then the filtering is done before
archiving the message in database.
In case of issue, troubleshooting could be done thanks to the logs stored in
/var/log/lora.log*. The message to be searched id Drop message …

53
 GWMP Protocol
Between Packet Forwarder and LNS

54
GWMP –duGateway
Modifiez le style titre Message Protocol
• Protocol developed by Semtech
• Defines the communication between the packet forwarder and the LNS
• In case the connection to the server LNS is lost (for example if there is a network
issue), it will automatically try to reconnect to it

• Kerlink gateways using CPF can communicate with all LNS that are compatible
with GWMP protocol

• The complete protocol description is available in the wiki

The communication between the packet forwarder and the LNS relies on a protocol
(GWMP) developed by Semtech.
If the connection to the server LNS is lost (for example if there is a network issue), it
automatically tries to reconnect to it.
Kerlink gateways using CPF can communicate with all LNS that are compliant with
GWMP protocol.
A complete protocol description is available in the wiki

55
GWMP –duReceived
Modifiez le style titre Packets example
rxpk messages contain {
"rxpk":[
• The cyphered data {
"aesk":0,
"brd":21,
• The time when the packet was received "codr":"4/5",
"data":"gCQAMgAALR0BciujaEGs38o=",
• RF parameters "datr":"SF8BW125",
"freq":868.1,
• Frequency "jver":2,
"modu":"LORA",
• Data rate "rsig":[
{
• RSSI "ant":0,
"chan":5,
• SNR "lsnr":10.8,
"rssic":-78
• Antenna that received the packet ],
}

"size":17,
"stat":1,
"time":"2019-06-05T14:05:13.195896Z",
"tmst":2238432268
}
]
}

Here is an example of json array used by the protocol implemented by the CPF for
received packets.
rxpk messages contains the cyphered data, the time when the packet was received
and some RF parameters such as frequency, data rate, RSSI, SNR, the antenna number
on which signal has been received.
The array of object for rxpk messages is described in GWMP interface description.

rxpk array of object

rxpk.jver number Version of the JSON rxpk frame format (always 2)
rxpk.time string UTC time of pkt RX, us precision, ISO 8601 'compact' format
rxpk.tmms number GPS time of pkt RX, number of milliseconds since 06 Jan.1980
rxpk.tmst number (32 bits unsigned integer) Internal timestamp of "RX finished"
event
rxpk.freq number (unsigned float) RX central frequency in MHz (Hz precision)
rxpk.brd number (unsigned integer) Radio ID
rxpk.aesk number (unsigned integer) Concentrator board used for RX
rxpk.stat number CRC status: 1 = OK, -1 = fail, 0 = no CRC
rxpk.modu string Modulation identifier "LORA" or "FSK"
rxpk.datr string LoRa datarate identifier (eg. SF12BW500)

56
rxpk.datr number (unsigned integer) FSK datarate (in bits per second)
rxpk.codr string LoRa ECC coding rate identifier
rxpk.size number (unsigned integer) RF packet payload size in bytes
rxpk.data string Base64 encoded RF packet payload, padded
rxpk.delayed boolean true if the message has been delayed due to a buffering
rxpk.rsig array of object Received signal information, per antenna
rxpk.rsig.ant number Antenna number on which signal has been received
rxpk.rsig.chan number (unsigned integer) Concentrator "IF" channel used for RX
rxpk.rsig.rssic number (signed integer) RSSI in dBm of the channel (1 dB precision)
rxpk.rsig.rssis number (signed integer) RSSI in dBm of the signal (1 dB precision)
rxpk.rsig.rssisd number (unsigned integer) Standard deviation of RSSI during preamble
rxpk.rsig.lsnr number (signed float) Lora SNR ratio in dB (0.1 dB precision)
rxpk.rsig.etime string Encrypted 'main' fine timestamp, ns precision [0..999999999]
rxpk.rsig.foff number Frequency offset in Hz [-125 kHz..+125 khz]
rxpk.rsig.ftstat number (8 bits unsigned integer) Fine timestamp status
rxpk.rsig.ftver number Version of the 'main' fine timestamp

56
GWMP –duTransmit
Modifiez le style titre Packets example
txpk messages contain
• The cyphered data {
"txpk":
• RF parameters {
"imme":false,
• Frequency "tmst":2079430044,
"freq":867.7,
• Data rate "rfch":0,
"powe":14,
• RSSI "modu":"LORA",
"datr":"SF8BW125",
• SNR "codr":"4/5",
"ipol":true,
• Antenna that received the packet "size":21,
"ncrc":true,
"data":"YEMlASalEwADVf8AAQIQW77r2MBg"
}
}

Here is an example of json array used by the protocol implemented by the CPF for
transmitted packets.
txpk messages contains the cyphered data, and some RF parameters such as
frequency, data rate, RSSI, SNR, the antenna number on which signal has been
received.
The array of object for txpk messages is described in GWMP interface description.

txpk object
txpk.imme bool
At least one
Send packet immediately (will ignore tmst & tmms)
txpk.tmst number Send packet on a certain timestamp value (will ignore tmms)
txpk.tmms number Send packet at a certain GPS time (GPS synchronization required)
txpk.freq number (unsigned float) TX central frequency in MHz (Hz precision)
txpk.brd number (unsigned integer) 0 Radio ID
txpk.ant number (unsigned integer)
At least one
Concentrator antenna used for TX

57
txpk.rfch number (unsigned integer) Concentrator antenna used for TX
txpk.powe number (unsigned integer) 0 TX output power in dBm (dBm precision)
txpk.modu string Modulation identifier "LORA" or "FSK"
txpk.datr string LoRa datarate identifier (eg. SF12BW500)
txpk.datr number (unsigned integer) FSK datarate (in bits per second)
txpk.codr string LoRa ECC coding rate identifier
txpk.fdev number (unsigned integer) FSK frequency deviation (in Hz)
txpk.ipol bool false Lora modulation polarization inversion
txpk.prea number (unsigned integer) 8 (LoRa)
5 (FSK)
RF preamble size
txpk.size number (unsigned integer) RF packet payload size in bytes
txpk.data string Base64 encoded RF packet payload, padding optional
txpk.ncrc bool false If true, disable the CRC of the physical layer

57
GWMP –duStatistics
Modifiez le style titre Packets example
stat messages contain
• Statistics about the send/received packet
• Statistics about the gateway {
"stat":{
• UTC 'system' time "ackr":0.0,
"boot":"2019-06-05 13:59:29 GMT",
• UTC boot time "dsp":37,
"dwnb":0,
• GPS latitude "fpga":61,
"hal":"5.1.0",
• GPS longitude "lpps":30,
"ping":3000,
• GPS altitude "rxfw":29,
"rxnb":30,
• Temperature "rxok":28,
"temp":58,
• FPGA version "time":"2019-06-05 14:00:59 GMT",
"txnb":0
• …. }
}

Here is an example of json array used by the protocol implemented by the CPF for
statistics packets.
stat messages contains statistics about the send and received packet and statistics
about the gateway such as UTC 'system' time, UTC boot time, GPS latitude, longitude
and altitude, Temperature, FPGA version.

The array of object for stat messages is described in GWMP interface description.

stat object
stat.time string UTC 'system' time of the gateway, ISO 8601 'expanded' format
stat.boot string UTC boot time of the gateway, ISO 8601 'expanded' format
stat.lati number (float) GPS latitude of the gateway in degree (N is +)
stat.long number (float) GPS latitude of the gateway in degree (E is +)
stat.alti number (integer) GPS altitude of the gateway in meter RX
stat.rxnb number (unsigned integer) Number of radio packets received
stat.rxok number Number of radio packets received with a valid PHY CRC
stat.rxfw number (unsigned integer) Number of radio packets forwarded
stat.ackr number Percentage of upstream datagrams that were acknowledged
stat.dwnb number (unsigned integer) Number of downlink datagrams received

58
stat.txnb number (unsigned integer) Number of packets emitted
stat.lpps number (unsigned integer) Number of lost PPS pulses
stat.temp number (signed integer) Temperature of the Gateway
stat.fpga number (unsigned integer) Version of Gateway FPGA
stat.dsp number (unsigned integer) Version of Gateway DSP software
stat.hal string Version of Gateway driver (format X.X.X)
stat.ping number Ping in ms for the last PULL_ACKs

58
Troubleshoot the
gateway

59
System information
Modifiez le style du titre

System Information
• Hardware information of the gateway: /tmp/board_info.json
File generated at boot time
• Gateway calibration values:
• For iBTS /tmp/calib_loraloc.json
• For iFemtoCell, iFemtoCell-evolution and iStation : /tmp/calib_rf.json
File generated at boot time
• GPS frames
• cat /dev/nmea* Allow to determine whether GPS signal is properly received
• cat /dev/gps0 Allow to read NMEA frames. GPS NMEA frames give UTC time

System logs
• System trace logs for SW and HW events and network traces: /var/log/messages
• Packet forwarder logs on LoRa traces: /var/log/lora.log

In case of issue, it is important to know where to find relevant information that can
help.

The hardware information is in the file /tmp/board_info.json. This file is generated at

boot time.

The gateway calibration values are in the file /tmp/calib_loraloc.json for iBTS and
/tmp/calib_rf.json for iFemtoCell, iFemtoCell-evolution and iStation. These files are
also generated at boot time. Note that the calibration values are specific to a
gateway.

About GPS feature, the devices receive NMEA frames every seconds. The command
cat /dev/nmea* allows to determine whether GPS signal is properly received or not
and the command cat /dev/gps0 allows to read NMEA frames. GPS NMEA frames give
UTC time.

Concerning the logs of the gateways, the system traces for SW and HW events and
network are saved under /var/log/messages.
The traces linked to Packet Forwarder can be found under /var/log/lora.log

60
Packet Forwarder
Modifiez le style du titre logs
• Both processes generate logs in the /var/log/lora.log* files
• The verbosity can be increased at 3 levels: notice, info and debug
• Configuration done in files /etc/default/lorad and /etc/default/lorafwd

lorad lorafwd
NOTICE = -v: Displays start and stop traces NOTICE = -v: Displays start and stop traces
INFO = -vv: INFO = -vv:
Displays the configuration of the hardware (frequencies, Displays the configuration of the forwarder (gateway ID,
bandwidth, spreading factor, antenna, LBT, …) LNS, uplink/downlink port, GWMP configuration, …)
Displays the number of uplinks and beacons sent. Displays the uplinks and downlink meta-data
Displays TAI/PPS info Displays the acknowledge / heartbeat / drop traces
… …
DEBUG = -vvv: Displays the hexdump of the packets DEBUG = -vvv: Displays the hexdump of the packets
Jun 5 13:34:48 klk-lpbs-0505AE local1.info lorafwd[1099]: <6> Received uplink message:
Jun 5 13:34:48 klk-lpbs-0505AE local1.info lorafwd[1099]: <6> | lora uplink (48D001DC), payload 37 B, channel 868.5 MHz,
crc ok, bw 125 kHz, sf 7, cr 4/5
Jun 5 13:34:48 klk-lpbs-0505AE local1.info lorafwd[1099]: <6> | Unconfirmed Data Up, DevAddr 2400455F, FCnt 15342, FPort 12
Jun 5 13:34:48 klk-lpbs-0505AE local1.info lorafwd[1099]: <6> | - radio (00000017)
Jun 5 13:34:48 klk-lpbs-0505AE local1.info lorafwd[1099]: <6> | - demodulator counter 413238044, UTC time 2019-06-
05T13:34:48.000639Z, rssi -80 dB, snr 10.5 dB

Both processes lorad and lorafwd generate logs in the /var/log/lora.log* files.
The verbosity can be increased at 3 levels: notice, info and debug

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

61
 Displays the acknowledge / heartbeat / drop traces
…
DEBUG = -vvv: Displays the hexdump of the packets

61
Common
Modifiez le style ducommands
titre

Useful commands
• Display all network interfaces on the gateway: ifconfig -a
• Display available routes on the gateway: route
• Display firewall rules: iptables -L
• Display all processes used: ps

Special commands
• Generates a status of the GSM: gsmdiag.py
• Configures/monitors the network manager: connmanctl
• Lists the installed packages: opkg list-installed
• Displays the status of monitored processes: monit status

The following commands are the basic ones to be known to operate and
troubleshoot Kerlink gateways.
You’ll be able to display all network interfaces on the gateway, display the available
routes on the gateway, display the firewall rules, display all the used processes.
Thanks to those commands, you’ll be able to know which interfaces are available,
which IP address is used, the number of transmitted packets.
The routes determines where the packets are redirected. The firewall rules help to
understand if some ports are filtered, if some data flow are blocked.

In case of issue with GSM backhaul, the command gsmdiag generates a status of the
modem.
Connmanctl is used to configure and monitor the network manager.
opkg list-installed allows to know which versions of packages are installed on the
gateway.
And finally, monit status displays the status of monitored processes. It could be useful
to check that the expected processed such as lorad, lorafwd are running.

62
Logs
Modifiez gathering
le style du titre

• Logs are the entry point to troubleshoot issue on a gateway

• Kerlink provides two simple ways to retrieve the logs

Over Network (from shell) Over USB

1. Use the command get_logs 1. Copy the mandatory files on a pen drive
It generates an archive • usb.autorun*
2. Retrieve this archive on /home/root. The • usbkey.txt*
format of the archive name is It generates an archive on the pen drive
Logs_<type_GW><serial>_<short_MAC>_<date>-<hour>.tar.gz
Ex : Logs_2E0605F5_7b26_20200124-095206.tar.gz * usb.autorun and usbkey.txt are different from the one
used for installation and upgrade. Available in the
WIKI/Automatic log gathering

Logs are the entry point to troubleshoot issue on a gateway.

If a ticket is opened at kerlink support, these logs will be systematically requested.

There are 2 ways to gather the logs, over the network or over USB.
If you are connected to the gateway through a SSH client, use the command get_logs
to generate an archive under /home/root.
The format of the archive name is
Logs_<type_GW><serialnumber>_<short_MACaddress>_<date>-<hour>.tar.gz

If the gateway is physically accessible, you can use a USB stick. You must copy the 2
mandatory files usb.autorun and usbkey.txt that can be found in the Kerlink WIKI in
the log gathering section.
Be careful, the usb.autorun and usbkey.txt are different from the one used for
installation and upgrade. Remember that usbkey.txt contains the password to access
to the gateway via USB. If you changed this password as it is recommended, you must
adapt this file.
The archive is directly created on the USB key.

63
Hardware State
Modifiez le style du titre

/tmp/board_info.json root@klk-lpbs_04018B:/tmp # cat board_info.json

{
• Generated by discovery_script.py "cpu": {
. . . .
• Generated at each reboot "sw_version": "sw_version":
"4.0.2_20180821165420"
• Contains the list of the hardware/modules }

• Contains the characteristics of the hardware "module": [

{
"EEPROM": { . . . . },
"Modem": [
{ . . . . }
],
"position": 1,
. . . .
},
{
"position": 2,
},
]
}

Here is an example of board_info.json that is under /tmp.

This file can’t be modified. It is automatically generated at boot time.

The board_info file contains information about hardware as the list of the modules
and the characteristics of the hardware

64
Example oftitrehardware state
Modifiez le style du

"Modem": [
{ Information about cellular connection
"IMEI": "356853052328061",
"Manufacturer": "Sierra Wire. . .",
"Model": "MC7304",
• Detected SIM Card
"capabilities": "gsm, umts, lte",
"data_attachment": { • APN
"APN": "websfr",
"attached": "true", ... • MCC/MNC
},
"gsm_attachment": {
"MCC": "208",
"MNC": "10", "serial_number": "0x2e0505ae",
"SignalStrength": "40%", "start_time": "08:16:56 2019-06-17",
"status": "registered" "sw_version": "4.0.2_20180821165420"
},
"sim": {
"ICCID": "89331032161985242457",
"IMSI": "208103295864864",
Information about the gateway
"PIN": "disabled or verified",
"status": "present" • Serial number
},

}
... • Boot time
"position": 1,
"type": "wan" • SW version
],

board_info contains information about the cellular connection. It is useful to know

which SIM card is connected, its APN and its MCC/MNC.
It also gives the serial number of the gateway, the software version but also
information such as boot time

65
Bootcause & Bootcount
Modifiez le style du titre

Bootcause
When a gateway is started/restarted, U-Boot displays the boot cause
• Possible reasons of the boot
POR Power On Reset (happens when the gateway is powered or after a power loss)
WDOG Watchdog
SW Software Reset
HW Physical reset (RESET button)
UNKNOWN Not documented cause
• Information provided in the bootcause parameter in the file /proc/cmdline
root@klk-lpbs:~# cat /proc/cmdline
console=ttymxc0,115200 bootmode=nominal bootcause=SW bootcount=5 bootfail=0

Bootcount
• Value counting the number of reboots since the last power cycle
• At each power loss, the counter is reset to 0
• Maximum value of this counter is 65535
• The bootcount value can be checked in the file /tmp/board_info.json
root@klk-lpbs:~# grep /tmp/board_info.json
“bootcount”: 1,

The bootcause and the bootcount are 2 importants parameters to be checked in case
of gateway instability for example.
When a gateway is started or restarted, U-Boot displays the boot cause.
There are 5 possible reasons of the boot.
POR is for Power On Reset. It happens when the gateway is powered or after a power
loss.
WDOG corresponds to a boot caused by a Watchdog.
SW corresponds to a boot caused by a Software Reset.
HW is caused by a physical reset, when the RESET button has been pushed

The bootcause parameter can be read from the file /proc/cmdline

The bootcount value is counting the number of reboots since the last power cycle. At
each power loss, the counter is reset to 0. The maximum value of this counter is
65535.

The bootcount value can be read from /tmp/board_info.json

Bootcount parameter is used to detect instability
• If 16 consecutive reboots are detected due to a watchdog, a “backup

66
 restore” operation is triggered.
• If 32 consecutive reboots are detected due to a watchdog, a “stock restore”
operation is triggered.
The counter is reset if the system is up during at least 10 minutes. This feature cannot
be disabled as it avoids bricking the gateway in case of software failure.

66
How to factory reset
the gateway ?

67
5Modifiez
ways todutrigger
le style titre a factory reset - FAQ on the wiki
A “stock restore” factory reset the gateway and all data are lost
• Via Web Interface

• Via SSH
kerosd -s
reboot

• Via SMS
[login:password] [sms_command_id] system/restore/stock

• Via HTTP REST API

POST /application/administration/restore/ {restoreType}

There are 5 ways to trigger a factory reset. It corresponds to a stock restore factory
reset. That means that all the data are lost !

On the web interface, only click on RESET GATEWAY button available in the gateway
tab.
Using SSH client, the command to trigger a factory reset on a gateway is kerosd –s.
The command reboot is mandatory as the factory reset is applied at the next reboot
of the gateway.
It is also possible to factory reset a gateway with a SMS command or through the
HTTP REST API.

68
5Modifiez
ways todutrigger
le style titre a factory reset - FAQ on the wiki
• Manual action on the gateway (since FW 4.1) : Manual Stock restore on the wiki
• All Wirnet iBTS, iFemtoCell-Evolution and iStation
• Push the ON/OFF button more than 5 seconds to power-off the gateway
• Make sure Power led is off then release button
• Push ON/OFF button to power-up the gateway and maintain it until power and status
leds blink alternatively. The gateway waits 10s for a confirmation
• Release button and push it again to confirm the stock restore operation

• Wirnet iFemtoCell
• Push WPS button and maintain it
• Push Reset button one second. The gateway waits 10s for a confirmation
• Release WPS button and push it again to confirm the stock restore operation

The last way to factory reset a gateway is the manual action directly on the gateway.
The procedure is described on the Kerlink WIKI.

On iBTS, iFemtoCell-Evolution and iStation,

Push the ON/OFF button more than 5 seconds to power-off the gateway
Make sure that the Power led is off then release button
Push the ON/OFF button to power-up the gateway and maintain it until power
and status leds blink alternatively. The gateway waits 10s for a confirmation.
Then Release button and push it again to confirm the stock restore operation

On Wirnet iFemtoCell
Push the WPS button and maintain it
Push Reset button one second, The gateway waits 10s for a confirmation.
Then Release the WPS button and push it again to confirm the stock restore
operation

69
Network management

70
Backhaul
Modifiez le style duconfiguration
titre

• Available interfaces to connect a gateway to a network

• Ethernet
• Cellular
• Wi-Fi (Wirnet iFemtoCell only)

• Network configuration
• Via Web interface
• Via SMS commands
• Via HTTP REST API
• Via Command line

There are different ways to connect a gateway to the network, Ethernet and cellular
on all Kerlink i-series gateways and WiFi only available on iFemtoCell.
The configuration of the network interfaces could be don via the Web Interface, or
with SMS commands or HTTP REST API or directly by using command line. The easiest
way remains the web interface.

71
Network Overview
Modifiez le style du titre

This diagram shows the architecture of the management of network interfaces.

The interfaces are handled by ConnMan, which is a daemon for managing Internet
connections within embedded devices.
ConnMan provides a way to :
- auto connect interfaces,
- to prioritize interfaces (route management),
- and to configure fallback interfaces.
ConnMan is not used to monitor the network.

Cellular protocol is handled by oFono. The use of oFono is almost entirely handled by
ConnMan. Ethernet is directly handled by ConnMan.

Kerlink provides two scripts to monitor the network. Only one can be used at the
same time.
- networkmonitoring.py: This script is self-sufficient. It is used to monitor/repair the
default route (it regularly pings an IP)
- fixnetwork.py: This script is designed to be called by a customer application. It is
used to repair multiple interfaces at the same time.

72
Cellular
Modifiez le styleconfiguration
du titre - oFono
oFono daemon used to configure the modem at startup or to reconfigure the modem

oFono configuration done via the editable configuration file

/etc/network/ofono/provisioning
• Used to define APN, PIN code and cellular context
• Different APN and authentication information can be given for each operator
• A list of Mobile Network Code / Mobile Country Code can be found on mcc-mnc.com
• In case of Roaming
• Configure the MCC/MNC codes of the SIM provider and not those of the local operator
• Configure the APN of the SIM provider and not the one of the local operator
• A ofono reset is needed each time the provisioning file is modified
/etc/init.d/ofono reset

Cellular protocol is handled by oFono.

The oFono configuration is done via the editable configuration file
/etc/network/ofono/provisioning.
APN, PIN code and cellular context can be configured.
Different APN and authentication information can be given for each
operator
Be careful, in case of roaming, configure the MCC/MNC codes and the
APN of the SIM provider and not those of the local operator

Note that each time the provisioning file is modified you must reset oFono otherwise
the modification are not taken into account.

73
Cellular
Modifiez le styleConfiguration
du titre – Provisioning file example

# Syntax: #[sim]
#[operator:MCC,MNC] #pin=XXXX => default SIM PIN
#internet.AccessPointName=APN => only mandatory field #phone=XXXX => default PH-SIM PIN
#internet.Username=myUsername #firstphone=XXXX => default PH-FSIM PIN
#internet.Password=myPassword #network=XXXX => default PH-NET PIN
#internet.AuthenticationMethod=[chap, pap] => default is chap #netsub=XXXX => default PH-NETSUB PIN
#internet.Protocol=[ip, ipv6, dual] => default is ip #service=XXX => default PH-SP PIN
#corp=XXXX => default PH-CORP PIN
#[sim:ICCID]
#pin=XXXX => SIM PIN of SIM identified by ICCID # Orange
#phone=XXXX => PH-SIM PIN of SIM identified by ICCID [operator:208,01]
#firstphone=XXXX => PH-FSIM PIN of SIM identified by ICCID internet.AccessPointName=orange.m2m.spec
#network=XXXX => PH-NET PIN of SIM identified by ICCID
#netsub=XXXX => PH-NETSUB PIN of SIM identified by ICCID # SFR
#service=XXX => PH-SP PIN of SIM identified by ICCID [operator:208,10]
#corp=XXXX => PH-CORP PIN of SIM identified by ICCID internet.AccessPointName=websfr

Here is an example of provisioning file with the different fields that can be defined.
MCC = mobile country code
MNC = mobile network code
APN
User name and password if any
SIM PIN
At the bottom right, there are 2 concrete examples with Orange operator, APN
orange.m2m.spec and SFR, APN websfr.

74
GSM
Modifiez leDiagnostic
style du titre Tool : gsmdiag.py
• Script using oFono interfaces to
• Detect most common problems on cellular modems
• Have a quick view of cellular modems status on board
• Generate a text file /tmp/gsmdiag.txt
root@klk-lpbs-0505AE:~ # gsmdiag.py [NetworkRegistrationProps]
Number of modems: 1 Status:registered
[Modem:/sierra_0] MobileCountryCode:208
Powered:1 MobileNetworkCode:10
Online:1 Name:SFR
Manufacturer:Sierra Wireless, Incorporated Strength:40
Model:MC7304 [ConnectionContexts]
Revision:SWI9X15C_05.05.58.00 r27038 carmd- [/sierra_0/context1]
fwbuild1 2015/03/04 21:30:23 Name:Internet
[SimProps] Active:1
Present:1 Type:internet
CardIdentifier:89331032152780379453 Protocol:ip
SubscriberIdentity:208103292732049 AccessPointName:websfr
LockedPins:dbus.Array([], Username:
signature=dbus.Signature('s'), variant_level=1) Password:
PinRequired:none AuthenticationMethod:chap

In case of issue with GSM backhaul, the command gsmdiag generates a status of the
modem.
It allows to detect the most common issues on cellular modem and have a quick view
of cellular modems status on the board.
The script gsmdiag generate a text file gsmdiag.txt under /tmp

75
Internet
Modifiez le style connections
du titre management - ConnMan
ConnMan is a daemon for managing Internet connections
• Provides a way to auto connect interfaces
• Prioritize interfaces (route management)
• Configure fallback interfaces

ConnMan is not used to monitor the network : ConnMan does not react if the network
fails

ConnMan configuration done via the editable configuration files

/etc/network/connman/main.conf, /etc/network/connman/lan.config and
/etc/network/connman/wlan.config

ConnMan automatically detects configuration changes and applies them when the
configuration file is closed

ConnMan is a daemon for managing Internet connections. It provides a way to auto

connect interfaces, prioritize interfaces and configure fallback interfaces.
Ethernet and Wi-Fi are configured through ConnMan.

Be careful, ConnMan is not used to monitor the network : ConnMan does not react if
the network fails.
If the interface is physically connected to the gateway, but there is a server error
when the gateway try to access the LNS, ConnMan do nothing because ConnMan
does only check that the interface is available but does not try to ping an IP address
to determine whether the interface is working or not.
For example, if an Ethernet cable is connected between the gateway and a switch,
and the switch is not connected to the network, the fallback interface will not be
used.
Monitoring of the connection must be done to solve such cases.

ConnMan configuration is done via the 3 editable configuration files main.conf,

lan.config and wlan.config located under /etc/network/connman.

Note that ConnMan automatically detects configuration changes and applies them

76
when the configuration file is closed. There is no need to restart ConnMan.

76
ConnMan Configuration
Modifiez le style du titre

main configuration : main.conf

• list of preferred technologies
• list of auto connectable technologies

Ethernet configuration : lan.config

• Not created by default
• Not needed in case of DHCP configuration
• Example of configuration file is provided in /etc/network/connman/lan.config.example
• lan.config can be created or lan.config.example can be renamed in lan.config and modified

Wi-Fi configuration : wlan.config

• Not created by default
• Example of configuration file is provided in /etc/network/connman/wlan.config.example
• wlan.config can be created or wlan.config.example can be renamed in wlan.config and modified

Main.conf is the main files to configure ConnMan. The list of preferred technologies
and the list of auto connectable technologies are defined in it.

lan.config is the configuration file for Ethernet. It is not created by default and this
file is not needed in case of DCHP configuration.
An example of ethernet configuration is available in the file lan.config.example under
/etc/network/connman/.
If needed, the configuration file lan.config can be created or lan.config.example can
be renamed in lan.config and modified.

wlan.config is the configuration file for Wi-Fi. It is not created by default.

An example of Wi-Fi configuration is available in the file wlan.config.example under
/etc/network/connman/.
If needed, the configuration file wlan.config can be created or wlan.config.example
can be renamed in wlan.config and modified.

77
ConnMan – main.conf example
Modifiez le style du titre

# List of blacklisted network interfaces

NetworkInterfaceBlacklist = vmnet,vboxnet,virbr,ifb,eth1,wlan-adm

# List of preferred technologies

PreferredTechnologies = ethernet, wifi, cellular

# List of technologies that are marked autoconnectable

DefaultAutoConnectTechnologies = ethernet, wifi, cellular

# Enable use of http get as on online status check.

EnableOnlineCheck = true

# When checking if a service is online, force connman to check for

# specific headers in HTTP response.
OnlineCheckUseConnmanHeaders = true

# URL used to check if a service is online

# OnlineCheckServerIpV4Url = http://ipv4.connman.net/online/status.html

# Enable auto connection of services in roaming.

AutoConnectRoamingServices = true

Here is an example of the configuration file main.conf.

In this example, the technologies that are marked autoconnectable ethernet, wifi and
cellular.
DefaultAutoConnectTechnologies = ethernet, wifi, cellular
The order of preference for network interfaces is ethernet then wifi then cellular
PreferredTechnologies = ethernet, wifi, cellular
That means that by default, ConnMan will auto-connect to Ethernet, Wifi and cellular
and prioritizes Ethernet over Wifi over cellular.

Removing a technology from these parameters does not mean that this technology
will not be used. It means that this technology will be used last. To force a technology
to be unused, you must define it in the configuration file with the parameter
NetworkInterfaceBlacklist.

The routing table is managed by ConnMan.

To define what should be the default route, in addition to the preferred technologies
and the auto connected technologies mechanism, ConnMan tries to connect to an
HTTP server when the interface is mounted. If successful, service is declared as
Online, if not, it is declared Ready.

78
By default, ConnMan tries to reach the server “ipv4.connman.net”. Since the gateway
is used to send/receive LoRa packets to an LNS, checking the default server is not
optimal. For example, the LNS could be in a local network, or “ipv4.connman.net”
could be down. In that cases, the check would be negative whereas the LNS is
reachable. For this reasons, it is strongly advised to configure ConnMan to check the
LNS instead of “ipv4.connman.net”.

When checking if a service is online, the OnlineCheckUseConnmanHeaders

parameter forces ConnMan to check for specific headers in HTTP response. If this
setting is false, a 200 status is enough to say that service is ONLINE. When using your
own server, set OnlineCheckUseConnmanHeaders to false, otherwise ConnMan
specific headers will be tested.
When using the OnlineCheckUseConnmanHeaders parameter, before configuring the
URL in ConnMan, it is strongly advised to check the response of this URL.

78
ConnMan - Ethernet configuration example
Modifiez le style du titre

DHCP root@klk-lpbs-0505AE:/ # cat

/etc/network/connman/lan.config.example
[global]
Name = LAN
Description = LAN Interface configuration
[service_LAN]
Type = ethernet
IPv4 = dhcp

Static IP
root@klk-lpbs-0505AE:/ # cat
/etc/network/connman/lan.config.example
[global]
Name = LAN
Description = LAN Interface configuration
IPv4 = network/netmask/gateway
[service_LAN] & Nameservers for DNS resolution
Type = ethernet
IPv4 = 192.168.1.5/255.255.255.0/192.168.1.1
Nameservers = 192.0.2.1,192.0.2.2

Here are example of Ethernet configuration. The first one is for DCHP configuration.
In this case, type is ethernet and IPv4 is dhcp.
The second example concerns Static IP configuration. In this case, Type is ethernet,
IPv4 is network/netmask/gateway and Nameservers is defined for DNS resolution.

79
ConnMan - Wi-Fi Configuration example
Modifiez le style du titre

BASICS root@klk-lpbs-0505AE:/ # cat

/etc/network/connman/wlan.config.example
• Name: SSID of the Wi-Fi network [global]
• Passphrase: password of the Wi-Fi network Name = WLAN
Description = WLAN Interface configuration
[service_WLAN]
Type = wifi
DCHP IPv4 = dhcp
• DHCP: IPv4 = dhcp #Name = ssidname
#Passphrase = passphrase

root@klk-lpbs-0505AE:/ # cat
IP STATIC /etc/network/connman/wlan.config.example
• Static: IPv4 = network/netmask/gateway [global]
Name = WLAN
Description = WLAN Interface configuration
[service_WLAN]
Type = wifi
IPv4 = 192.168.1.5/255.255.255.0/192.168.1.1
#Name = ssidname
#Passphrase = passphrase

Here are example of WIFI configuration.

The first one is for DCHP configuration. In this case, type is wifi and IPv4 is dhcp.
The second example concerns Static IP configuration. In this case, Type is wifi, IPv4 is
network/netmask/gateway.
In all cases, SSID of the wifi network and the passphrase must be defined in name and
Passphrase.

80
ConnMan - Useful commands
Modifiez le style du titre

Connmanctl tool
• To properly restart ConnMan
root@klk-lpbs-0505AE:~ # /etc/init.d/connman restart

• Connmanctl services : O for Online, R for Ready

root@klk-lpbs_0505AE:~ # connmanctl services
*AO Wired ethernet_7076ff010a20_cable
*AR SFR cellular_208103292732049_context1

• Connmanctl connect : Force ConnMan to connect a service

root@klk-lpbs_0505AE:/ # connmanctl connect cellular_208103292732049_context1
Connected cellular_208103292732049_context1

• Connmanctl disconnect : Force ConnMan to disconnect a service

root@klk-lpbs_0505AE:/ # connmanctl disconnect cellular_208103292732049_context1
Disconnected cellular_208103292732049_context1

Connmanctl is a tool used to configure and monitor the network manager

The most common and useful commands are :
restart to properly restart ConnMan
services to know the available interfaces and their status. O is for
Online and R for Ready
connect allows to force ConnMan to connect a service
disconnect allows to force ConnMan to disconnect a service

81
ConnMan - Useful commands
Modifiez le style du titre

Connmanctl tool
• Connmanctl technologies : Lists the technologies available on the gateway

root@klk-lpbs_0505AE:/ # connmanctl technologies

/net/connman/technology/cellular
Name = Cellular
Type = cellular
Powered = True
Connected = False
Tethering = False
/net/connman/technology/ethernet
Name = Wired
Type = ethernet
Powered = True
Connected = True
Tethering = False

The command technologies gives the lists the technologies available on the gateway.
In the example, 2 technologies are available, the cellular and Ethernet and ethernet is
the connected interface.

82
Network monitoring

83
Network Monitoring
Modifiez le style du titre - Overview
• ConnMan alone is not enough to monitor a network : Kerlink provides two scripts to monitor
or restart network interfaces
• networkmonitoring.py
• Self-sufficient
• Used to monitor/repair the default route
• Based on regular check of a server access
• The customer application uses the default route
• Only the default route is monitored by the script

• fixnetwork.py (advanced use)

• Designed to be called by a customer application
• Used to repair multiple interfaces at the same time
• The customer application chooses which interface is used for each transmission

• Only one of the 2 scripts can be used at the same time

As seen in the ConnMan section, ConnMan is used to manage the network, not to
monitor it. That’s why Kerlink provides two scripts to monitor or restart network
interfaces.
The script are disabled by default.
Only one of the 2 scripts can be used at the same time

The networkmonitoring script is self-sufficient. It is used to monitor and repair the

default route if needed. It checks the access of a server on regular basis. The
customer application uses the default route and only the default route is
monitored by the script.

The fixnetwork script is for an advanced use because customers need to build a
specific application for KerOS as it is designed to be called by a customer application.
A compilation is needed. It is used to repair multiple interfaces at the same time. The
customer application chooses which interface is used for each transmission.

84
Networkmonitoring.py
Modifiez le style du titre principles
• Monitors the network and takes actions to fix it if the
connection fails
• Regular check of a server access over # cat /etc/network/networkmonitoring.conf
• ICMP pings to a given server (IP address or DNS name) [general]
• TCP connection to a given server and port monitor_network=0
first_check_delay=60
check_interval=1200
• Once a check fails, monitoring is done every 10 seconds log_level=0
monitor_external_usb=0

[ping]
• Actions are taken after a certain number of consecutive server=8.8.8.8
fails protocol=ping
port=80
timeout=5
• Taken actions when check fails
• Restarting ConnMan service of the default route (if any) [actions]
ping_error_before_service_reconnect=3
• Restarting ConnMan, oFono daemons ping_error_before_servers_restart=5
• Hardware reboot of all WAN modules and ethernet phy ping_error_before_network_hardware_reboot=10
ping_error_before_board_reboot=20
• Reboot board

All fields are described in the file

Change monitor_network to 1 to enable the monitoring
Logs will be available in the file /var/log/networkmonitoring.log

Networkmonitoring monitors the network and takes actions to fix it if the connection
fails. It regularly checks the access of a server access over either ICMP pings to a
given server (IP address or DNS name) or TCP connection to a given server and port

Once a check fails, the monitoring is done every 10 seconds. Actions are taken after a
certain number of consecutive fails.
Those parameters are configurable in the file networkmonitoring.conf under
/etc/network.
In the example, networkmonitoring waits 60s before the first check.
He waits 1200s between two monitoring when network is OK
and it pings the server (by default 8.8.8.8 with a ping timeout at 5s)

In case of failure, networkmonitoring firstly restart the connman service of the

default route (if any). If it is not sufficient, it restarting connman and ofono daemons.
If it is still not sufficient, it performs a Hardware reboot of all WAN modules and

85
ethernet phy and if it is still not sufficient, it reboots the board
In the example
ping_error_before_service_reconnect=3
ping_error_before_servers_restart=5
ping_error_before_network_hardware_reboot=10
ping_error_before_board_reboot=20

85
Networkmonitoring.py
Modifiez le style du titre - Example
Service available on the gateway
• An ethernet connection (eth0)
• Cellular modem (ppp0 not shown by ifconfig) ready to be used
The default route is ethernet and this route can access the server : O for Online

connmanctl services
*AO Wired ethernet_7076ff010a20_cable
*A Orange F cellular_208017001155392_context1

GSM

switch
Ethernet

Let’s illustrate this principle with an example.

2 services are available on the gateway, Ethernet and cellular. The default route is
currently Ethernet. The route can access the server, the status is O for Online.

86
Networkmonitoring.py
Modifiez le style du titre - Example
The script detects a problem on the switch
• The default service is restarted
• Connman detects another service (ppp0) with an access to the server
This cellular service becomes the default one

connmanctl services
*AO Orange F cellular_208017001155392_context1
*AR Wired ethernet_7076ff010a20_cable

GSM

switch
Ethernet

The script detects a problem on the switch.

The default service is then restarted. Connman detects another service (ppp0) with
an access to the server.
This cellular service becomes the default one

87
Networkmonitoring.py
Modifiez le style du titre - Example
The ethernet connection is reestablished
• Since networkmonitoring.py monitors only the default route and the default route is properly
working, no action is taken
• The default route stays on ppp0
connmanctl services
*AO Orange F cellular_208017001155392_context1
*AR Wired ethernet_7076ff010a20_cable

GSM

switch
Ethernet

The ethernet connection is now reestablished but the default route stays on GSM.
Indeed, networkmonitoring monitors only the default route and the default route is
still properly working, so no new action is taken.
That means cellular remains the current route even if Ethernet is defined as the
preferred interface.

88
Networkmonitoring.py
Modifiez le style du titre - Example
The script detects a problem on the default service (cellular)
• The default service is restarted
• ConnMan detects another service (eth0) with the same state (R as Ready)
The Ethernet service becomes the default one

connmanctl services
*AR Wired ethernet_7076ff010a20_cable
*AR Orange F cellular_208017001155392_context1

GSM

switch
Ethernet

Then, an error appears on the GSM connection.

After 3 ping fails, ConnMan service restarts.
ConnMan detects the service eth0. Ethernet becomes the new default route

89