summaryrefslogtreecommitdiff
path: root/PROTOCOL.TXT
diff options
context:
space:
mode:
Diffstat (limited to 'PROTOCOL.TXT')
-rw-r--r--PROTOCOL.TXT461
1 files changed, 461 insertions, 0 deletions
diff --git a/PROTOCOL.TXT b/PROTOCOL.TXT
new file mode 100644
index 0000000..d479fbe
--- /dev/null
+++ b/PROTOCOL.TXT
@@ -0,0 +1,461 @@
+ ______ _
+ / _____) _ | |
+ ( (____ _____ ____ _| |_ _____ ____| |__
+ \____ \| ___ | (_ _) ___ |/ ___) _ \
+ _____) ) ____| | | || |_| ____( (___| | | |
+ (______/|_____)_|_|_| \__)_____)\____)_| |_|
+ (C)2013 Semtech-Cycleo
+
+Basic communication protocol between Lora gateway and server
+=============================================================
+
+
+1. Introduction
+----------------
+
+The protocol between the gateway and the server is purposefully very basic and
+for demonstration purpose only, or for use on private and reliable networks.
+
+There is no authentication of the gateway or the server, and the acknowledges
+are only used for network quality assessment, not to correct UDP datagrams
+losses (no retries).
+
+
+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 |-------+ | +--------+
+ | | (opt) | |
+ | +-------+ |
+ | |
+ | 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.
+
+__GPS__: GNSS (GPS, Galileo, GLONASS, etc) receiver with a "1 Pulse Per Second"
+output and a serial link to the host to send NMEA frames containing time and
+geographical coordinates data. Optional.
+
+__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.
+
+It is assumed that the gateway can be behind a NAT or a firewall stopping any
+incoming connection.
+It is assumed that the server has an static IP address (or an address solvable
+through a DNS service) and is able to receive incoming connections on a
+specific port.
+
+
+3. Upstream protocol
+---------------------
+
+### 3.1. Sequence diagram ###
+
+ +---------+ +---------+
+ | Gateway | | Server |
+ +---------+ +---------+
+ | -----------------------------------\ |
+ |-| When 1-N RF packets are received | |
+ | ------------------------------------ |
+ | |
+ | PUSH_DATA (token X, GW MAC, JSON payload) |
+ |------------------------------------------------------------->|
+ | |
+ | PUSH_ACK (token X) |
+ |<-------------------------------------------------------------|
+ | ------------------------------\ |
+ | | process packets *after* ack |-|
+ | ------------------------------- |
+ | |
+
+### 3.2. PUSH_DATA packet ###
+
+That packet type is used by the gateway mainly to forward the RF packets
+received, and associated metadata, to the server.
+
+ Bytes | Function
+:------:|---------------------------------------------------------------------
+ 0 | protocol version = 2
+ 1-2 | random token
+ 3 | PUSH_DATA identifier 0x00
+ 4-11 | Gateway unique identifier (MAC address)
+ 12-end | JSON object, starting with {, ending with }, see section 4
+
+### 3.3. PUSH_ACK packet ###
+
+That packet type is used by the server to acknowledge immediately all the
+PUSH_DATA packets received.
+
+ Bytes | Function
+:------:|---------------------------------------------------------------------
+ 0 | protocol version = 2
+ 1-2 | same token as the PUSH_DATA packet to acknowledge
+ 3 | PUSH_ACK identifier 0x01
+
+
+4. Upstream JSON data structure
+--------------------------------
+
+The root object can contain an array named "rxpk":
+
+``` json
+{
+ "rxpk":[ {...}, ...]
+}
+```
+
+That array contains at least one JSON object, each object contain a RF packet
+and associated metadata with the following fields:
+
+ Name | Type | Function
+:----:|:------:|--------------------------------------------------------------
+ time | string | UTC time of pkt RX, us precision, ISO 8601 'compact' format
+ tmms | number | GPS time of pkt RX, number of milliseconds since 06.Jan.1980
+ tmst | number | Internal timestamp of "RX finished" event (32b unsigned)
+ freq | number | RX central frequency in MHz (unsigned float, Hz precision)
+ chan | number | Concentrator "IF" channel used for RX (unsigned integer)
+ rfch | number | Concentrator "RF chain" used for RX (unsigned integer)
+ stat | number | CRC status: 1 = OK, -1 = fail, 0 = no CRC
+ modu | string | Modulation identifier "LORA" or "FSK"
+ datr | string | LoRa datarate identifier (eg. SF12BW500)
+ datr | number | FSK datarate (unsigned, in bits per second)
+ codr | string | LoRa ECC coding rate identifier
+ rssi | number | RSSI in dBm (signed integer, 1 dB precision)
+ lsnr | number | Lora SNR ratio in dB (signed float, 0.1 dB precision)
+ size | number | RF packet payload size in bytes (unsigned integer)
+ data | string | Base64 encoded RF packet payload, padded
+
+Example (white-spaces, indentation and newlines added for readability):
+
+``` json
+{"rxpk":[
+ {
+ "time":"2013-03-31T16:21:17.528002Z",
+ "tmst":3512348611,
+ "chan":2,
+ "rfch":0,
+ "freq":866.349812,
+ "stat":1,
+ "modu":"LORA",
+ "datr":"SF7BW125",
+ "codr":"4/6",
+ "rssi":-35,
+ "lsnr":5.1,
+ "size":32,
+ "data":"-DS4CGaDCdG+48eJNM3Vai-zDpsR71Pn9CPA9uCON84"
+ },{
+ "time":"2013-03-31T16:21:17.530974Z",
+ "tmst":3512348514,
+ "chan":9,
+ "rfch":1,
+ "freq":869.1,
+ "stat":1,
+ "modu":"FSK",
+ "datr":50000,
+ "rssi":-75,
+ "size":16,
+ "data":"VEVTVF9QQUNLRVRfMTIzNA=="
+ },{
+ "time":"2013-03-31T16:21:17.532038Z",
+ "tmst":3316387610,
+ "chan":0,
+ "rfch":0,
+ "freq":863.00981,
+ "stat":1,
+ "modu":"LORA",
+ "datr":"SF10BW125",
+ "codr":"4/7",
+ "rssi":-38,
+ "lsnr":5.5,
+ "size":32,
+ "data":"ysgRl452xNLep9S1NTIg2lomKDxUgn3DJ7DE+b00Ass"
+ }
+]}
+```
+
+The root object can also contain an object named "stat" :
+
+``` json
+{
+ "rxpk":[ {...}, ...],
+ "stat":{...}
+}
+```
+
+It is possible for a packet to contain no "rxpk" array but a "stat" object.
+
+``` json
+{
+ "stat":{...}
+}
+```
+
+That object contains the status of the gateway, with the following fields:
+
+ Name | Type | Function
+:----:|:------:|--------------------------------------------------------------
+ time | string | UTC 'system' time of the gateway, ISO 8601 'expanded' format
+ lati | number | GPS latitude of the gateway in degree (float, N is +)
+ long | number | GPS latitude of the gateway in degree (float, E is +)
+ alti | number | GPS altitude of the gateway in meter RX (integer)
+ rxnb | number | Number of radio packets received (unsigned integer)
+ rxok | number | Number of radio packets received with a valid PHY CRC
+ rxfw | number | Number of radio packets forwarded (unsigned integer)
+ ackr | number | Percentage of upstream datagrams that were acknowledged
+ dwnb | number | Number of downlink datagrams received (unsigned integer)
+ txnb | number | Number of packets emitted (unsigned integer)
+
+Example (white-spaces, indentation and newlines added for readability):
+
+``` json
+{"stat":{
+ "time":"2014-01-12 08:59:28 GMT",
+ "lati":46.24000,
+ "long":3.25230,
+ "alti":145,
+ "rxnb":2,
+ "rxok":2,
+ "rxfw":2,
+ "ackr":100.0,
+ "dwnb":2,
+ "txnb":2
+}}
+```
+
+
+5. Downstream protocol
+-----------------------
+
+### 5.1. Sequence diagram ###
+
+ +---------+ +---------+
+ | Gateway | | Server |
+ +---------+ +---------+
+ | -----------------------------------\ |
+ |-| Every N seconds (keepalive time) | |
+ | ------------------------------------ |
+ | |
+ | PULL_DATA (token Y, MAC@) |
+ |------------------------------------------------------------->|
+ | |
+ | PULL_ACK (token Y) |
+ |<-------------------------------------------------------------|
+ | |
+
+ +---------+ +---------+
+ | Gateway | | Server |
+ +---------+ +---------+
+ | ------------------------------------------------------\ |
+ | | Anytime after first PULL_DATA for each packet to TX |-|
+ | ------------------------------------------------------- |
+ | |
+ | PULL_RESP (token Z, JSON payload) |
+ |<-------------------------------------------------------------|
+ | |
+ | TX_ACK (token Z, JSON payload) |
+ |------------------------------------------------------------->|
+
+### 5.2. PULL_DATA packet ###
+
+That packet type is used by the gateway to poll data from the server.
+
+This data exchange is initialized by the gateway because it might be
+impossible for the server to send packets to the gateway if the gateway is
+behind a NAT.
+
+When the gateway initialize the exchange, the network route towards the
+server will open and will allow for packets to flow both directions.
+The gateway must periodically send PULL_DATA packets to be sure the network
+route stays open for the server to be used at any time.
+
+ Bytes | Function
+:------:|---------------------------------------------------------------------
+ 0 | protocol version = 2
+ 1-2 | random token
+ 3 | PULL_DATA identifier 0x02
+ 4-11 | Gateway unique identifier (MAC address)
+
+### 5.3. PULL_ACK packet ###
+
+That packet type is used by the server to confirm that the network route is
+open and that the server can send PULL_RESP packets at any time.
+
+ Bytes | Function
+:------:|---------------------------------------------------------------------
+ 0 | protocol version = 2
+ 1-2 | same token as the PULL_DATA packet to acknowledge
+ 3 | PULL_ACK identifier 0x04
+
+### 5.4. PULL_RESP packet ###
+
+That packet type is used by the server to send RF packets and associated
+metadata that will have to be emitted by the gateway.
+
+ Bytes | Function
+:------:|---------------------------------------------------------------------
+ 0 | protocol version = 2
+ 1-2 | random token
+ 3 | PULL_RESP identifier 0x03
+ 4-end | JSON object, starting with {, ending with }, see section 6
+
+### 5.5. TX_ACK packet ###
+
+That packet type is used by the gateway to send a feedback to the server
+to inform if a downlink request has been accepted or rejected by the gateway.
+The datagram may optionnaly contain a JSON string to give more details on
+acknoledge. If no JSON is present (empty string), this means than no error
+occured.
+
+ Bytes | Function
+:------:|---------------------------------------------------------------------
+ 0 | protocol version = 2
+ 1-2 | same token as the PULL_RESP packet to acknowledge
+ 3 | TX_ACK identifier 0x05
+ 4-11 | Gateway unique identifier (MAC address)
+ 12-end | [optional] JSON object, starting with {, ending with }, see section 6
+
+6. Downstream JSON data structure
+----------------------------------
+
+The root object of PULL_RESP packet must contain an object named "txpk":
+
+``` json
+{
+ "txpk": {...}
+}
+```
+
+That object contain a RF packet to be emitted and associated metadata with the following fields:
+
+ Name | Type | Function
+:----:|:------:|--------------------------------------------------------------
+ imme | bool | Send packet immediately (will ignore tmst & time)
+ tmst | number | Send packet on a certain timestamp value (will ignore time)
+ tmms | number | Send packet at a certain GPS time (GPS synchronization required)
+ freq | number | TX central frequency in MHz (unsigned float, Hz precision)
+ rfch | number | Concentrator "RF chain" used for TX (unsigned integer)
+ powe | number | TX output power in dBm (unsigned integer, dBm precision)
+ modu | string | Modulation identifier "LORA" or "FSK"
+ datr | string | LoRa datarate identifier (eg. SF12BW500)
+ datr | number | FSK datarate (unsigned, in bits per second)
+ codr | string | LoRa ECC coding rate identifier
+ fdev | number | FSK frequency deviation (unsigned integer, in Hz)
+ ipol | bool | Lora modulation polarization inversion
+ prea | number | RF preamble size (unsigned integer)
+ size | number | RF packet payload size in bytes (unsigned integer)
+ data | string | Base64 encoded RF packet payload, padding optional
+ ncrc | bool | If true, disable the CRC of the physical layer (optional)
+
+Most fields are optional.
+If a field is omitted, default parameters will be used.
+
+Examples (white-spaces, indentation and newlines added for readability):
+
+``` json
+{"txpk":{
+ "imme":true,
+ "freq":864.123456,
+ "rfch":0,
+ "powe":14,
+ "modu":"LORA",
+ "datr":"SF11BW125",
+ "codr":"4/6",
+ "ipol":false,
+ "size":32,
+ "data":"H3P3N2i9qc4yt7rK7ldqoeCVJGBybzPY5h1Dd7P7p8v"
+}}
+```
+
+``` json
+{"txpk":{
+ "imme":true,
+ "freq":861.3,
+ "rfch":0,
+ "powe":12,
+ "modu":"FSK",
+ "datr":50000,
+ "fdev":3000,
+ "size":32,
+ "data":"H3P3N2i9qc4yt7rK7ldqoeCVJGBybzPY5h1Dd7P7p8v"
+}}
+```
+
+The root object of TX_ACK packet must contain an object named "txpk_ack":
+
+``` json
+{
+ "txpk_ack": {...}
+}
+```
+
+That object contain status information concerning the associated PULL_RESP packet.
+
+ Name | Type | Function
+:----:|:------:|------------------------------------------------------------------------------
+error | string | Indication about success or type of failure that occured for downlink request.
+
+The possible values of "error" field are:
+
+ Value | Definition
+:-----------------:|---------------------------------------------------------------------
+ NONE | Packet has been programmed for downlink
+ TOO_LATE | Rejected because it was already too late to program this packet for downlink
+ TOO_EARLY | Rejected because downlink packet timestamp is too much in advance
+ COLLISION_PACKET | Rejected because there was already a packet programmed in requested timeframe
+ COLLISION_BEACON | Rejected because there was already a beacon planned in requested timeframe
+ TX_FREQ | Rejected because requested frequency is not supported by TX RF chain
+ TX_POWER | Rejected because requested power is not supported by gateway
+ GPS_UNLOCKED | Rejected because GPS is unlocked, so GPS timestamp cannot be used
+
+Examples (white-spaces, indentation and newlines added for readability):
+
+``` json
+{"txpk_ack":{
+ "error":"COLLISION_PACKET"
+}}
+```
+
+7. Revisions
+-------------
+
+### v1.4 ###
+* Added "tmms" field for GPS time as a monotonic number of milliseconds
+ellapsed since January 6th, 1980 (GPS Epoch). No leap second.
+
+### v1.3 ###
+
+* Added downlink feedback from gateway to server (PULL_RESP -> TX_ACK)
+
+### v1.2 ###
+
+* Added value of FSK bitrate for upstream.
+* Added parameters for FSK bitrate and frequency deviation for downstream.
+
+### v1.1 ###
+
+* Added syntax for status report JSON object on upstream.
+
+### v1.0 ###
+
+* Initial version.