GatewayToBackend API: add otap target related changes (#127)

* GatewayToBackend API: add otap target related changes

Author: GwendalRaoul

gateway_to_backend/README.md

@@ -371,10 +371,24 @@ _Consequently, it is highly recommended to keep this field._
 
 - **Response:**
 
-    > **topics:** gw-response/otap_status/*\<gw-id\>/\<sink-id\>*
+    > **topics:** gw-response/otap_process_scratchpad/*\<gw-id\>/\<sink-id\>*
     >
     > **content:** [GenericMessage][message_GenericMessage].[WirepasMessage][message_WirepasMessage].[ProcessScratchpadResp][message_ProcessScratchpadResp]
 
+#### Set target scratchpad and action
+
+- **Request:**
+
+    > **topic:** gw-request/otap_set_target_scratchpad/*\<gw-id\>/\<sink-id\>*
+    >
+    > **content:** [GenericMessage][message_GenericMessage].[WirepasMessage][message_WirepasMessage].[SetScratchpadTargetAndActionReq][message_SetScratchpadTargetAndActionReq]
+
+- **Response:**
+
+    > **topics:** gw-response/otap_set_target_scratchpad/*\<gw-id\>/\<sink-id\>*
+    >
+    > **content:** [GenericMessage][message_GenericMessage].[WirepasMessage][message_WirepasMessage].[SetScratchpadTargetAndActionResp][message_SetScratchpadTargetAndActionResp]
+
 ## API extension
 
 This API is the minimal set of services to be integrated to be
@@ -501,6 +515,9 @@ definition)
     gw-request/otap_load_scratchpad/<gw-id>/<sink-id>
 
     gw-request/otap_process_scratchpad/<gw-id>/<sink-id>
+
+    gw-request/otap_set_target_scratchpad/<gw-id>/<sink-id>
+
 ```
 
 *Response* from a gateway to a backend:
@@ -519,6 +536,8 @@ definition)
     gw-response/otap_load_scratchpad/<gw-id>/<sink-id>
 
     gw-response/otap_process_scratchpad/<gw-id>/<sink-id>
+
+    gw-response/otap_set_target_scratchpad/<gw-id>/<sink-id>
 ```
 
 *Asynchronous* event from a gateway:
@@ -555,11 +574,6 @@ definition)
 
 [message_GetConfigsResp]: https://github.com/wirepas/backend-apis/blob/982974eb6069d89aef527862cb7b5f1b2e2c4385/gateway_to_backend/protocol_buffers_files/config_message.proto#L121-L125
 
-
-
-
-
-
 [message_SetConfigReq]: https://github.com/wirepas/backend-apis/blob/8580ee52eb71dbef3afce6b0207d3312153ced42/gateway_to_backend/protocol_buffers_files/config_message.proto#L127-L131
 
 [message_SetConfigResp]: https://github.com/wirepas/backend-apis/blob/8580ee52eb71dbef3afce6b0207d3312153ced42/gateway_to_backend/protocol_buffers_files/config_message.proto#L133-L138
@@ -592,4 +606,8 @@ definition)
 
 [message_WirepasMessage]: https://github.com/wirepas/backend-apis/blob/127f4a0025078aa7b118a6b10661461a50aaf33e/gateway_to_backend/protocol_buffers_files/generic_message.proto#L9-L26
 
+[message_SetScratchpadTargetAndActionReq]:
+
+[message_SetScratchpadTargetAndActionRsp]:
+
 [protobuf_homepage]: https://developers.google.com/protocol-buffers

gateway_to_backend/protocol_buffers_files/config_message.proto

@@ -98,9 +98,12 @@ message GatewayInfo {
     optional string gw_version = 3 /*[(nanopb).max_size = 128]*/;
 
     // API version implemented in the gateway
-    // This field must be explicitely set from code and must be
-    // the one defined in each released verion.
-    // Current version is 1
+    // This field must be explicitly set from code and must be
+    // the one defined in each released version.
+    // Current version is 2
+    // Version 1: Initial release
+    // Version 2: Addition of setScratchpadTargetAndAction
+    // It should be replaced by a feature list
     optional uint32 implemented_api_version = 4;
 }
 

gateway_to_backend/protocol_buffers_files/generic_message.proto

@@ -23,6 +23,8 @@ message WirepasMessage {
     optional ProcessScratchpadResp process_scratchpad_resp = 14;
     optional GetGwInfoReq get_gateway_info_req = 15;
     optional GetGwInfoResp get_gateway_info_resp = 16;
+    optional SetScratchpadTargetAndActionReq set_scratchpad_target_and_action_req = 17;
+    optional SetScratchpadTargetAndActionResp set_scratchpad_target_and_action_resp = 18;
 }
 
 message CustomerMessage {

gateway_to_backend/protocol_buffers_files/otap_message.proto

@@ -18,12 +18,49 @@ enum ScratchpadStatus {
     ERROR = 3;
 }
 
+enum ScratchpadAction {
+    // Will be the default value in case it is later extended
+    UNKNOWN_ACTION = 0;
+    // No propagation, no processing of scratchpad
+    NO_OTAP = 1;
+    // Propagate the target scratchpad but no processing
+    PROPAGATE_ONLY = 2;
+    // Propagate the target scratchpad and process it as soon as received
+    PROPAGATE_AND_PROCESS = 3;
+    // Propagate the target scratchpad and process it after delay (starting when scratchpad is present and this info received)
+    PROPAGATE_AND_PROCESS_WITH_DELAY = 4;
+    // Otap propagation works as before with sequence comparison and processing through remote API
+    LEGACY_OTAP = 5;
+}
+
+enum ProcessingDelay {
+    UNKNOWN_DELAY = 0;
+    TEN_MINUTES = 1;
+    THIRTY_MINUTES = 2;
+    ONE_HOUR = 3;
+    SIX_HOURS = 4;
+    ONE_DAY = 5;
+    TWO_DAYS = 6;
+    FIVE_DAYS = 7;
+}
+
+
 message ScratchpadInfo {
     required uint32 len = 1;
     required uint32 crc = 2;
     required uint32 seq = 3;
 }
 
+message TargetScratchpadAndAction {
+    required ScratchpadAction action = 1; // What is the action to perform with the current scratchpad
+    optional uint32 target_sequence = 2; // Between 1 and 254 (if missing using local scratchpad sequence if present)
+    optional uint32 target_crc = 3; // Between 0 and 0xffff (if missing using local scratchpad CRC if present)
+    oneof param {
+       ProcessingDelay delay = 4; // Delay parameter for action PROPAGATE_AND_PROCESS_WITH_DELAY
+       uint32 raw = 5; // Raw parameter for the action (between 0 and 255)
+    }
+}
+
 /*
  * Request/Responses definition
  */
@@ -39,6 +76,8 @@ message GetScratchpadStatusResp {
     optional ScratchpadType stored_type = 4;
     optional ScratchpadInfo processed_scratchpad = 5;
     optional uint32 firmware_area_id = 6;
+
+    optional TargetScratchpadAndAction target_and_action = 7; // Unset if sink doesn't support it
 }
 
 message UploadScratchpadReq {
@@ -60,3 +99,13 @@ message ProcessScratchpadReq {
 message ProcessScratchpadResp {
     required ResponseHeader header = 1;
 }
+
+message SetScratchpadTargetAndActionReq {
+    required RequestHeader header = 1;
+
+    required TargetScratchpadAndAction target_and_action = 2;
+}
+
+message SetScratchpadTargetAndActionResp {
+    required ResponseHeader header = 1;
+}