v3.0.0

* 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" 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.

Author: mcoracin

Makefile

@@ -8,17 +8,13 @@ export
 ### general build targets
 
 all:
-	$(MAKE) all -e -C basic_pkt_fwd
-	$(MAKE) all -e -C gps_pkt_fwd
-	$(MAKE) all -e -C beacon_pkt_fwd
+	$(MAKE) all -e -C lora_pkt_fwd
 	$(MAKE) all -e -C util_ack
 	$(MAKE) all -e -C util_sink
 	$(MAKE) all -e -C util_tx_test
 
 clean:
-	$(MAKE) clean -e -C basic_pkt_fwd
-	$(MAKE) clean -e -C gps_pkt_fwd
-	$(MAKE) clean -e -C beacon_pkt_fwd
+	$(MAKE) clean -e -C lora_pkt_fwd
 	$(MAKE) clean -e -C util_ack
 	$(MAKE) clean -e -C util_sink
 	$(MAKE) clean -e -C util_tx_test

PROTOCOL.TXT

@@ -96,7 +96,7 @@ received, and associated metadata, to the server.
 
  Bytes  | Function
 :------:|---------------------------------------------------------------------
- 0      | protocol version = 1
+ 0      | protocol version = 2
  1-2    | random token
  3      | PUSH_DATA identifier 0x00
  4-11   | Gateway unique identifier (MAC address)
@@ -109,7 +109,7 @@ PUSH_DATA packets received.
 
  Bytes  | Function
 :------:|---------------------------------------------------------------------
- 0      | protocol version = 1
+ 0      | protocol version = 2
  1-2    | same token as the PUSH_DATA packet to acknowledge
  3      | PUSH_ACK identifier 0x01
 
@@ -269,9 +269,11 @@ Example (white-spaces, indentation and newlines added for readability):
 	     |      | Anytime after first PULL_DATA for each packet to TX |-|
 	     |      ------------------------------------------------------- |
 	     |                                                              |
-	     |                            PULL_RESP (token 0, JSON payload) |
+	     |                            PULL_RESP (token Z, JSON payload) |
 	     |<-------------------------------------------------------------|
 	     |                                                              |
+	     | TX_ACK (token Z, JSON payload)                               |
+	     |------------------------------------------------------------->|
 
 ### 5.2. PULL_DATA packet ###
 
@@ -288,7 +290,7 @@ route stays open for the server to be used at any time.
 
  Bytes  | Function
 :------:|---------------------------------------------------------------------
- 0      | protocol version = 1
+ 0      | protocol version = 2
  1-2    | random token
  3      | PULL_DATA identifier 0x02
  4-11   | Gateway unique identifier (MAC address)
@@ -300,7 +302,7 @@ open and that the server can send PULL_RESP packets at any time.
 
  Bytes  | Function
 :------:|---------------------------------------------------------------------
- 0      | protocol version = 1
+ 0      | protocol version = 2
  1-2    | same token as the PULL_DATA packet to acknowledge
  3      | PULL_ACK identifier 0x04
 
@@ -311,16 +313,30 @@ metadata that will have to be emitted by the gateway.
 
  Bytes  | Function
 :------:|---------------------------------------------------------------------
- 0      | protocol version = 1
- 1-2    | unused bytes
+ 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-end  | [optional] JSON object, starting with {, ending with }, see section 6
 
 6. Downstream JSON data structure
 ----------------------------------
 
-The root object must contain an object named "txpk":
+The root object of PULL_RESP packet must contain an object named "txpk":
 
 ``` json
 {
@@ -383,10 +399,48 @@ Examples (white-spaces, indentation and newlines added for readability):
 }}
 ```
 
+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.3 ###
+
+* Added downlink feedback from gateway to server (PULL_RESP -> TX_ACK)
+
 ### v1.2 ###
 
 * Added value of FSK bitrate for upstream.

VERSION

@@ -1 +1 @@
-2.2.1
+3.0.0