1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
|
/ _____) _ | |
( (____ _____ ____ _| |_ _____ ____| |__
\____ \| ___ | (_ _) ___ |/ ___) _ \
_____) ) ____| | | || |_| ____( (___| | | |
(______/|_____)_|_|_| \__)_____)\____)_| |_|
(C)2013 Semtech-Cycleo
Lora network packet forwarder project
======================================
1. Core program: lora_pkt_fwd
-------------------------------
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.
((( 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 |
+- - - - - - - - - - - - - - -+
Uplink: radio packets received by the gateway, with metadata added by the
gateway, forwarded to the server. Might also include gateway status.
Downlink: packets generated by the server, with additional metadata, to be
transmitted by the gateway on the radio channel. Might also include
configuration data for the gateway.
2. Helper programs
-------------------
Those programs are included in the project to provide examples on how to
communicate with the packet forwarder, and to help the system builder use it
without having to implement a full Lora network server.
### 3.1. util_sink ###
The packet sink is a simple helper program listening on a single port for UDP
datagrams, and displaying a message each time one is received. The content of
the datagram itself is ignored.
### 3.2. util_ack ###
The packet acknowledger is a simple helper program listening on a single UDP
port and responding to PUSH_DATA datagrams with PUSH_ACK, and to PULL_DATA
datagrams with PULL_ACK.
### 3.3. util_tx_test ###
The network packet sender is a simple helper program used to send packets
through the gateway-to-server downlink route.
4. Helper scripts
-----------------
### 4.1. lora_gateway/reset_lgw.sh
This script, provided with the HAL (lora_gateway), must be launched on IoT Start
Kit platform to reset concentrator chip through GPIO, before starting any
application using the concentrator, like the packet forwarder.
### 4.2. packet_forwarder/lora_pkt_fwd/update_gwid.sh
This script allows automatic update of Gateway_ID with unique MAC address, in
packet forwarder JSON configuration file.
Please refer to the script header for more details.
5. Changelog
-------------
### v4.0.1 - 2017-03-16 ###
* Class-B: Added xtal error correction to beacon frequency
* Class-B: Added support for all regions to beacon frame format (various
datarates imply different frame sizes), as defined by LoRaWAN v1.1.
### v4.0.0 - 2017-01-10 ###
* Added Class-B support, as defined in LoRaWAN v1.1
* Downlink only support "tmst" or "tmms" timestamp. "time" is not supported
anymore ("time" field is kept in Uplink as an informative field).
* Reworked thread_gps to handle GPS UBX messages for native GPS time.
* Updated Gateway <-> NetworkServer protocol to describe the new "tmms" field.
* Updated global_conf.PCB286*.json to remove indexes of the TX gain LUT above
20dBm. Use PCB336 (aka GW v1.5) to comply with ETSI TX mask between 20dBm and
27dBm.
### v3.1.0 - 2016-09-07 ###
* Updated "Listen-Before-Talk" JSON configuration to match with LBT rework.
* Added TX Notch Filter JSON configuration.
* Updated Parson library to latest version
* Fixed Class-B beacon CRC-16 calculation
* Removed JiT time_on_air local function, and use lgw_time_on_air() function
### v3.0.0 - 2016-05-19 ###
* Merged all different flavours of packet forwarder into one unique lora_pkt_fwd
Note: Various flavours can still be achieved using the corresponding
global_conf.json.XXX file provided in lora_pkt_fwd/cfg.
* Added downlink "just-in-time" scheduling to optimize downlink capacity.
* Updated Gateway <-> NetworkServer protocol to describe the new format of
"tx_ack" message.
* Added "Listen-Before-Talk" JSON configuration.
* Splitted reset_pkt_fwd.sh script in 2 different scripts:
- reset_lgw.sh, provided with the HAL (lora_gateway)
- update_gwid.sh, provided with lora_pkt_fwd
WARNING: Gateway <-> Network Server protocol version has changed. Please refer
to PROTOCOL.txt file.
### v2.2.1 - 2016-04-12 ###
* util_tx_test: added FSK support and specific payload for easier PER testing.
* base64: fixed padding check.
* Updated all makefiles to handle the creation of obj directory when necessary.
* [gps/beacon]_pkt_fwd: fixed crash on exit when GPS not enabled.
* [*]_pkt_fwd: added a cfg/ directory containing different flavours or the
global_conf.json file for different boards: Ref Design PCB_E336 (GW1.5-27dBm),
Ref Design PCB_E286 (GW1.0), Ref Design with US902 frequency plan.
### v2.2.0 - 2015-10-08 ###
* Removed FTDI support in makefiles to align with HAL v3.2.0.
* Force IPv4 mode usage on UDP socket, instead of auto. The auto mode was
causing an issue to properly resolve LoRa server hostname given in JSON
configuration file (MariaDB issue: https://mariadb.atlassian.net/browse/MDEV-4356,
https://mariadb.atlassian.net/browse/MDEV-4379).
### v2.1.0 - 2015-06-29 ###
* Added helper script for concentrator reset through GPIO, needed on IoT
Starter Kit (reset_pkt_fwd.sh).
* The same reset_pkt_fwd.sh script also allows to automatically update the
Gateway_ID field in JSON configuration file, with board MAC address.
* Updated JSON configuration file with proper default value for IoT Starter
Kit: server address set to local server, GPS device path set to proper value
(/dev/ttyAMA0).
### v2.0.0 - 2015-04-30 ###
* Changed: Several configuration parameters are now set dynamically from the
JSON configuration file: RSSI offset, concentrator clock source, radio type,
TX gain table, network type. The HAL does not need to be recompiled any more to
update those parameters. An example for IoT Starter Kit platform is provided in
global_conf.json for basic, gps and beacon packet_forwarder.
* Removed: Band frequency JSON configuration file has been removed. An example
for EU 868MHz is provided in global_conf.json for basic, gps and beacon packet
forwarder.
* Changed: Updated makefiles to allow cross compilation from environment
variable (ARCH, CROSS_COMPILE).
** WARNING: **
** Update your JSON configuration file with new dynamic parameters. **
### v1.4.1 - 2015-01-23 ###
* Bugfix: fixed LP-116, fdev parameter parsed incorrectly, making FSK TX fail.
* Bugfix: fixed a platform-dependant minor rounding issue.
* Beta: updated beacon format, partially aligned with latest class B proposal.
### v1.4.0 - 2014-10-16 ###
* Feature: Adding TX FSK support.
* Feature: optional auto-quit if a certain number of PULL_ACK is missed.
* Feature: upstream and downstream ping time is displayed on console.
* Bugfix: some beacons were missed at high beaconing frequency.
* Bugfix: critical snprintf error caused a crash for long payloads.
* FSK bitrate now appears in the upstream JSON.
### v1.3.0 - 2014-03-28 ###
* Feature: adding preliminary beacon support for class B development.
* Solved warnings with 64b integer printf when compiling on x86_64.
* Updated build system for easier deployment on various hardware.
* Changed threads organization in the forwarder programs.
* Removed duplicate protocol documentation.
### v1.2.0 - 2014-02-03 ###
* Feature: added a GPS-enabled packet forwarder, used to timestamp received
packet with a globally-synchronous microsecond-accurate timestamp.
* Feature: GPS packet forwarder sends status report on the uplink, protocol
specification updated accordingly (report include gateway geolocation).
* Feature: packets can be sent without CRC at radio layer.
* Bugfix: no more crash with base64 padded input.
* Bugfix: no more rounding errors on the 'freq' value sent to server.
* A minimum preamble of 6 Lora symbol is enforced for optimum sensitivity.
* Padded Base64 is sent on uplink, downlink accepts padded and unpadded Base64.
* Updated the Parson JSON library to a version that supports comments.
* Added .md (Markdown) extension to readme files for better Github viewing.
### v1.1.0 - 2013-12-09 ###
* Feature: added packet filtering parameters to the JSON configuration files.
* Bugfix: will not send a datagram if all the packets returned by the receive()
function have been filtered out.
* Bugfix: removed leading zeros for the timestamp in the upstream JSON because
it is not compliant with JSON standard (might be interpreted as octal number).
* Removed TXT extension for README files for better Github integration.
* Cleaned-up documentation, moving change log to top README.
* Modified Makefiles to ease cross-compilation.
### v1.0.0 - 2013-11-22 ###
* Initial release of the packet forwarder, protocol specifications and helper
programs.
6. Legal notice
----------------
The information presented in this project documentation does not form part of
any quotation or contract, is believed to be accurate and reliable and may be
changed without notice. No liability will be accepted by the publisher for any
consequence of its use. Publication thereof does not convey nor imply any
license under patent or other industrial or intellectual property rights.
Semtech assumes no responsibility or liability whatsoever for any failure or
unexpected operation resulting from misuse, neglect improper installation,
repair or improper handling or unusual physical or electrical stress
including, but not limited to, exposure to parameters beyond the specified
maximum ratings or operation outside the specified range.
SEMTECH PRODUCTS ARE NOT DESIGNED, INTENDED, AUTHORIZED OR WARRANTED TO BE
SUITABLE FOR USE IN LIFE-SUPPORT APPLICATIONS, DEVICES OR SYSTEMS OR OTHER
CRITICAL APPLICATIONS. INCLUSION OF SEMTECH PRODUCTS IN SUCH APPLICATIONS IS
UNDERSTOOD TO BE UNDERTAKEN SOLELY AT THE CUSTOMER’S OWN RISK. Should a
customer purchase or use Semtech products for any such unauthorized
application, the customer shall indemnify and hold Semtech and its officers,
employees, subsidiaries, affiliates, and distributors harmless against all
claims, costs damages and attorney fees which could arise.
*EOF*
|
