User Tools

Site Tools


Sidebar

Kerlink Wiki Home Page

Home

Setups

General information

Wirnet™ iBTS information

Wirnet™ iFemtoCell information

Wirnet™ iFemtoCell-evolution information

Wirnet™ iStation information

System management

Network management

LoRa Features

KerOS customization

Support and resources



www.kerlink.com

wiki:lora:advanced_features

Advanced LoRa features

LoRa API

The LoRa API takes place between a single server (lorad), which drives all LoRa related devices, and multiple clients (e.g. lorafwd) wanting to interact with these devices. Its main purpose is to provide an abstraction of the LoRa devices to other processes.

The LoRa API allows three ways of communication:

  • Receive data from lorad (uplink).
  • Send data to lorad (downlink).
  • Control lorad configuration (control).

The LoRa API defines a transport layer and a data exchange format.

Details of the LoRa API for CPF 1.2.x

Details of the LoRa API for CPF 1.1.x

Details of the LoRa API for CPF 1.0.x

Compilation

To compile one of the daemons, refer to the toolchain page and to the README.md included in the sources.

lorafwdctl

A tool to edit the lorafwd configuration is installed at the same time than the lorafwd. It can be used instead of editing manually the configuration file.

Examples:

  • To enable database:
    • lorafwdctl database.enable true
  • To configure GWMP node and services:
    • lorafwdctl -s gwmp.node foobar.example.com
    • lorafwdctl gwmp.service.uplink 1234
    • lorafwdctl gwmp.service.downlink 1234
  • To configure GWMP node and services for “foo” instance:
    • lorafwdctl -i=foo -s gwmp.node foobar.example.com

LoRaWAN frame Filtering

DevAddr/NetID Filtering

This feature is available from Keros firmware 5.7 and above.
It allows to save data consumption by forwarding only LoRaWAN packets from a given DevAddr range.
A DevAddr is the ID used by a LoRaWAN device to communicate on a LoRaWAN network, NetID is a part of this DevAddr.
See Lora Alliance NetID FAQ for further details. See NetID and DevAddr Prefix Assignments for the current list of NetIDs and the corresponding DevAddr range.

In order to activate this filtering, configuration is done by a CIDR notation of wanted mask in lorafwd configuration.

Examples:

  • 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 0x24000001 to 0x25FFFFFF.

  • Filtering on Type-3 (/14) Kerlink NetID (600014):
    lorafwdctl -s filter.lorawan.netid "0xE0280000/14"

    Once activated, the gateway will only forward packets from devices with DevAddr from 0xE0280000 to 0xE029FFFF.

  • 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* with a trace like this:
Drop message from 0x24f52627 (not in NetID range 0xE0501234/32)

JoinEUI Filtering

This feature is available from Keros firmware 5.7 and above.
It allows to save data consumption by forwarding only LoRaWAN packets from a given JoinEUI range.
A JoinEUI is an ID used by a LoRaWAN device to join on a LoRaWAN network.

In order to activate this filtering, configuration is done by a CIDR notation of wanted mask in lorafwd configuration.

Examples:

  • Filtering on JoinEUI:
    lorafwdctl -s filter.lorawan.joineui "0x7076FF0001000000/40"

    Once activated, the gateway will only forward join requests from devices with JoinEui from 0x7076FF0001000000 to 0x7076FF0001FFFFFF.

  • Filtering on a specific device with JoinEUI 7076FF0001005554:
    lorafwdctl -s filter.lorawan.joineui "0x7076FF0001005554/64"

    Once activated, the gateway will only forward join requests from devices with JoinEUI 7076FF0001005554.

DevEUI Filtering

This feature is available from Keros firmware 5.7 and above.
It allows to save data consumption by forwarding only LoRaWAN packets from a given DevEUI range.
A DevEUI is an ID used by a LoRaWAN device to communicate on a LoRaWAN network.

In order to activate this filtering, configuration is done by a CIDR notation of wanted mask in lorafwd configuration.

Examples:

  • Filtering on DevEUI:
    lorafwdctl -s filter.lorawan.deveui "0x7777777700000000/32"

    Once activated, the gateway will only forward packets from devices with DevEui from 0x7777777700000000 to 0x77777777FFFFFFFF.

  • Filtering on a specific device with DevEUI 7076FF0001005554:
    lorafwdctl -s filter.lorawan.deveui "0x7076FF0001005554/64"

    Once activated, the gateway will only forward packets from devices with DevEUI 7076FF0001005554.

Multiple range filter and reverse filter

Multiple range filter

Multiple range filter can be applied on NetID/DevAddr, JoinEUI, DevEUI filters.
It is useful when several range of IDs need to be filtered in.
Examples:

  • Filtering on DevAddr:
    lorafwdctl -s filter.lorawan.netid "0x24000000/8" "0x26000000/8"

    Once activated, the gateway will only forward packets from devices with DevAddr from 24000000 to 24FFFFFF and from 26000000 to 26FFFFFF.

Reverse filtering

Reverse filter can be applied on NetID/DevAddr, JoinEUI, DevEUI filters.
It is useful when several range of IDs need to be filtered out.
In this case, filter has to start with “!”.
Examples:

  • Filtering on DevAddr:
    lorafwdctl -s filter.lorawan.netid "!0x24000000/7"

    Once activated, the gateway will reject packets from devices with DevAddr from 0x24000001 to 0x25FFFFFF and will forward any other packets.

It is possible to combine multiple and reverse filter
For example : lorafwdctl -s filter.lorawan.netid “!0x11111100/24” “0x11111110/28”

Be careful at the order of filter when you use simple and reverse filter
Filter [ “!0x24000000/7”, “0x24000000/7” ] is different from filter [ “0x24000000/7”, “!0x24000000/7” ]
See the Filter cheat sheet for a better understanding.

Filter cheat sheet

Proprietary frame

It is possible to filter proprietary LoRaWAN frame.
To do so :

lorafwdctl -s filter.lorawan.proprietary true

Fine timestamp

General information

This feature is only available on Wirnet iBTS and iStation gateways.

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

How does it work?

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

Requirements

AES key(s)

There is one specific AES key per LoRaLOC module. Without it, data cannot be deciphered. Contact support@kerlink.fr and provide them with the serial number of each gateway. They will provide you with the AES key of each LoRaLOC of each Wirnet iBTS.

GPS fix

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

To see the NMEA frames coming from the GPS chip, issue the command cat /dev/nmea2.
parameters:

  • 7th field - GPS fix 0=no fix, 1=fix GPS.
  • 8th field - Connected satellites number of connected satellites (4 in following example).

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

A GPS fix value equal to 1 is required to use the fine timestamp feature.

When lorad is started with the -vv extra args, if the GPS synchronization is lost the following trace is logged If fix value is not equal to one, the following error will be displayed in the packet forwarder log:
Feb 13 11:18:24 klk-lpbs-050789 local1.info lorad[1390]: <6> PPS is disabled

TAI clock (optionnal)

International Atomic Time (TAI, from the French name “Temps Atomique International”) is a high-precision atomic coordinate time standard based on the notional passage of proper time on Earth's geoid.
As of 31 December 2016, when another leap second was added, TAI is exactly 37 seconds ahead of UTC.
TAI clock is obtained once the GPS synchronization is achieved. Note that it can take about half an hour.
A gateway uses TAI clock to retrieve fine timestamps whenever it is possible.

To check if TAI clock is OK, run the following command and check that both clocks have a difference of at least 37 seconds.

$ taiclock -d
CLOCK_REALTIME: res: 0. time:1550158205.428239230
CLOCK_TAI:      res: 0. time:1550158242.428243230

Deciphering

By default, fine timestamps are deciphered by the Application server of the LNS.
For debug purposes, fine timestamps can be directly deciphered from the gateway. Please note it should not be used in production environments.

To activate deciphering from the gateway, edit the frequency plan (in /etc/lorad/):

  • “aes_key”: “00112233445566778899AABBCCDDEEFF”,
  • “fine_timestamp_decrypt_enable”: true,

JSON Message

Packets received by gateways are sent to the LNS along with their meta-data in a JSON array as below:

{
  "rxpk": [
    {
      "aesk": 0,
      "brd": 23,
      "codr": "4/5",
      "data": "QCYAJQAAhHcZ3njAQQQ7+Qzqhdp2Qogmxw==",
      "datr": "SF7BW125",
      "freq": 868.5,
      "jver": 2,
      "modu": "LORA",
      "rsig": [
        {
          "ant": 0,
          "chan": 7,
          "etime": "7xkP+6rs/F/Y845JaB5pnQ==",
          "foff": 2944,
          "ftdelta": 0,
          "ftstat": 0,
          "ftver": 1,
          "lsnr": -3,
          "rssic": -116,
          "rssis": -122,
          "rssisd": 0
        }
      ],
      "size": 25,
      "stat": 1,
      "tmms": 1192801083186,
      "tmst": 64679556
    }
  ]
}
  • tmms: classic timestamp: GPS time, number of milliseconds since 06 Jan.1980. This field is only present when GPS synchronization and TAI clock are OK.
  • time: “time”:2017-10-23T13:37:45.570488Z. This field replaces the tmms field when GPS synchronization or TAI clock is not avaialble.
  • etime:“etime”:“uONILwcR/z8069OwdklfaQ==”. nanosecond number - encrypted time.
  • ftime: This field replaces etime when fine_timestamp_decrypt_enable is true. It contains the decrypted number of nanoseconds.

The etime field can sometimes be missing due to a loss of GPS signal.

Security key

The AES Key is used to decypher the etime field.

AES key:

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

Decypher the data

Hereunder is an example of script that decrypts the nanosecond number using OpenSSL.

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

To avoid an issue due to the nopad parameter in the script, use OpenSSL 1.1.0g 25 May 2017 or greater.
To check the version:

openssl version

The etime field is an hexadecimal value which has been 64 base encoded. To retrieve the actual number of nanoseconds from the etime value, the value needs to be divided by 32.

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

example

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

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

Note that etime value is always inferior to 1. If not Your AES key is probably wrong.

wiki/lora/advanced_features.txt · Last modified: 2024/04/11 12:14 by ehe