diff --git a/databroker/src/grpc/kuksa_val_v2/val.rs b/databroker/src/grpc/kuksa_val_v2/val.rs index 7f549cf5..7fc4476a 100644 --- 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>; + /// 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>,