Damian Gabino / picoGW_packet_forwarder

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

PROTOCOL.TXT@0:9002b89157da, 2018-04-11 (annotated)

Committer:
dgabino
Date:
Wed Apr 11 14:47:16 2018 +0000
Revision:
0:9002b89157da
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dgabino 0:9002b89157da 1 ______ _
dgabino 0:9002b89157da 2 / _____) _ | |
dgabino 0:9002b89157da 3 ( (____ _____ ____ _| |_ _____ ____| |__
dgabino 0:9002b89157da 4 \____ \| ___ | (_ _) ___ |/ ___) _ \
dgabino 0:9002b89157da 5 _____) ) ____| | | || |_| ____( (___| | | |
dgabino 0:9002b89157da 6 (______/|_____)_|_|_| \__)_____)\____)_| |_|
dgabino 0:9002b89157da 7 (C)2013 Semtech-Cycleo
dgabino 0:9002b89157da 8
dgabino 0:9002b89157da 9 Basic communication protocol between Lora gateway and server
dgabino 0:9002b89157da 10 =============================================================
dgabino 0:9002b89157da 11
dgabino 0:9002b89157da 12
dgabino 0:9002b89157da 13 1. Introduction
dgabino 0:9002b89157da 14 ----------------
dgabino 0:9002b89157da 15
dgabino 0:9002b89157da 16 The protocol between the gateway and the server is purposefully very basic and
dgabino 0:9002b89157da 17 for demonstration purpose only, or for use on private and reliable networks.
dgabino 0:9002b89157da 18
dgabino 0:9002b89157da 19 There is no authentication of the gateway or the server, and the acknowledges
dgabino 0:9002b89157da 20 are only used for network quality assessment, not to correct UDP datagrams
dgabino 0:9002b89157da 21 losses (no retries).
dgabino 0:9002b89157da 22
dgabino 0:9002b89157da 23
dgabino 0:9002b89157da 24 2. System schematic and definitions
dgabino 0:9002b89157da 25 ------------------------------------
dgabino 0:9002b89157da 26
dgabino 0:9002b89157da 27 ((( Y )))
dgabino 0:9002b89157da 28 |
dgabino 0:9002b89157da 29 |
dgabino 0:9002b89157da 30 + - -|- - - - - - - - - - - - - + xxxxxxxxxxxx +--------+
dgabino 0:9002b89157da 31 | +--+-----------+ +------+ | xx x x xxx | |
dgabino 0:9002b89157da 32 | | | | | | xx Internet xx | |
dgabino 0:9002b89157da 33 | | Concentrator |<--->| Host |<-------xx or xx-------->| |
dgabino 0:9002b89157da 34 | | | SPI | | | xx Intranet xx | Server |
dgabino 0:9002b89157da 35 | +--------------+ +------+ | xxxx x xxxx | |
dgabino 0:9002b89157da 36 | ^ ^ | xxxxxxxx | |
dgabino 0:9002b89157da 37 | | PPS +-------+ NMEA | | | |
dgabino 0:9002b89157da 38 | +-----| GPS |-------+ | +--------+
dgabino 0:9002b89157da 39 | | (opt) | |
dgabino 0:9002b89157da 40 | +-------+ |
dgabino 0:9002b89157da 41 | |
dgabino 0:9002b89157da 42 | Gateway |
dgabino 0:9002b89157da 43 +- - - - - - - - - - - - - - - -+
dgabino 0:9002b89157da 44
dgabino 0:9002b89157da 45 __Concentrator__: radio RX/TX board, based on Semtech multichannel modems
dgabino 0:9002b89157da 46 (SX130x), transceivers (SX135x) and/or low-power stand-alone modems (SX127x).
dgabino 0:9002b89157da 47
dgabino 0:9002b89157da 48 __Host__: embedded computer on which the packet forwarder is run. Drives the
dgabino 0:9002b89157da 49 concentrator through a SPI link.
dgabino 0:9002b89157da 50
dgabino 0:9002b89157da 51 __GPS__: GNSS (GPS, Galileo, GLONASS, etc) receiver with a "1 Pulse Per Second"
dgabino 0:9002b89157da 52 output and a serial link to the host to send NMEA frames containing time and
dgabino 0:9002b89157da 53 geographical coordinates data. Optional.
dgabino 0:9002b89157da 54
dgabino 0:9002b89157da 55 __Gateway__: a device composed of at least one radio concentrator, a host, some
dgabino 0:9002b89157da 56 network connection to the internet or a private network (Ethernet, 3G, Wifi,
dgabino 0:9002b89157da 57 microwave link), and optionally a GPS receiver for synchronization.
dgabino 0:9002b89157da 58
dgabino 0:9002b89157da 59 __Server__: an abstract computer that will process the RF packets received and
dgabino 0:9002b89157da 60 forwarded by the gateway, and issue RF packets in response that the gateway
dgabino 0:9002b89157da 61 will have to emit.
dgabino 0:9002b89157da 62
dgabino 0:9002b89157da 63 It is assumed that the gateway can be behind a NAT or a firewall stopping any
dgabino 0:9002b89157da 64 incoming connection.
dgabino 0:9002b89157da 65 It is assumed that the server has an static IP address (or an address solvable
dgabino 0:9002b89157da 66 through a DNS service) and is able to receive incoming connections on a
dgabino 0:9002b89157da 67 specific port.
dgabino 0:9002b89157da 68
dgabino 0:9002b89157da 69
dgabino 0:9002b89157da 70 3. Upstream protocol
dgabino 0:9002b89157da 71 ---------------------
dgabino 0:9002b89157da 72
dgabino 0:9002b89157da 73 ### 3.1. Sequence diagram ###
dgabino 0:9002b89157da 74
dgabino 0:9002b89157da 75 +---------+ +---------+
dgabino 0:9002b89157da 76 | Gateway | | Server |
dgabino 0:9002b89157da 77 +---------+ +---------+
dgabino 0:9002b89157da 78 | -----------------------------------\ |
dgabino 0:9002b89157da 79 |-| When 1-N RF packets are received | |
dgabino 0:9002b89157da 80 | ------------------------------------ |
dgabino 0:9002b89157da 81 | |
dgabino 0:9002b89157da 82 | PUSH_DATA (token X, GW MAC, JSON payload) |
dgabino 0:9002b89157da 83 |------------------------------------------------------------->|
dgabino 0:9002b89157da 84 | |
dgabino 0:9002b89157da 85 | PUSH_ACK (token X) |
dgabino 0:9002b89157da 86 |<-------------------------------------------------------------|
dgabino 0:9002b89157da 87 | ------------------------------\ |
dgabino 0:9002b89157da 88 | | process packets *after* ack |-|
dgabino 0:9002b89157da 89 | ------------------------------- |
dgabino 0:9002b89157da 90 | |
dgabino 0:9002b89157da 91
dgabino 0:9002b89157da 92 ### 3.2. PUSH_DATA packet ###
dgabino 0:9002b89157da 93
dgabino 0:9002b89157da 94 That packet type is used by the gateway mainly to forward the RF packets
dgabino 0:9002b89157da 95 received, and associated metadata, to the server.
dgabino 0:9002b89157da 96
dgabino 0:9002b89157da 97 Bytes | Function
dgabino 0:9002b89157da 98 :------:|---------------------------------------------------------------------
dgabino 0:9002b89157da 99 0 | protocol version = 2
dgabino 0:9002b89157da 100 1-2 | random token
dgabino 0:9002b89157da 101 3 | PUSH_DATA identifier 0x00
dgabino 0:9002b89157da 102 4-11 | Gateway unique identifier (MAC address)
dgabino 0:9002b89157da 103 12-end | JSON object, starting with {, ending with }, see section 4
dgabino 0:9002b89157da 104
dgabino 0:9002b89157da 105 ### 3.3. PUSH_ACK packet ###
dgabino 0:9002b89157da 106
dgabino 0:9002b89157da 107 That packet type is used by the server to acknowledge immediately all the
dgabino 0:9002b89157da 108 PUSH_DATA packets received.
dgabino 0:9002b89157da 109
dgabino 0:9002b89157da 110 Bytes | Function
dgabino 0:9002b89157da 111 :------:|---------------------------------------------------------------------
dgabino 0:9002b89157da 112 0 | protocol version = 2
dgabino 0:9002b89157da 113 1-2 | same token as the PUSH_DATA packet to acknowledge
dgabino 0:9002b89157da 114 3 | PUSH_ACK identifier 0x01
dgabino 0:9002b89157da 115
dgabino 0:9002b89157da 116
dgabino 0:9002b89157da 117 4. Upstream JSON data structure
dgabino 0:9002b89157da 118 --------------------------------
dgabino 0:9002b89157da 119
dgabino 0:9002b89157da 120 The root object can contain an array named "rxpk":
dgabino 0:9002b89157da 121
dgabino 0:9002b89157da 122 ``` json
dgabino 0:9002b89157da 123 {
dgabino 0:9002b89157da 124 "rxpk":[ {...}, ...]
dgabino 0:9002b89157da 125 }
dgabino 0:9002b89157da 126 ```
dgabino 0:9002b89157da 127
dgabino 0:9002b89157da 128 That array contains at least one JSON object, each object contain a RF packet
dgabino 0:9002b89157da 129 and associated metadata with the following fields:
dgabino 0:9002b89157da 130
dgabino 0:9002b89157da 131 Name | Type | Function
dgabino 0:9002b89157da 132 :----:|:------:|--------------------------------------------------------------
dgabino 0:9002b89157da 133 time | string | UTC time of pkt RX, us precision, ISO 8601 'compact' format
dgabino 0:9002b89157da 134 tmst | number | Internal timestamp of "RX finished" event (32b unsigned)
dgabino 0:9002b89157da 135 freq | number | RX central frequency in MHz (unsigned float, Hz precision)
dgabino 0:9002b89157da 136 chan | number | Concentrator "IF" channel used for RX (unsigned integer)
dgabino 0:9002b89157da 137 rfch | number | Concentrator "RF chain" used for RX (unsigned integer)
dgabino 0:9002b89157da 138 stat | number | CRC status: 1 = OK, -1 = fail, 0 = no CRC
dgabino 0:9002b89157da 139 modu | string | Modulation identifier "LORA" or "FSK"
dgabino 0:9002b89157da 140 datr | string | LoRa datarate identifier (eg. SF12BW500)
dgabino 0:9002b89157da 141 datr | number | FSK datarate (unsigned, in bits per second)
dgabino 0:9002b89157da 142 codr | string | LoRa ECC coding rate identifier
dgabino 0:9002b89157da 143 rssi | number | RSSI in dBm (signed integer, 1 dB precision)
dgabino 0:9002b89157da 144 lsnr | number | Lora SNR ratio in dB (signed float, 0.1 dB precision)
dgabino 0:9002b89157da 145 size | number | RF packet payload size in bytes (unsigned integer)
dgabino 0:9002b89157da 146 data | string | Base64 encoded RF packet payload, padded
dgabino 0:9002b89157da 147
dgabino 0:9002b89157da 148 Example (white-spaces, indentation and newlines added for readability):
dgabino 0:9002b89157da 149
dgabino 0:9002b89157da 150 ``` json
dgabino 0:9002b89157da 151 {"rxpk":[
dgabino 0:9002b89157da 152 {
dgabino 0:9002b89157da 153 "time":"2013-03-31T16:21:17.528002Z",
dgabino 0:9002b89157da 154 "tmst":3512348611,
dgabino 0:9002b89157da 155 "chan":2,
dgabino 0:9002b89157da 156 "rfch":0,
dgabino 0:9002b89157da 157 "freq":866.349812,
dgabino 0:9002b89157da 158 "stat":1,
dgabino 0:9002b89157da 159 "modu":"LORA",
dgabino 0:9002b89157da 160 "datr":"SF7BW125",
dgabino 0:9002b89157da 161 "codr":"4/6",
dgabino 0:9002b89157da 162 "rssi":-35,
dgabino 0:9002b89157da 163 "lsnr":5.1,
dgabino 0:9002b89157da 164 "size":32,
dgabino 0:9002b89157da 165 "data":"-DS4CGaDCdG+48eJNM3Vai-zDpsR71Pn9CPA9uCON84"
dgabino 0:9002b89157da 166 },{
dgabino 0:9002b89157da 167 "time":"2013-03-31T16:21:17.530974Z",
dgabino 0:9002b89157da 168 "tmst":3512348514,
dgabino 0:9002b89157da 169 "chan":9,
dgabino 0:9002b89157da 170 "rfch":1,
dgabino 0:9002b89157da 171 "freq":869.1,
dgabino 0:9002b89157da 172 "stat":1,
dgabino 0:9002b89157da 173 "modu":"FSK",
dgabino 0:9002b89157da 174 "datr":50000,
dgabino 0:9002b89157da 175 "rssi":-75,
dgabino 0:9002b89157da 176 "size":16,
dgabino 0:9002b89157da 177 "data":"VEVTVF9QQUNLRVRfMTIzNA=="
dgabino 0:9002b89157da 178 },{
dgabino 0:9002b89157da 179 "time":"2013-03-31T16:21:17.532038Z",
dgabino 0:9002b89157da 180 "tmst":3316387610,
dgabino 0:9002b89157da 181 "chan":0,
dgabino 0:9002b89157da 182 "rfch":0,
dgabino 0:9002b89157da 183 "freq":863.00981,
dgabino 0:9002b89157da 184 "stat":1,
dgabino 0:9002b89157da 185 "modu":"LORA",
dgabino 0:9002b89157da 186 "datr":"SF10BW125",
dgabino 0:9002b89157da 187 "codr":"4/7",
dgabino 0:9002b89157da 188 "rssi":-38,
dgabino 0:9002b89157da 189 "lsnr":5.5,
dgabino 0:9002b89157da 190 "size":32,
dgabino 0:9002b89157da 191 "data":"ysgRl452xNLep9S1NTIg2lomKDxUgn3DJ7DE+b00Ass"
dgabino 0:9002b89157da 192 }
dgabino 0:9002b89157da 193 ]}
dgabino 0:9002b89157da 194 ```
dgabino 0:9002b89157da 195
dgabino 0:9002b89157da 196 The root object can also contain an object named "stat" :
dgabino 0:9002b89157da 197
dgabino 0:9002b89157da 198 ``` json
dgabino 0:9002b89157da 199 {
dgabino 0:9002b89157da 200 "rxpk":[ {...}, ...],
dgabino 0:9002b89157da 201 "stat":{...}
dgabino 0:9002b89157da 202 }
dgabino 0:9002b89157da 203 ```
dgabino 0:9002b89157da 204
dgabino 0:9002b89157da 205 It is possible for a packet to contain no "rxpk" array but a "stat" object.
dgabino 0:9002b89157da 206
dgabino 0:9002b89157da 207 ``` json
dgabino 0:9002b89157da 208 {
dgabino 0:9002b89157da 209 "stat":{...}
dgabino 0:9002b89157da 210 }
dgabino 0:9002b89157da 211 ```
dgabino 0:9002b89157da 212
dgabino 0:9002b89157da 213 That object contains the status of the gateway, with the following fields:
dgabino 0:9002b89157da 214
dgabino 0:9002b89157da 215 Name | Type | Function
dgabino 0:9002b89157da 216 :----:|:------:|--------------------------------------------------------------
dgabino 0:9002b89157da 217 time | string | UTC 'system' time of the gateway, ISO 8601 'expanded' format
dgabino 0:9002b89157da 218 lati | number | GPS latitude of the gateway in degree (float, N is +)
dgabino 0:9002b89157da 219 long | number | GPS latitude of the gateway in degree (float, E is +)
dgabino 0:9002b89157da 220 alti | number | GPS altitude of the gateway in meter RX (integer)
dgabino 0:9002b89157da 221 rxnb | number | Number of radio packets received (unsigned integer)
dgabino 0:9002b89157da 222 rxok | number | Number of radio packets received with a valid PHY CRC
dgabino 0:9002b89157da 223 rxfw | number | Number of radio packets forwarded (unsigned integer)
dgabino 0:9002b89157da 224 ackr | number | Percentage of upstream datagrams that were acknowledged
dgabino 0:9002b89157da 225 dwnb | number | Number of downlink datagrams received (unsigned integer)
dgabino 0:9002b89157da 226 txnb | number | Number of packets emitted (unsigned integer)
dgabino 0:9002b89157da 227
dgabino 0:9002b89157da 228 Example (white-spaces, indentation and newlines added for readability):
dgabino 0:9002b89157da 229
dgabino 0:9002b89157da 230 ``` json
dgabino 0:9002b89157da 231 {"stat":{
dgabino 0:9002b89157da 232 "time":"2014-01-12 08:59:28 GMT",
dgabino 0:9002b89157da 233 "lati":46.24000,
dgabino 0:9002b89157da 234 "long":3.25230,
dgabino 0:9002b89157da 235 "alti":145,
dgabino 0:9002b89157da 236 "rxnb":2,
dgabino 0:9002b89157da 237 "rxok":2,
dgabino 0:9002b89157da 238 "rxfw":2,
dgabino 0:9002b89157da 239 "ackr":100.0,
dgabino 0:9002b89157da 240 "dwnb":2,
dgabino 0:9002b89157da 241 "txnb":2
dgabino 0:9002b89157da 242 }}
dgabino 0:9002b89157da 243 ```
dgabino 0:9002b89157da 244
dgabino 0:9002b89157da 245
dgabino 0:9002b89157da 246 5. Downstream protocol
dgabino 0:9002b89157da 247 -----------------------
dgabino 0:9002b89157da 248
dgabino 0:9002b89157da 249 ### 5.1. Sequence diagram ###
dgabino 0:9002b89157da 250
dgabino 0:9002b89157da 251 +---------+ +---------+
dgabino 0:9002b89157da 252 | Gateway | | Server |
dgabino 0:9002b89157da 253 +---------+ +---------+
dgabino 0:9002b89157da 254 | -----------------------------------\ |
dgabino 0:9002b89157da 255 |-| Every N seconds (keepalive time) | |
dgabino 0:9002b89157da 256 | ------------------------------------ |
dgabino 0:9002b89157da 257 | |
dgabino 0:9002b89157da 258 | PULL_DATA (token Y, MAC@) |
dgabino 0:9002b89157da 259 |------------------------------------------------------------->|
dgabino 0:9002b89157da 260 | |
dgabino 0:9002b89157da 261 | PULL_ACK (token Y) |
dgabino 0:9002b89157da 262 |<-------------------------------------------------------------|
dgabino 0:9002b89157da 263 | |
dgabino 0:9002b89157da 264
dgabino 0:9002b89157da 265 +---------+ +---------+
dgabino 0:9002b89157da 266 | Gateway | | Server |
dgabino 0:9002b89157da 267 +---------+ +---------+
dgabino 0:9002b89157da 268 | ------------------------------------------------------\ |
dgabino 0:9002b89157da 269 | | Anytime after first PULL_DATA for each packet to TX |-|
dgabino 0:9002b89157da 270 | ------------------------------------------------------- |
dgabino 0:9002b89157da 271 | |
dgabino 0:9002b89157da 272 | PULL_RESP (token Z, JSON payload) |
dgabino 0:9002b89157da 273 |<-------------------------------------------------------------|
dgabino 0:9002b89157da 274 | |
dgabino 0:9002b89157da 275 | TX_ACK (token Z, JSON payload) |
dgabino 0:9002b89157da 276 |------------------------------------------------------------->|
dgabino 0:9002b89157da 277
dgabino 0:9002b89157da 278 ### 5.2. PULL_DATA packet ###
dgabino 0:9002b89157da 279
dgabino 0:9002b89157da 280 That packet type is used by the gateway to poll data from the server.
dgabino 0:9002b89157da 281
dgabino 0:9002b89157da 282 This data exchange is initialized by the gateway because it might be
dgabino 0:9002b89157da 283 impossible for the server to send packets to the gateway if the gateway is
dgabino 0:9002b89157da 284 behind a NAT.
dgabino 0:9002b89157da 285
dgabino 0:9002b89157da 286 When the gateway initialize the exchange, the network route towards the
dgabino 0:9002b89157da 287 server will open and will allow for packets to flow both directions.
dgabino 0:9002b89157da 288 The gateway must periodically send PULL_DATA packets to be sure the network
dgabino 0:9002b89157da 289 route stays open for the server to be used at any time.
dgabino 0:9002b89157da 290
dgabino 0:9002b89157da 291 Bytes | Function
dgabino 0:9002b89157da 292 :------:|---------------------------------------------------------------------
dgabino 0:9002b89157da 293 0 | protocol version = 2
dgabino 0:9002b89157da 294 1-2 | random token
dgabino 0:9002b89157da 295 3 | PULL_DATA identifier 0x02
dgabino 0:9002b89157da 296 4-11 | Gateway unique identifier (MAC address)
dgabino 0:9002b89157da 297
dgabino 0:9002b89157da 298 ### 5.3. PULL_ACK packet ###
dgabino 0:9002b89157da 299
dgabino 0:9002b89157da 300 That packet type is used by the server to confirm that the network route is
dgabino 0:9002b89157da 301 open and that the server can send PULL_RESP packets at any time.
dgabino 0:9002b89157da 302
dgabino 0:9002b89157da 303 Bytes | Function
dgabino 0:9002b89157da 304 :------:|---------------------------------------------------------------------
dgabino 0:9002b89157da 305 0 | protocol version = 2
dgabino 0:9002b89157da 306 1-2 | same token as the PULL_DATA packet to acknowledge
dgabino 0:9002b89157da 307 3 | PULL_ACK identifier 0x04
dgabino 0:9002b89157da 308
dgabino 0:9002b89157da 309 ### 5.4. PULL_RESP packet ###
dgabino 0:9002b89157da 310
dgabino 0:9002b89157da 311 That packet type is used by the server to send RF packets and associated
dgabino 0:9002b89157da 312 metadata that will have to be emitted by the gateway.
dgabino 0:9002b89157da 313
dgabino 0:9002b89157da 314 Bytes | Function
dgabino 0:9002b89157da 315 :------:|---------------------------------------------------------------------
dgabino 0:9002b89157da 316 0 | protocol version = 2
dgabino 0:9002b89157da 317 1-2 | random token
dgabino 0:9002b89157da 318 3 | PULL_RESP identifier 0x03
dgabino 0:9002b89157da 319 4-end | JSON object, starting with {, ending with }, see section 6
dgabino 0:9002b89157da 320
dgabino 0:9002b89157da 321 ### 5.5. TX_ACK packet ###
dgabino 0:9002b89157da 322
dgabino 0:9002b89157da 323 That packet type is used by the gateway to send a feedback to the server
dgabino 0:9002b89157da 324 to inform if a downlink request has been accepted or rejected by the gateway.
dgabino 0:9002b89157da 325 The datagram may optionnaly contain a JSON string to give more details on
dgabino 0:9002b89157da 326 acknoledge. If no JSON is present (empty string), this means than no error
dgabino 0:9002b89157da 327 occured.
dgabino 0:9002b89157da 328
dgabino 0:9002b89157da 329 Bytes | Function
dgabino 0:9002b89157da 330 :------:|---------------------------------------------------------------------
dgabino 0:9002b89157da 331 0 | protocol version = 2
dgabino 0:9002b89157da 332 1-2 | same token as the PULL_RESP packet to acknowledge
dgabino 0:9002b89157da 333 3 | TX_ACK identifier 0x05
dgabino 0:9002b89157da 334 4-11 | Gateway unique identifier (MAC address)
dgabino 0:9002b89157da 335 12-end | [optional] JSON object, starting with {, ending with }, see section 6
dgabino 0:9002b89157da 336
dgabino 0:9002b89157da 337 6. Downstream JSON data structure
dgabino 0:9002b89157da 338 ----------------------------------
dgabino 0:9002b89157da 339
dgabino 0:9002b89157da 340 The root object of PULL_RESP packet must contain an object named "txpk":
dgabino 0:9002b89157da 341
dgabino 0:9002b89157da 342 ``` json
dgabino 0:9002b89157da 343 {
dgabino 0:9002b89157da 344 "txpk": {...}
dgabino 0:9002b89157da 345 }
dgabino 0:9002b89157da 346 ```
dgabino 0:9002b89157da 347
dgabino 0:9002b89157da 348 That object contain a RF packet to be emitted and associated metadata with the following fields:
dgabino 0:9002b89157da 349
dgabino 0:9002b89157da 350 Name | Type | Function
dgabino 0:9002b89157da 351 :----:|:------:|--------------------------------------------------------------
dgabino 0:9002b89157da 352 imme | bool | Send packet immediately (will ignore tmst & time)
dgabino 0:9002b89157da 353 tmst | number | Send packet on a certain timestamp value (will ignore time)
dgabino 0:9002b89157da 354 time | string | Send packet at a certain time (GPS synchronization required)
dgabino 0:9002b89157da 355 freq | number | TX central frequency in MHz (unsigned float, Hz precision)
dgabino 0:9002b89157da 356 rfch | number | Concentrator "RF chain" used for TX (unsigned integer)
dgabino 0:9002b89157da 357 powe | number | TX output power in dBm (unsigned integer, dBm precision)
dgabino 0:9002b89157da 358 modu | string | Modulation identifier "LORA" or "FSK"
dgabino 0:9002b89157da 359 datr | string | LoRa datarate identifier (eg. SF12BW500)
dgabino 0:9002b89157da 360 datr | number | FSK datarate (unsigned, in bits per second)
dgabino 0:9002b89157da 361 codr | string | LoRa ECC coding rate identifier
dgabino 0:9002b89157da 362 fdev | number | FSK frequency deviation (unsigned integer, in Hz)
dgabino 0:9002b89157da 363 ipol | bool | Lora modulation polarization inversion
dgabino 0:9002b89157da 364 prea | number | RF preamble size (unsigned integer)
dgabino 0:9002b89157da 365 size | number | RF packet payload size in bytes (unsigned integer)
dgabino 0:9002b89157da 366 data | string | Base64 encoded RF packet payload, padding optional
dgabino 0:9002b89157da 367 ncrc | bool | If true, disable the CRC of the physical layer (optional)
dgabino 0:9002b89157da 368
dgabino 0:9002b89157da 369 Most fields are optional.
dgabino 0:9002b89157da 370 If a field is omitted, default parameters will be used.
dgabino 0:9002b89157da 371
dgabino 0:9002b89157da 372 Examples (white-spaces, indentation and newlines added for readability):
dgabino 0:9002b89157da 373
dgabino 0:9002b89157da 374 ``` json
dgabino 0:9002b89157da 375 {"txpk":{
dgabino 0:9002b89157da 376 "imme":true,
dgabino 0:9002b89157da 377 "freq":864.123456,
dgabino 0:9002b89157da 378 "rfch":0,
dgabino 0:9002b89157da 379 "powe":14,
dgabino 0:9002b89157da 380 "modu":"LORA",
dgabino 0:9002b89157da 381 "datr":"SF11BW125",
dgabino 0:9002b89157da 382 "codr":"4/6",
dgabino 0:9002b89157da 383 "ipol":false,
dgabino 0:9002b89157da 384 "size":32,
dgabino 0:9002b89157da 385 "data":"H3P3N2i9qc4yt7rK7ldqoeCVJGBybzPY5h1Dd7P7p8v"
dgabino 0:9002b89157da 386 }}
dgabino 0:9002b89157da 387 ```
dgabino 0:9002b89157da 388
dgabino 0:9002b89157da 389 ``` json
dgabino 0:9002b89157da 390 {"txpk":{
dgabino 0:9002b89157da 391 "imme":true,
dgabino 0:9002b89157da 392 "freq":861.3,
dgabino 0:9002b89157da 393 "rfch":0,
dgabino 0:9002b89157da 394 "powe":12,
dgabino 0:9002b89157da 395 "modu":"FSK",
dgabino 0:9002b89157da 396 "datr":50000,
dgabino 0:9002b89157da 397 "fdev":3000,
dgabino 0:9002b89157da 398 "size":32,
dgabino 0:9002b89157da 399 "data":"H3P3N2i9qc4yt7rK7ldqoeCVJGBybzPY5h1Dd7P7p8v"
dgabino 0:9002b89157da 400 }}
dgabino 0:9002b89157da 401 ```
dgabino 0:9002b89157da 402
dgabino 0:9002b89157da 403 The root object of TX_ACK packet must contain an object named "txpk_ack":
dgabino 0:9002b89157da 404
dgabino 0:9002b89157da 405 ``` json
dgabino 0:9002b89157da 406 {
dgabino 0:9002b89157da 407 "txpk_ack": {...}
dgabino 0:9002b89157da 408 }
dgabino 0:9002b89157da 409 ```
dgabino 0:9002b89157da 410
dgabino 0:9002b89157da 411 That object contain status information concerning the associated PULL_RESP packet.
dgabino 0:9002b89157da 412
dgabino 0:9002b89157da 413 Name | Type | Function
dgabino 0:9002b89157da 414 :----:|:------:|------------------------------------------------------------------------------
dgabino 0:9002b89157da 415 error | string | Indication about success or type of failure that occured for downlink request.
dgabino 0:9002b89157da 416
dgabino 0:9002b89157da 417 The possible values of "error" field are:
dgabino 0:9002b89157da 418
dgabino 0:9002b89157da 419 Value | Definition
dgabino 0:9002b89157da 420 :-----------------:|---------------------------------------------------------------------
dgabino 0:9002b89157da 421 NONE | Packet has been programmed for downlink
dgabino 0:9002b89157da 422 TOO_LATE | Rejected because it was already too late to program this packet for downlink
dgabino 0:9002b89157da 423 TOO_EARLY | Rejected because downlink packet timestamp is too much in advance
dgabino 0:9002b89157da 424 COLLISION_PACKET | Rejected because there was already a packet programmed in requested timeframe
dgabino 0:9002b89157da 425 COLLISION_BEACON | Rejected because there was already a beacon planned in requested timeframe
dgabino 0:9002b89157da 426 TX_FREQ | Rejected because requested frequency is not supported by TX RF chain
dgabino 0:9002b89157da 427 TX_POWER | Rejected because requested power is not supported by gateway
dgabino 0:9002b89157da 428 GPS_UNLOCKED | Rejected because GPS is unlocked, so GPS timestamp cannot be used
dgabino 0:9002b89157da 429
dgabino 0:9002b89157da 430 Examples (white-spaces, indentation and newlines added for readability):
dgabino 0:9002b89157da 431
dgabino 0:9002b89157da 432 ``` json
dgabino 0:9002b89157da 433 {"txpk_ack":{
dgabino 0:9002b89157da 434 "error":"COLLISION_PACKET"
dgabino 0:9002b89157da 435 }}
dgabino 0:9002b89157da 436 ```
dgabino 0:9002b89157da 437
dgabino 0:9002b89157da 438 7. Revisions
dgabino 0:9002b89157da 439 -------------
dgabino 0:9002b89157da 440
dgabino 0:9002b89157da 441 ### v1.3 ###
dgabino 0:9002b89157da 442
dgabino 0:9002b89157da 443 * Added downlink feedback from gateway to server (PULL_RESP -> TX_ACK)
dgabino 0:9002b89157da 444
dgabino 0:9002b89157da 445 ### v1.2 ###
dgabino 0:9002b89157da 446
dgabino 0:9002b89157da 447 * Added value of FSK bitrate for upstream.
dgabino 0:9002b89157da 448 * Added parameters for FSK bitrate and frequency deviation for downstream.
dgabino 0:9002b89157da 449
dgabino 0:9002b89157da 450 ### v1.1 ###
dgabino 0:9002b89157da 451
dgabino 0:9002b89157da 452 * Added syntax for status report JSON object on upstream.
dgabino 0:9002b89157da 453
dgabino 0:9002b89157da 454 ### v1.0 ###
dgabino 0:9002b89157da 455
dgabino 0:9002b89157da 456 * Initial version.