LG-75 CDD API and optional feature flags

Author: sgunes-wirepas

gateway_to_backend/README.md

@@ -277,6 +277,56 @@ _Even if this version is increased, the API remains backward compatible.
 It just help backends development to identify if new features are
 present in a gateway._
 
+#### Set configuration data item
+
+Only processed if CONFIGURATION_DATA_V1 feature flag is set on the gateway.
+
+- **Request:**
+
+    > **topic:** gw-request/set_configuration_data_item/*\<gw-id\>/\<sink-id\>*
+    >
+    > **content:** [GenericMessage][message_GenericMessage].[WirepasMessage][message_WirepasMessage].SetConfigurationDataItemReq
+
+- **Response:**
+
+    > **topics:** gw-response/set_configuration_data_item/*\<gw-id\>/\<sink-id\>*
+    >
+    > **content:** [GenericMessage][message_GenericMessage].[WirepasMessage][message_WirepasMessage].SetConfigurationDataItemResp
+    >
+    > **possible errors:**
+    > - INVALID_ROLE: Node is not a sink.
+    > - SINK_OUT_OF_MEMORY: Payload is too large or maximum number of items is reached.
+    > - INVALID_DEST_ENDPOINT: Endpoint is too large (it should be a 16 bit unsigned integer).
+    > - INVALID_DATA_PAYLOAD: Payload is rejected for this endpoint by the sink.
+    > - INVALID_SINK_ID: Invalid sink id in the request header.
+
+:warning:
+
+_Successfully setting an item must be treated as a configuration change on the
+sink, meaning that the gateway must report the new complete configuration data
+content by generating a new [StatusEvent][message_StatusEvent] message._
+
+#### Get configuration data item
+
+Only processed if CONFIGURATION_DATA_V1 feature flag is set on the gateway.
+
+- **Request:**
+
+    > **topic:** gw-request/get_configuration_data_item/*\<gw-id\>/\<sink-id\>*
+    >
+    > **content:** [GenericMessage][message_GenericMessage].[WirepasMessage][message_WirepasMessage].GetConfigurationDataItemReq
+
+- **Response:**
+
+    > **topics:** gw-response/get_configuration_data_item/*\<gw-id\>/\<sink-id\>*
+    >
+    > **content:** [GenericMessage][message_GenericMessage].[WirepasMessage][message_WirepasMessage].GetConfigurationDataItemResp
+    >
+    > **possible errors:**
+    > - INVALID_DEST_ENDPOINT: Endpoint is too large (it should be a 16 bit unsigned integer).
+    > - INVALID_PARAM: No item found with the given endpoint.
+    > - INVALID_SINK_ID: Invalid sink id in the request header.
+
 ### Data module
 
 ---
@@ -518,6 +568,9 @@ definition)
 
     gw-request/otap_set_target_scratchpad/<gw-id>/<sink-id>
 
+    gw-request/set_configuration_data_item/<gw-id>/<sink-id>
+
+    gw-request/get_configuration_data_item/<gw-id>/<sink-id>
 ```
 
 *Response* from a gateway to a backend:
@@ -538,6 +591,10 @@ definition)
     gw-response/otap_process_scratchpad/<gw-id>/<sink-id>
 
     gw-response/otap_set_target_scratchpad/<gw-id>/<sink-id>
+
+    gw-response/set_configuration_data_item/<gw-id>/<sink-id>
+
+    gw-response/get_configuration_data_item/<gw-id>/<sink-id>
 ```
 
 *Asynchronous* event from a gateway:
@@ -591,4 +648,13 @@ definition)
 
 [message_SetScratchpadTargetAndActionResp]: https://github.com/wirepas/backend-apis/blob/77d83cc91ccfede5e457a488f0611f1fed342585/gateway_to_backend/protocol_buffers_files/otap_message.proto#L54-L56
 
+<!-- TODO update links and take them into use once they are available in the master branch -->
+<!-- [message_SetConfigurationDataItemReq]: -->
+<!---->
+<!-- [message_SetConfigurationDataItemResp]: -->
+<!---->
+<!-- [message_GetConfigurationDataItemReq]: -->
+<!---->
+<!-- [message_GetConfigurationDataItemResp]: -->
+
 [protobuf_homepage]: https://developers.google.com/protocol-buffers

gateway_to_backend/protocol_buffers_files/config_message.proto

@@ -39,6 +39,11 @@ message NetworkKeys {
     required bytes authentication = 2;
 }
 
+message ConfigurationDataItem {
+    required uint32 endpoint = 1;
+    required bytes payload = 2;
+}
+
 message SinkReadConfig {
     // Local id to uniquely identify a sink on gateway
     required string sink_id = 1;
@@ -72,6 +77,9 @@ message SinkReadConfig {
     optional ScratchpadInfo processed_scratchpad = 21;
     optional uint32 firmware_area_id = 22;
     optional TargetScratchpadAndAction target_and_action = 23; // Unset if sink doesn't support it
+
+    // Only present if CDD_API feature flag is set
+    repeated ConfigurationDataItem configuration_data_content = 24;
 }
 
 message SinkNewConfig {
@@ -118,6 +126,8 @@ message GatewayInfo {
     // it must be sent as chunk. If not set, it means that
     // scratchpad can be sent in a single request
     optional uint32 max_scratchpad_size = 5;
+
+    repeated GatewayFeature gw_features = 6;
 }
 
 /*
@@ -146,6 +156,8 @@ message GatewayInfo {
 
     // See GatewayInfo for details of this field
     optional uint32 max_scratchpad_size = 7;
+
+    repeated GatewayFeature gw_features = 8;
 }
 
 message GetConfigsReq {
@@ -180,3 +192,26 @@ message GetGwInfoResp {
 
     required GatewayInfo info = 2;
 }
+
+message SetConfigurationDataItemReq {
+    required RequestHeader header = 1;
+
+    // 0-length payloads are used to clear an entry
+    required ConfigurationDataItem configuration_data_item = 2;
+}
+
+message SetConfigurationDataItemResp {
+    required ResponseHeader header = 1;
+}
+
+message GetConfigurationDataItemReq {
+    required RequestHeader header = 1;
+
+    required uint32 endpoint = 2;
+}
+
+message GetConfigurationDataItemResp {
+    required ResponseHeader header = 1;
+
+    optional ConfigurationDataItem configuration_data_item = 2;
+}

gateway_to_backend/protocol_buffers_files/generic_message.proto

@@ -25,6 +25,10 @@ message WirepasMessage {
     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;
+    optional SetConfigurationDataItemReq set_configuration_data_item_req = 19;
+    optional SetConfigurationDataItemResp set_configuration_data_item_resp = 20;
+    optional GetConfigurationDataItemReq get_configuration_data_item_req = 21;
+    optional GetConfigurationDataItemResp get_configuration_data_item_resp = 22;
 }
 
 message CustomerMessage {
@@ -36,4 +40,4 @@ message CustomerMessage {
 message GenericMessage {
     optional WirepasMessage wirepas = 1;
     optional CustomerMessage customer = 2;
-}
+}

gateway_to_backend/protocol_buffers_files/wp_global.proto

@@ -103,4 +103,14 @@ message TargetScratchpadAndAction {
        ProcessingDelay delay = 4; // Delay parameter for action PROPAGATE_AND_PROCESS_WITH_DELAY
        uint32 raw = 5; // Raw parameter for the action (between 0 and 255)
     }
-}
+}
+
+enum GatewayFeature {
+    UNKNOWN = 0;
+    // Support for uploading a scratchpad in chunks
+    SCRATCHPAD_CHUNK_V1 = 1;
+    // Configuration Data Distribution API, allows modifying of the
+    // configuration data content.
+    CONFIGURATION_DATA_V1 = 2;
+}
+