jlpoole/sx1302_hal
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sx1302_hal/packet_forwarder/readme.md

253 lines
12 KiB
Markdown
Raw Normal View History

v1.0.0 * Initial release for SX1302 CoreCell Reference Design.
2019-07-12 15:40:13 +02:00
/ _____) _ | |
( (____ _____ ____ _| |_ _____ ____| |__
\____ \| ___ | (_ _) ___ |/ ___) _ \
_____) ) ____| | | || |_| ____( (___| | | |
(______/|_____)_|_|_| \__)_____)\____)_| |_|
(C)2019 Semtech
SX1302 packet forwarder
=======================
## 1. Introduction
The packet forwarder is a program running on the host of a Lora gateway that
forwards RF packets receive by the concentrator to a server through a IP/UDP
link, and emits RF packets that are sent by the server. It can also emit a
network-wide GPS-synchronous beacon signal used for coordinating all nodes of
the network.
To learn more about the network protocol between the gateway and the server,
please read the PROTOCOL.TXT document.
## 2. System schematic and definitions
((( Y )))
|
|
+- -|- - - - - - - - - - - - -+ xxxxxxxxxxxx +--------+
|+--+-----------+ +------+| xx x x xxx | |
|| | | || xx Internet xx | |
|| Concentrator |<----+ Host |<------xx or xx-------->| |
|| | SPI | || xx Intranet xx | Server |
|+--------------+ +------+| xxxx x xxxx | |
| ^ ^ | xxxxxxxx | |
| | PPS +-----+ NMEA | | | |
| +------| GPS |-------+ | +--------+
| +-----+ |
| |
| Gateway |
+- - - - - - - - - - - - - - -+
Concentrator: radio RX/TX board, based on Semtech multichannel modems (SX130x),
transceivers (SX135x) and/or low-power stand-alone modems (SX127x).
Host: embedded computer on which the packet forwarder is run. Drives the
concentrator through a SPI link.
Gateway: a device composed of at least one radio concentrator, a host, some
network connection to the internet or a private network (Ethernet, 3G, Wifi,
microwave link), and optionally a GPS receiver for synchronization.
Server: an abstract computer that will process the RF packets received and
forwarded by the gateway, and issue RF packets in response that the gateway
will have to emit.
## 3. Dependencies
This program uses the Parson library (http://kgabis.github.com/parson/) by
Krzysztof Gabis for JSON parsing.
Many thanks to him for that very practical and well written library.
This program is statically linked with the libloragw Lora concentrator library.
It was tested with v1.3.0 of the library but should work with any later
version provided the API is v1 or a later backward-compatible API.
Data structures of the received packets are accessed by name (ie. not at a
binary level) so new functionalities can be added to the API without affecting
that program at all.
This program follows the v1.3 version of the gateway-to-server protocol.
The last dependency is the hardware concentrator (based on FPGA or SX130x
chips) that must be matched with the proper version of the HAL.
## 4. Usage
* Pick the global_conf.json file that fit with your platform, region and feature
need.
* Update the JSON configuration (global and local) files, as explained below.
* Run:
./lora_pkt_fwd -c global_conf.json
To stop the application, press Ctrl+C.
Unless it is manually stopped or encounter a critical error, the program will
run forever.
The way the program takes configuration files into account is the following:
* if a specific configuration file is given as program argument, use the
one specified.
* if there is a global_conf.json parse it.
The global configuration file should be exactly the same throughout your
network, contain all global parameters (parameters for "sensor" radio
channels) and preferably default "safe" values for parameters that are
specific for each gateway (eg. specify a default MAC address).
In each configuration file, the program looks for a JSON object named
"SX130x_conf" that should contain the parameters for the Lora concentrator
board (RF channels definition, modem parameters, etc) and another JSON object
called "gateway_conf" that should contain the gateway parameters (gateway MAC
address, IP address of the server, keep-alive time, etc).
To learn more about the JSON configuration format, read the provided JSON
files and the libloragw API documentation.
Every X seconds (parameter settable in the configuration files) the program
display statistics on the RF packets received and sent, and the network
datagrams received and sent.
The program also send some statistics to the server in JSON format.
## 5. "Just-In-Time" downlink scheduling
The LoRa concentrator can have only one TX packet programmed for departure at a
time. The actual departure of a downlink packet will be done based on its
timestamp, when the concentrator internal counter reaches timestamp’s value.
The departure of a beacon will be done based on a GPS PPS event.
It may happen that, due to network variable latency, the gateway receives one
or many downlink packets from the server while a TX is already programmed in the
concentrator. The packet forwarder has to store and order incoming downlink
packets (in a queue), so that they can all be programmed in the concentrator at
the proper time and sent over the air.
Possible failures that may occur and that have to be reported to the server are:
- It is too early or too late to send a given packet
- A packet collides with another packet already queued
- A packet collides with a beacon
- TX RF parameters (frequency, power) are not supported by gateway
- Gateway’s GPS is unlocked, so cannot process Class B downlink
It is called "Just-in-Time" (JiT) scheduling, because the packet forwarder will
program a downlink or a beacon packet in the concentrator just before it has to
be sent over the air.
Another benefit of JiT is to optimize the gateway downlink capacity by avoiding
to keep the concentrator TX buffer busy for too long.
In order to achieve "Just-in-Time" scheduling, the following software elements
have been added:
- A JiT queue, with associated enqueue/peek/dequeue functions and packet
acceptance criterias. It is where downlink packets are stored, waiting to be
sent.
- A JiT thread, which regularly checks if there is a packet in the JiT queue
ready to be programmed in the concentrator, based on current concentrator
internal time.
### 5.1. Concentrator vs GPS time synchronization
There are 2 cases for which we need to convert a GPS time to concentrator
counter:
- Class B downlink: when the “time” field of JSON “txpk” is filled instead
of the “tmst” field, we need to be able to determine if the packet can be
queued in JiT queue or not, based on its corresponding concentrator
counter value.
Note: even if a Class-B downlink is given with a GPS timestamp, the
concentrator TX mode is configured as “TIMESTAMP”, and not “ON_GPS”. So
at the end, it is the counter value which will be used for transmission.
- Beacons: beacons transmission time is based on GPS clock, and the
concentrator TX mode is configured as “ON_GPS” for accurate beacon
transmission on GPS PPS event. In this case, the concentrator does not
need the packet counter to be set. But, as the JiT thread decides if a
packet has to be peeked or not, based on its concentrator counter, we need
to have the beacon packet counter set (see next chapter for more details
on JiT scheduling).
We also need to convert a SX1302 counter value to GPS UTC time when we receive
an uplink, in order to fill the “time” field of JSON “rxpk” structure.
### 5.2. TX scheduling
The JiT queue implemented is a static array of nodes, where each node contains:
- the downlink packet, with its type (beacon, downlink class A, B or C)
- a “pre delay” which depends on packet type (BEACON_GUARD, TX_START_DELAY…)
- a “post delay” which depends on packet type (“time on air” of this packet
computed based on its size, datarate and coderate, or BEACON_RESERVED)
Several functions are implemented to manipulate this queue or get info from it:
- init: initialize array with default values
- is full / is empty: gives queue status
- enqueue: checks if the given packet can be queued or not, based on several
criteria’s
- peek: checks if the queue contains a packet that must be passed
immediately to the concentrator for transmission and returns corresponding
index if any.
- dequeue: actually removes from the queue the packet at index given by peek
function
The queue is always kept sorted on ascending timestamp order.
The JiT thread will regularly check in the JiT queue if there is a packet to be
sent soon. If a packet is matching, it is dequeued and programmed in the
concentrator TX buffer.
### 5.3. Fine tuning parameters
There are few parameters of the JiT queue which could be tweaked to adapt to
different system constraints.
- inc/jitqueue.h:
JIT_QUEUE_MAX: The maximum number of nodes in the queue.
- src/jitqueue.c:
TX_JIT_DELAY: The number of milliseconds a packet is programmed in the
concentrator TX buffer before its actual departure time.
TX_MARGIN_DELAY: Packet collision check margin
6. License
-----------
Copyright (C) 2019, SEMTECH S.A.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the Semtech corporation nor the
names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL SEMTECH S.A. BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
6. License for Parson library
------------------------------
Parson ( http://kgabis.github.com/parson/ )
Copyright (C) 2012 Krzysztof Gabis
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*EOF*
Reference in a new issue Copy permalink