Add service method documentation

SoftwareDefinedVehicle · Jul 25, 2024 · f5f3629 · f5f3629
1 parent 5116fe6
commit f5f3629
Showing 1 changed file with 95 additions and 0 deletions.
diff --git a/databroker/src/grpc/kuksa_val_v2/val.rs b/databroker/src/grpc/kuksa_val_v2/val.rs
@@ -112,6 +112,101 @@ impl proto::val_server::Val for broker::DataBroker {
     type OpenProviderStreamStream =
         ReceiverStream<Result<proto::OpenProviderStreamResponse, tonic::Status>>;
 
+    /// Opens a bidirectional stream with the databroker to perform various actions such as
+    /// providing actuators, publishing sensor and actuator values, and receiving actuations from the databroker.
+    ///
+    /// # Actions
+    ///
+    /// The function handles the following actions:
+    ///
+    /// 1. **Provide an Actuator**:
+    ///    - The provider claims ownership of the actuator with the specified signal ID.
+    ///
+    ///      ```
+    ///     `request`:
+    ///      OpenProviderStreamRequest {
+    ///          action: ProvidedActuation {
+    ///              {
+    ///                  signal: id: 30,
+    ///              },
+    ///              {
+    ///                  signal: id: 45,
+    ///              },
+    ///              ...
+    ///          }
+    ///      }
+    ///
+    ///      `response`:
+    ///      OpenProviderStreamStream {
+    ///          action: ProvideActuatorResponse { }
+    ///      }
+    ///      ```
+    ///
+    /// 2. **Publish Values**:
+    ///    - The provider publishes a request ID along with a map of sensor and actuator values.
+    ///
+    ///      ```
+    ///     `request`:
+    ///      OpenProviderStreamRequest {
+    ///          action: PublishValuesRequest {
+    ///              request_id: 1,
+    ///              datapoints: {
+    ///                  (30, Datapoint),
+    ///                  (45, Datapoint),
+    ///                  ...
+    ///              }
+    ///          }
+    ///      }
+    ///
+    ///      `response`:
+    ///      OpenProviderStreamStream {
+    ///          action: PublishValuesResponse {
+    ///              request_id: 1,
+    ///              status: {
+    ///                  (If errors) {
+    ///                      (30, Error),
+    ///                      (45, Error),
+    ///                      ...
+    ///                  }
+    ///              }
+    ///          }
+    ///      }
+    ///      ```
+    ///
+    /// 3. **Receive Actuations**:
+    ///    - The provider receives actuation requests from the databroker.
+    ///
+    ///      ```
+    ///     `request`:
+    ///      OpenProviderStreamRequest {
+    ///          action: BatchActuateStreamResponse { }
+    ///      }
+    ///
+    ///      `response`:
+    ///      OpenProviderStreamStream {
+    ///          action: BatchActuateStreamRequest {
+    ///              actuate_requests: {
+    ///                  (30, Value),
+    ///                  (45, Value),
+    ///                  ...
+    ///              }
+    ///          }
+    ///      }
+    ///      ```
+    ///
+    /// # Arguments
+    ///
+    /// * `request` - The request should contain the necessary permissions if the databroker is started with secure mode.
+    ///   The request `OpenProviderStreamRequest` can contain messages according to the action:
+    ///   - Action 1: `ProvidedActuation`
+    ///   - Action 2: `PublishValuesRequest`
+    ///   - Action 3: `BatchActuateStreamResponse`
+    ///
+    /// # Errors
+    ///
+    /// The open stream is used for request / response type communication between the
+    /// provider and server (where the initiator of a request can vary).
+    /// Errors are communicated as messages in the stream.
     async fn open_provider_stream(
         &self,
         request: tonic::Request<tonic::Streaming<proto::OpenProviderStreamRequest>>,