Initial commit

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.