v1.0.0
* Initial release for SX1302 CoreCell Reference Design.
This commit is contained in:
Michael Coracin
parent
c7a5171a47
commit
4c61c5d48e
79 changed files with 30157 additions and 0 deletions
253
packet_forwarder/readme.md
Normal file
253
packet_forwarder/readme.md
Normal file
|
|
@ -0,0 +1,253 @@
|
|||
/ _____) _ | |
|
||||
( (____ _____ ____ _| |_ _____ ____| |__
|
||||
\____ \| ___ | (_ _) ___ |/ ___) _ \
|
||||
_____) ) ____| | | || |_| ____( (___| | | |
|
||||
(______/|_____)_|_|_| \__)_____)\____)_| |_|
|
||||
(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*
|
||||
Loading…
Add table
Add a link
Reference in a new issue