From 75b440f65c3fe8babd3edad6380a6cdb1d6f711d Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Thu, 16 May 2024 11:55:40 +0200 Subject: [PATCH 01/21] Init Databroker API V2 --- proto/kuksa/val/v2/types.proto | 274 +++++++++++++++++++++++++++++++++ proto/kuksa/val/v2/val.proto | 100 ++++++++++++ 2 files changed, 374 insertions(+) create mode 100644 proto/kuksa/val/v2/types.proto create mode 100644 proto/kuksa/val/v2/val.proto diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto new file mode 100644 index 00000000..4db8d2cd --- /dev/null +++ b/proto/kuksa/val/v2/types.proto @@ -0,0 +1,274 @@ +/******************************************************************************** + * Copyright (c) 2022 Contributors to the Eclipse Foundation + * + * See the NOTICE file(s) distributed with this work for additional + * information regarding copyright ownership. + * + * This program and the accompanying materials are made available under the + * terms of the Apache License 2.0 which is available at + * http://www.apache.org/licenses/LICENSE-2.0 + * + * SPDX-License-Identifier: Apache-2.0 + ********************************************************************************/ + +syntax = "proto3"; + +package kuksa.val.v2; +import "google/protobuf/timestamp.proto"; + +option go_package = "kuksa/val/v2"; + +// Define which data we want +message EntryRequest { + string path = 1; + EntryType entry_type = 2; +} + +// Define the data we want to set +message EntryUpdate { + DataEntry entry = 1; +} + +message DataEntry { + // Defines the full VSS path of the entry. + string path = 1; + + // The value (datapoint) + Datapoint value = 2; + + EntryType entry_type = 3; +} + +message Datapoint { + google.protobuf.Timestamp timestamp = 1; + + oneof value { + string string = 11; + bool bool = 12; + sint32 int32 = 13; + sint64 int64 = 14; + uint32 uint32 = 15; + uint64 uint64 = 16; + float float = 17; + double double = 18; + StringArray string_array = 21; + BoolArray bool_array = 22; + Int32Array int32_array = 23; + Int64Array int64_array = 24; + Uint32Array uint32_array = 25; + Uint64Array uint64_array = 26; + FloatArray float_array = 27; + DoubleArray double_array = 28; + } +} + +message Metadata { + // Data type + // The VSS data type of the entry (i.e. the value, min, max etc). + // + // NOTE: protobuf doesn't have int8, int16, uint8 or uint16 which means + // that these values must be serialized as int32 and uint32 respectively. + DataType data_type = 11; // [field: FIELD_METADATA_DATA_TYPE] + + // Entry type + EntryType entry_type = 12; // [field: FIELD_METADATA_ENTRY_TYPE] + + // Description + // Describes the meaning and content of the entry. + optional string description = 13; // [field: FIELD_METADATA_DESCRIPTION] + + // Comment [optional] + // A comment can be used to provide additional informal information + // on a entry. + optional string comment = 14; // [field: FIELD_METADATA_COMMENT] + + // Deprecation [optional] + // Whether this entry is deprecated. Can contain recommendations of what + // to use instead. + optional string deprecation = 15; // [field: FIELD_METADATA_DEPRECATION] + + // Unit [optional] + // The unit of measurement + optional string unit = 16; // [field: FIELD_METADATA_UNIT] + + // Value restrictions [optional] + // Restrict which values are allowed. + // Only restrictions matching the DataType {datatype} above are valid. + ValueRestriction value_restriction = 17; // [field: FIELD_METADATA_VALUE_RESTRICTION] + + // Entry type specific metadata + oneof entry_specific { + Actuator actuator = 20; // [field: FIELD_METADATA_ACTUATOR] + Sensor sensor = 30; // [field: FIELD_METADATA_SENSOR] + Attribute attribute = 40; // [field: FIELD_METADATA_ATTRIBUTE] + } +} + +/////////////////////// +// Actuator specific fields +message Actuator { + // Nothing for now +} + +//////////////////////// +// Sensor specific +message Sensor { + // Nothing for now +} + +//////////////////////// +// Attribute specific +message Attribute { + // Nothing for now. +} + +// Value restriction +// +// One ValueRestriction{type} for each type, since +// they don't make sense unless the types match +// +message ValueRestriction { + oneof type { + ValueRestrictionString string = 21; + // For signed VSS integers + ValueRestrictionInt signed = 22; + // For unsigned VSS integers + ValueRestrictionUint unsigned = 23; + // For floating point VSS values (float and double) + ValueRestrictionFloat floating_point = 24; + } +} + +message ValueRestrictionInt { + optional sint64 min = 1; + optional sint64 max = 2; + repeated sint64 allowed_values = 3; +} + +message ValueRestrictionUint { + optional uint64 min = 1; + optional uint64 max = 2; + repeated uint64 allowed_values = 3; +} + +message ValueRestrictionFloat { + optional double min = 1; + optional double max = 2; + + // allowed for doubles/floats not recommended + repeated double allowed_values = 3; +} + +// min, max doesn't make much sense for a string +message ValueRestrictionString { + repeated string allowed_values = 3; +} + +// VSS Data type of a signal +// +// Protobuf doesn't support int8, int16, uint8 or uint16. +// These are mapped to int32 and uint32 respectively. +// +enum DataType { + DATA_TYPE_UNSPECIFIED = 0; + DATA_TYPE_STRING = 1; + DATA_TYPE_BOOLEAN = 2; + DATA_TYPE_INT8 = 3; + DATA_TYPE_INT16 = 4; + DATA_TYPE_INT32 = 5; + DATA_TYPE_INT64 = 6; + DATA_TYPE_UINT8 = 7; + DATA_TYPE_UINT16 = 8; + DATA_TYPE_UINT32 = 9; + DATA_TYPE_UINT64 = 10; + DATA_TYPE_FLOAT = 11; + DATA_TYPE_DOUBLE = 12; + DATA_TYPE_TIMESTAMP = 13; + DATA_TYPE_STRING_ARRAY = 20; + DATA_TYPE_BOOLEAN_ARRAY = 21; + DATA_TYPE_INT8_ARRAY = 22; + DATA_TYPE_INT16_ARRAY = 23; + DATA_TYPE_INT32_ARRAY = 24; + DATA_TYPE_INT64_ARRAY = 25; + DATA_TYPE_UINT8_ARRAY = 26; + DATA_TYPE_UINT16_ARRAY = 27; + DATA_TYPE_UINT32_ARRAY = 28; + DATA_TYPE_UINT64_ARRAY = 29; + DATA_TYPE_FLOAT_ARRAY = 30; + DATA_TYPE_DOUBLE_ARRAY = 31; + DATA_TYPE_TIMESTAMP_ARRAY = 32; +} + +// Entry type +enum EntryType { + ENTRY_TYPE_UNSPECIFIED = 0; + ENTRY_TYPE_ATTRIBUTE = 1; + ENTRY_TYPE_SENSOR = 2; + ENTRY_TYPE_ACTUATOR = 3; +} + +// A `Field` corresponds to a specific field of a `DataEntry`. +// +// It can be used to: +// * populate only specific fields of a `DataEntry` response. +// * specify which fields of a `DataEntry` should be set as +// part of a `Set` request. +// * subscribe to only specific fields of a data entry. +// * convey which fields of an updated `DataEntry` have changed. +enum Field { + FIELD_UNSPECIFIED = 0; // "*" i.e. everything + FIELD_PATH = 1; // path + FIELD_VALUE = 2; // value + FIELD_ACTUATOR_TARGET = 3; // actuator_target + FIELD_METADATA = 10; // metadata.* + FIELD_METADATA_DATA_TYPE = 11; // metadata.data_type + FIELD_METADATA_DESCRIPTION = 12; // metadata.description + FIELD_METADATA_ENTRY_TYPE = 13; // metadata.entry_type + FIELD_METADATA_COMMENT = 14; // metadata.comment + FIELD_METADATA_DEPRECATION = 15; // metadata.deprecation + FIELD_METADATA_UNIT = 16; // metadata.unit + FIELD_METADATA_VALUE_RESTRICTION = 17; // metadata.value_restriction.* + FIELD_METADATA_ACTUATOR = 20; // metadata.actuator.* + FIELD_METADATA_SENSOR = 30; // metadata.sensor.* + FIELD_METADATA_ATTRIBUTE = 40; // metadata.attribute.* +} + +// Error response shall be an HTTP-like code. +// Should follow https://www.w3.org/TR/viss2-transport/#status-codes. +message Error { + uint32 code = 1; + string reason = 2; + string message = 3; +} + +message StringArray { + repeated string values = 1; +} + +message BoolArray { + repeated bool values = 1; +} + +message Int32Array { + repeated sint32 values = 1; +} + +message Int64Array { + repeated sint64 values = 1; +} + +message Uint32Array { + repeated uint32 values = 1; +} + +message Uint64Array { + repeated uint64 values = 1; +} + +message FloatArray { + repeated float values = 1; +} + +message DoubleArray { + repeated double values = 1; +} diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto new file mode 100644 index 00000000..bdee1afc --- /dev/null +++ b/proto/kuksa/val/v2/val.proto @@ -0,0 +1,100 @@ +/******************************************************************************** + * Copyright (c) 2022 Contributors to the Eclipse Foundation + * + * See the NOTICE file(s) distributed with this work for additional + * information regarding copyright ownership. + * + * This program and the accompanying materials are made available under the + * terms of the Apache License 2.0 which is available at + * http://www.apache.org/licenses/LICENSE-2.0 + * + * SPDX-License-Identifier: Apache-2.0 + ********************************************************************************/ + +syntax = "proto3"; + +package kuksa.val.v2; + +option go_package = "kuksa/val/v2"; + +import "types.proto"; + +// Note on authorization: +// Tokens (auth-token or auth-uuid) are sent as (GRPC / http2) metadata. +// +// The auth-token is a JWT compliant token as the examples found here: +// https://github.com/eclipse-kuksa/kuksa-databroker/tree/main/certificates/jwt +// +// See also https://github.com/eclipse-kuksa/kuksa-databroker/blob/main/doc/authorization.md#jwt-access-token +// +// Upon reception of auth-token, server shall generate an auth-uuid in metadata +// that the client can use instead of auth-token in subsequent calls. + +service VAL { + // get current value of attributes, sensors and actuators + rpc Get(GetRequest) returns (GetResponse); + + // provide current value of attributes, sensors and actuator - for low update frequency + rpc ProvideOnce(ProviceOnceRequest) returns (ProvideOnceResponse); + + // provide stream of current values of attributes, sensors and actuator - for high frequency + // return stream of ACK + rpc ProvideStream(stream ProvideStreamRequest) returns (stream ProvideStreamResponse); + + // actuate on actuator value + rpc Actuate(ActuateRequest) returns (ActuateResponse); + + //get static metadata + rpc GetMetadata(MetadataRequest) returns (MetadataResponse); + + rpc GetServerInfo(GetServerInfoRequest) returns (GetServerInfoResponse); +} + +// Request a set of entries. +message GetRequest { + repeated EntryRequest entries = 1; +} + +message GetResponse { + repeated DataEntry entries = 1; +} + +message ProviceOnceRequest { + repeated EntryUpdate updates = 1; +} + +message ProvideOnceResponse { +} + +message ProvideStreamRequest { + repeated EntryUpdate updates = 1; +} + +message ProvideStreamResponse { + bool update_received = 1; +} + +message ActuateRequest { + EntryUpdate actuator = 1; +} + +message ActuateResponse { +} + +message MetadataRequest { + repeated string path = 1; +} + +message MetadataResponse { + repeated Metadata metadata = 1; + repeated Field fields = 2; +} + +message GetServerInfoRequest { + // Nothing yet +} + +message GetServerInfoResponse { + string name = 1; + string version = 2; +} From 2e103a619e12a0739e61bfe10b7c209d8d3ec521 Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Tue, 21 May 2024 13:46:19 +0200 Subject: [PATCH 02/21] Added oneof to Datapoint and some changes --- proto/kuksa/val/v2/types.proto | 59 +++++++++++++--------------------- proto/kuksa/val/v2/val.proto | 45 ++++++++++++++++++++++---- 2 files changed, 60 insertions(+), 44 deletions(-) diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto index 4db8d2cd..055e54af 100644 --- a/proto/kuksa/val/v2/types.proto +++ b/proto/kuksa/val/v2/types.proto @@ -21,28 +21,25 @@ option go_package = "kuksa/val/v2"; // Define which data we want message EntryRequest { string path = 1; - EntryType entry_type = 2; -} - -// Define the data we want to set -message EntryUpdate { - DataEntry entry = 1; } message DataEntry { // Defines the full VSS path of the entry. string path = 1; - - // The value (datapoint) - Datapoint value = 2; - - EntryType entry_type = 3; + Datapoint datapoint = 2; } message Datapoint { google.protobuf.Timestamp timestamp = 1; - oneof value { + oneof state { + Failure failure = 2; + Value value = 3; + } +} + +message Value { + oneof typed_value { string string = 11; bool bool = 12; sint32 int32 = 13; @@ -62,6 +59,19 @@ message Datapoint { } } +enum Failure { + // The data point is known, but doesn't have a valid value + INVALID_VALUE = 0; + // The data point is known, but no value is available + NOT_AVAILABLE = 1; + // Unknown datapoint + UNKNOWN_DATAPOINT = 2; + // Access denied + ACCESS_DENIED = 3; + // Unexpected internal error + INTERNAL_ERROR = 4; +} + message Metadata { // Data type // The VSS data type of the entry (i.e. the value, min, max etc). @@ -95,31 +105,6 @@ message Metadata { // Restrict which values are allowed. // Only restrictions matching the DataType {datatype} above are valid. ValueRestriction value_restriction = 17; // [field: FIELD_METADATA_VALUE_RESTRICTION] - - // Entry type specific metadata - oneof entry_specific { - Actuator actuator = 20; // [field: FIELD_METADATA_ACTUATOR] - Sensor sensor = 30; // [field: FIELD_METADATA_SENSOR] - Attribute attribute = 40; // [field: FIELD_METADATA_ATTRIBUTE] - } -} - -/////////////////////// -// Actuator specific fields -message Actuator { - // Nothing for now -} - -//////////////////////// -// Sensor specific -message Sensor { - // Nothing for now -} - -//////////////////////// -// Attribute specific -message Attribute { - // Nothing for now. } // Value restriction diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index bdee1afc..48f18645 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -17,7 +17,7 @@ package kuksa.val.v2; option go_package = "kuksa/val/v2"; -import "types.proto"; +import "kuksa/val/v2/types.proto"; // Note on authorization: // Tokens (auth-token or auth-uuid) are sent as (GRPC / http2) metadata. @@ -35,12 +35,15 @@ service VAL { rpc Get(GetRequest) returns (GetResponse); // provide current value of attributes, sensors and actuator - for low update frequency - rpc ProvideOnce(ProviceOnceRequest) returns (ProvideOnceResponse); + rpc ProvideOnce(ProvideOnceRequest) returns (ProvideOnceResponse); // provide stream of current values of attributes, sensors and actuator - for high frequency // return stream of ACK rpc ProvideStream(stream ProvideStreamRequest) returns (stream ProvideStreamResponse); + // subscribe to sensor and actuator values + rpc Subscribe(SubscribeRequest) returns (stream SubscribeResponse); + // actuate on actuator value rpc Actuate(ActuateRequest) returns (ActuateResponse); @@ -59,35 +62,63 @@ message GetResponse { repeated DataEntry entries = 1; } -message ProviceOnceRequest { - repeated EntryUpdate updates = 1; +/** +Option 2 for GetResponse: + +message GetResponse { + map entries = 1; +} + +**/ + + +message ProvideOnceRequest { + repeated DataEntry updates = 1; } message ProvideOnceResponse { } message ProvideStreamRequest { - repeated EntryUpdate updates = 1; + repeated DataEntry updates = 1; } message ProvideStreamResponse { bool update_received = 1; } +message SubscribeRequest { + repeated EntryRequest entries = 1; +} + +message SubscribeResponse { + repeated DataEntry entries = 1; +} + message ActuateRequest { - EntryUpdate actuator = 1; + repeated DataEntry actuators = 1; +} + +/** +Option 2 for ActuateRequest: + +message GetResponse { + map entries = 1; } +**/ + message ActuateResponse { + bool update_forwarded = 1; } message MetadataRequest { repeated string path = 1; + repeated Field fields = 2; } message MetadataResponse { repeated Metadata metadata = 1; - repeated Field fields = 2; } message GetServerInfoRequest { From c01314a176759445f197018232a41fff90d761c7 Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Tue, 28 May 2024 09:24:23 +0200 Subject: [PATCH 03/21] Rename oneof Datapoint --- proto/kuksa/val/v2/types.proto | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto index 055e54af..ed31637e 100644 --- a/proto/kuksa/val/v2/types.proto +++ b/proto/kuksa/val/v2/types.proto @@ -32,8 +32,8 @@ message DataEntry { message Datapoint { google.protobuf.Timestamp timestamp = 1; - oneof state { - Failure failure = 2; + oneof data { + ValueMissing not_available = 2; Value value = 3; } } @@ -59,7 +59,7 @@ message Value { } } -enum Failure { +enum ValueMissing { // The data point is known, but doesn't have a valid value INVALID_VALUE = 0; // The data point is known, but no value is available From 50ca9a46ab60a5449cac4f3c1da2b460f4d0cf42 Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Tue, 28 May 2024 09:38:02 +0200 Subject: [PATCH 04/21] Add oneof for Stream Provider response --- proto/kuksa/val/v2/types.proto | 8 ++++++++ proto/kuksa/val/v2/val.proto | 11 ++++++++++- 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto index ed31637e..aa8d8fe0 100644 --- a/proto/kuksa/val/v2/types.proto +++ b/proto/kuksa/val/v2/types.proto @@ -72,6 +72,14 @@ enum ValueMissing { INTERNAL_ERROR = 4; } +message ActuateCommand { + +} + +message SensorCommand { + +} + message Metadata { // Data type // The VSS data type of the entry (i.e. the value, min, max etc). diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 48f18645..0f4696b5 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -77,6 +77,10 @@ message ProvideOnceRequest { } message ProvideOnceResponse { + oneof action { + bool ack_update_received = 1; + Error error = 2; + } } message ProvideStreamRequest { @@ -84,7 +88,12 @@ message ProvideStreamRequest { } message ProvideStreamResponse { - bool update_received = 1; + oneof action { + ActuateCommand actuator_command = 1; + SensorCommand sensor_command = 2; + bool ack_update_received = 3; + Error error = 4; + } } message SubscribeRequest { From ce1351604480da631ded543b289f442c992299bc Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Wed, 29 May 2024 11:16:31 +0200 Subject: [PATCH 05/21] Update provide stream response and add files to the build project --- databroker-proto/build.rs | 2 ++ proto/kuksa/val/v2/types.proto | 9 +++++++-- proto/kuksa/val/v2/val.proto | 8 ++++---- 3 files changed, 13 insertions(+), 6 deletions(-) diff --git a/databroker-proto/build.rs b/databroker-proto/build.rs index d02a006d..9d21cfe0 100644 --- a/databroker-proto/build.rs +++ b/databroker-proto/build.rs @@ -23,6 +23,8 @@ fn main() -> Result<(), Box> { "proto/sdv/databroker/v1/collector.proto", "proto/kuksa/val/v1/val.proto", "proto/kuksa/val/v1/types.proto", + "proto/kuksa/val/v2/types.proto", + "proto/kuksa/val/v2/val.proto" ], &["proto"], )?; diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto index aa8d8fe0..02b8e838 100644 --- a/proto/kuksa/val/v2/types.proto +++ b/proto/kuksa/val/v2/types.proto @@ -72,12 +72,17 @@ enum ValueMissing { INTERNAL_ERROR = 4; } +message DataUpdate { + string path = 1; + Value value = 2; +} + message ActuateCommand { - + repeated DataUpdate updates = 1; } message SensorCommand { - + repeated DataUpdate updates = 1; } message Metadata { diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 0f4696b5..b38bb623 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -73,7 +73,7 @@ message GetResponse { message ProvideOnceRequest { - repeated DataEntry updates = 1; + repeated DataUpdate updates = 1; } message ProvideOnceResponse { @@ -84,14 +84,14 @@ message ProvideOnceResponse { } message ProvideStreamRequest { - repeated DataEntry updates = 1; + repeated DataUpdate updates = 1; } message ProvideStreamResponse { oneof action { ActuateCommand actuator_command = 1; SensorCommand sensor_command = 2; - bool ack_update_received = 3; + bool ack_command = 3; Error error = 4; } } @@ -105,7 +105,7 @@ message SubscribeResponse { } message ActuateRequest { - repeated DataEntry actuators = 1; + repeated DataUpdate actuators = 1; } /** From 32c79d8f08f92638b83518faaa51fea90a7c7e37 Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Fri, 31 May 2024 17:11:42 +0200 Subject: [PATCH 06/21] Update ProvideStream and Actuate calls --- proto/kuksa/val/v2/types.proto | 38 ++++++++++++++++++++++++++++------ proto/kuksa/val/v2/val.proto | 33 +++++++++++++++++++---------- 2 files changed, 54 insertions(+), 17 deletions(-) diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto index 02b8e838..8d174f82 100644 --- a/proto/kuksa/val/v2/types.proto +++ b/proto/kuksa/val/v2/types.proto @@ -33,7 +33,7 @@ message Datapoint { google.protobuf.Timestamp timestamp = 1; oneof data { - ValueMissing not_available = 2; + DatapointStatus not_available = 2; Value value = 3; } } @@ -59,7 +59,7 @@ message Value { } } -enum ValueMissing { +enum DatapointStatus { // The data point is known, but doesn't have a valid value INVALID_VALUE = 0; // The data point is known, but no value is available @@ -72,17 +72,43 @@ enum ValueMissing { INTERNAL_ERROR = 4; } -message DataUpdate { +message DatapointUpdate { string path = 1; Value value = 2; } message ActuateCommand { - repeated DataUpdate updates = 1; + string uuid = 1; + repeated DatapointUpdate updates = 2; } -message SensorCommand { - repeated DataUpdate updates = 1; +message ActuateCommandResponse { + string uuid = 1; + bool ack_action_received = 3; +} + + +message Start { + optional uint64 update_interval_ms = 1; +} + +message Stop { + +} + +message SignalCommand { + string uuid = 1; + string path = 2; + + oneof signal_behaviour { + Start start = 3; + Stop stop = 4; + } +} + +enum SignalAction { + START = 0; + STOP = 1; } message Metadata { diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index b38bb623..33aa3d87 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -17,7 +17,7 @@ package kuksa.val.v2; option go_package = "kuksa/val/v2"; -import "kuksa/val/v2/types.proto"; +import "types.proto"; // Note on authorization: // Tokens (auth-token or auth-uuid) are sent as (GRPC / http2) metadata. @@ -73,7 +73,7 @@ message GetResponse { message ProvideOnceRequest { - repeated DataUpdate updates = 1; + repeated DatapointUpdate updates = 1; } message ProvideOnceResponse { @@ -83,21 +83,27 @@ message ProvideOnceResponse { } } -message ProvideStreamRequest { - repeated DataUpdate updates = 1; +message ProvideUpwardsStream { + message UpdateValues { + repeated DatapointUpdate datapoints = 1; + } + oneof action { + UpdateValues updates = 1; + ActuateCommandACK actuate_command_ack = 2; + } } -message ProvideStreamResponse { +message ProvideDownwardsStream { oneof action { - ActuateCommand actuator_command = 1; - SensorCommand sensor_command = 2; - bool ack_command = 3; - Error error = 4; + SignalCommand signal_command = 1; + ActuateCommand actuate_command = 2; + Error error = 3; } } message SubscribeRequest { repeated EntryRequest entries = 1; + optional uint64 interval_ms = 2; } message SubscribeResponse { @@ -105,7 +111,7 @@ message SubscribeResponse { } message ActuateRequest { - repeated DataUpdate actuators = 1; + repeated DatapointUpdate actuators = 1; } /** @@ -118,7 +124,12 @@ message GetResponse { **/ message ActuateResponse { - bool update_forwarded = 1; + bool ack_request_forwarded = 1; + oneof status { + DatapointStatus not_available = 1; + ProviderStatus provider_status = 2; + Error error = 3; + } } message MetadataRequest { From 761d9c0173a6a4151ec33c6cbb85693f8489ebeb Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Mon, 3 Jun 2024 17:47:46 +0200 Subject: [PATCH 07/21] Add Start/Stop Signal --- proto/kuksa/val/v2/types.proto | 16 ++++++++++------ proto/kuksa/val/v2/val.proto | 5 +++-- 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto index 8d174f82..e9b2bd65 100644 --- a/proto/kuksa/val/v2/types.proto +++ b/proto/kuksa/val/v2/types.proto @@ -82,13 +82,18 @@ message ActuateCommand { repeated DatapointUpdate updates = 2; } -message ActuateCommandResponse { +message ActuateCommandACK { string uuid = 1; bool ack_action_received = 3; } +message SignalCommandACK { + string uuid = 1; + bool ack_action_received = 3; +} message Start { + repeated string path = 2; optional uint64 update_interval_ms = 1; } @@ -98,18 +103,17 @@ message Stop { message SignalCommand { string uuid = 1; - string path = 2; - oneof signal_behaviour { Start start = 3; Stop stop = 4; } } -enum SignalAction { - START = 0; - STOP = 1; +enum ProviderStatus { + NOT_AVAILABE = 3; + INTERNAL_ERROR = 4; } + message Metadata { // Data type diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 33aa3d87..811d9fe2 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -39,7 +39,7 @@ service VAL { // provide stream of current values of attributes, sensors and actuator - for high frequency // return stream of ACK - rpc ProvideStream(stream ProvideStreamRequest) returns (stream ProvideStreamResponse); + rpc ProvideStream(stream ProvideUpwardsStream) returns (stream ProvideDownwardsStream); // subscribe to sensor and actuator values rpc Subscribe(SubscribeRequest) returns (stream SubscribeResponse); @@ -89,7 +89,8 @@ message ProvideUpwardsStream { } oneof action { UpdateValues updates = 1; - ActuateCommandACK actuate_command_ack = 2; + SignalCommandACK signal_command_ack = 2; + ActuateCommandACK actuate_command_ack = 3; } } From ce7cfc1f221ccb5350577d013022e09f06943690 Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Tue, 4 Jun 2024 15:31:23 +0200 Subject: [PATCH 08/21] Remove Start/Stop Signal and add batch methods --- proto/kuksa/val/v2/types.proto | 71 ++++++++++------------ proto/kuksa/val/v2/val.proto | 104 +++++++++++++++------------------ 2 files changed, 79 insertions(+), 96 deletions(-) diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto index e9b2bd65..a3a347ae 100644 --- a/proto/kuksa/val/v2/types.proto +++ b/proto/kuksa/val/v2/types.proto @@ -32,8 +32,8 @@ message DataEntry { message Datapoint { google.protobuf.Timestamp timestamp = 1; - oneof data { - DatapointStatus not_available = 2; + oneof value_state { + ValueFailure failure = 2; Value value = 3; } } @@ -59,17 +59,22 @@ message Value { } } -enum DatapointStatus { - // The data point is known, but doesn't have a valid value - INVALID_VALUE = 0; - // The data point is known, but no value is available - NOT_AVAILABLE = 1; - // Unknown datapoint - UNKNOWN_DATAPOINT = 2; - // Access denied - ACCESS_DENIED = 3; +enum ValueFailure { + // Unspecified value failure, reserved for gRPC backwards compatibility + // (see https://protobuf.dev/programming-guides/dos-donts/#unspecified-enum) + UNSPECIFIED = 0; + // The signal is known and provided, but doesn't have a valid value + INVALID_VALUE = 1; + // The signal is known, but no value is provided currently + NOT_AVAILABLE = 2; + // The referred signal is unknown on the system + UNKNOWN_SIGNAL = 3; + // The client does not have the necessary access rights to the signal + ACCESS_DENIED = 4; + // There is no prodiver connected to Databroker + PROVIDER_NOT_AVAILABE = 5; // Unexpected internal error - INTERNAL_ERROR = 4; + INTERNAL_ERROR = 6; } message DatapointUpdate { @@ -77,44 +82,32 @@ message DatapointUpdate { Value value = 2; } -message ActuateCommand { - string uuid = 1; - repeated DatapointUpdate updates = 2; +message UpdateDatapoints { + repeated DatapointUpdate datapoints = 1; } -message ActuateCommandACK { - string uuid = 1; - bool ack_action_received = 3; +message UpdateValueFailures { + map failures = 1; } -message SignalCommandACK { - string uuid = 1; - bool ack_action_received = 3; +message ActuateCommandRequest { + int32 request_id = 1; + repeated DatapointUpdate updates = 2; } -message Start { - repeated string path = 2; - optional uint64 update_interval_ms = 1; +message ActuateCommandResponse { + int32 request_id = 1; } -message Stop { - -} - -message SignalCommand { - string uuid = 1; - oneof signal_behaviour { - Start start = 3; - Stop stop = 4; +message ActuationResult { + oneof value + { + bool ack_request_forwarded = 1; + ValueFailure failure = 2; + Error error = 4; } } -enum ProviderStatus { - NOT_AVAILABE = 3; - INTERNAL_ERROR = 4; -} - - message Metadata { // Data type // The VSS data type of the entry (i.e. the value, min, max etc). diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 811d9fe2..c419f081 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -31,9 +31,21 @@ import "types.proto"; // that the client can use instead of auth-token in subsequent calls. service VAL { - // get current value of attributes, sensors and actuators + // get current value of a single attribute, sensor or actuator rpc Get(GetRequest) returns (GetResponse); + + // get current values of a set of attributes, sensors or actuators + rpc GetBatch(GetRequestBatch) returns (GetResponseBatch); + // subscribe to sensor and actuator values + rpc Subscribe(SubscribeRequest) returns (stream SubscribeResponse); + + // actuate on a single actuator value + rpc Actuate(ActuateRequest) returns (ActuateResponse); + + // actuate on more than one actuators values + rpc ActuateBatch(ActuateRequestBatch) returns (ActuateResponseBatch); + // provide current value of attributes, sensors and actuator - for low update frequency rpc ProvideOnce(ProvideOnceRequest) returns (ProvideOnceResponse); @@ -41,95 +53,73 @@ service VAL { // return stream of ACK rpc ProvideStream(stream ProvideUpwardsStream) returns (stream ProvideDownwardsStream); - // subscribe to sensor and actuator values - rpc Subscribe(SubscribeRequest) returns (stream SubscribeResponse); - - // actuate on actuator value - rpc Actuate(ActuateRequest) returns (ActuateResponse); - //get static metadata rpc GetMetadata(MetadataRequest) returns (MetadataResponse); rpc GetServerInfo(GetServerInfoRequest) returns (GetServerInfoResponse); } -// Request a set of entries. message GetRequest { - repeated EntryRequest entries = 1; + EntryRequest entry = 1; } message GetResponse { + DataEntry entry = 1; +} + +message GetRequestBatch { + map entries = 1; +} + +message GetResponseBatch { + map entries = 1; +} + +message SubscribeRequest { + repeated EntryRequest entries = 1; +} + +message SubscribeResponse { repeated DataEntry entries = 1; } -/** -Option 2 for GetResponse: +message ActuateRequest { + DatapointUpdate actuator = 1; +} -message GetResponse { - map entries = 1; +message ActuateResponse { + ActuationResult result = 1; } -**/ +message ActuateRequestBatch { + map actuators = 1; +} +message ActuateResponseBatch { + map responses = 1; +} message ProvideOnceRequest { - repeated DatapointUpdate updates = 1; + UpdateDatapoints update_datapoints = 1; } message ProvideOnceResponse { oneof action { - bool ack_update_received = 1; - Error error = 2; + ValueFailure failure = 1; } } message ProvideUpwardsStream { - message UpdateValues { - repeated DatapointUpdate datapoints = 1; - } oneof action { - UpdateValues updates = 1; - SignalCommandACK signal_command_ack = 2; - ActuateCommandACK actuate_command_ack = 3; + UpdateDatapoints update_datapoints = 1; + ActuateCommandResponse actuate_command_response = 2; } } message ProvideDownwardsStream { oneof action { - SignalCommand signal_command = 1; - ActuateCommand actuate_command = 2; - Error error = 3; - } -} - -message SubscribeRequest { - repeated EntryRequest entries = 1; - optional uint64 interval_ms = 2; -} - -message SubscribeResponse { - repeated DataEntry entries = 1; -} - -message ActuateRequest { - repeated DatapointUpdate actuators = 1; -} - -/** -Option 2 for ActuateRequest: - -message GetResponse { - map entries = 1; -} - -**/ - -message ActuateResponse { - bool ack_request_forwarded = 1; - oneof status { - DatapointStatus not_available = 1; - ProviderStatus provider_status = 2; - Error error = 3; + UpdateValueFailures update_failure = 2; + ActuateCommandRequest actuate_command_request = 1; } } From 3221203fddc0cc568049102140142a79c59228c6 Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Tue, 4 Jun 2024 15:48:59 +0200 Subject: [PATCH 09/21] Use correct numeration --- proto/kuksa/val/v2/val.proto | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index c419f081..5baaa1d8 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -118,8 +118,8 @@ message ProvideUpwardsStream { message ProvideDownwardsStream { oneof action { - UpdateValueFailures update_failure = 2; - ActuateCommandRequest actuate_command_request = 1; + UpdateValueFailures update_failure = 1; + ActuateCommandRequest actuate_command_request = 2; } } From 5afc533f38ccb9c485b10ecea0199c1150c726b7 Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Tue, 4 Jun 2024 17:14:48 +0200 Subject: [PATCH 10/21] Clean up and rename messages --- proto/kuksa/val/v2/types.proto | 87 +++++++++++++++++++++------------- proto/kuksa/val/v2/val.proto | 48 ++++++++++--------- 2 files changed, 79 insertions(+), 56 deletions(-) diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto index a3a347ae..d61940be 100644 --- a/proto/kuksa/val/v2/types.proto +++ b/proto/kuksa/val/v2/types.proto @@ -18,17 +18,6 @@ import "google/protobuf/timestamp.proto"; option go_package = "kuksa/val/v2"; -// Define which data we want -message EntryRequest { - string path = 1; -} - -message DataEntry { - // Defines the full VSS path of the entry. - string path = 1; - Datapoint datapoint = 2; -} - message Datapoint { google.protobuf.Timestamp timestamp = 1; @@ -66,48 +55,38 @@ enum ValueFailure { // The signal is known and provided, but doesn't have a valid value INVALID_VALUE = 1; // The signal is known, but no value is provided currently - NOT_AVAILABLE = 2; + NOT_PROVIDED = 2; // The referred signal is unknown on the system UNKNOWN_SIGNAL = 3; // The client does not have the necessary access rights to the signal ACCESS_DENIED = 4; - // There is no prodiver connected to Databroker - PROVIDER_NOT_AVAILABE = 5; // Unexpected internal error - INTERNAL_ERROR = 6; + INTERNAL_ERROR = 5; } -message DatapointUpdate { - string path = 1; - Value value = 2; -} - -message UpdateDatapoints { - repeated DatapointUpdate datapoints = 1; +message DatapointsUpdateRequest { + message ValueUpdate { + oneof value_state { + ValueFailure failure = 2; + Value value = 3; + } + } + map datapoints = 1; } -message UpdateValueFailures { - map failures = 1; +message DatapointsUpdateResponse { + map status = 1; } message ActuateCommandRequest { int32 request_id = 1; - repeated DatapointUpdate updates = 2; + map actuators_values = 2; } message ActuateCommandResponse { int32 request_id = 1; } -message ActuationResult { - oneof value - { - bool ack_request_forwarded = 1; - ValueFailure failure = 2; - Error error = 4; - } -} - message Metadata { // Data type // The VSS data type of the entry (i.e. the value, min, max etc). @@ -185,6 +164,46 @@ message ValueRestrictionString { repeated string allowed_values = 3; } +enum ActuateStatus { + // Unspecified value failure, reserved for gRPC backwards compatibility + // (see https://protobuf.dev/programming-guides/dos-donts/#unspecified-enum) + UNSPECIFIED = 0; + // The actuator value was successfully forwarded to the corresponding provider + OK_FORWARDED = 1; + // The passed value is not allowed + INVALID_VALUE = 2; + // The data type of the signal is not correct + INVALID_DATA_TYPE = 3; + // The signal is known, but there is no provider connected to Databroker + PROVIDER_NOT_AVAILABE = 4; + // The referred signal is unknown on the system + UNKNOWN_SIGNAL = 5; + // The client does not have the necessary access rights to the signal + ACCESS_DENIED = 6; + // Unexpected internal error + INTERNAL_ERROR = 7; +} + +enum ProvideStatus { + // Unspecified value failure, reserved for gRPC backwards compatibility + // (see https://protobuf.dev/programming-guides/dos-donts/#unspecified-enum) + UNSPECIFIED = 0; + // The actuator value was successfully forwarded to the corresponding provider + ACCEPTED = 1; + // The passed value is not allowed + INVALID_VALUE = 2; + // The data type of the signal is not correct + INVALID_DATA_TYPE = 3; + // The signal is already claimed by another provider. + OWNERSHIP_DENIED = 4; + // The referred signal is unknown on the system + UNKNOWN_SIGNAL = 5; + // The client does not have the necessary access rights to the signal + ACCESS_DENIED = 6; + // Unexpected internal error + INTERNAL_ERROR = 7; +} + // VSS Data type of a signal // // Protobuf doesn't support int8, int16, uint8 or uint16. diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 5baaa1d8..bae9e953 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -35,7 +35,7 @@ service VAL { rpc Get(GetRequest) returns (GetResponse); // get current values of a set of attributes, sensors or actuators - rpc GetBatch(GetRequestBatch) returns (GetResponseBatch); + rpc GetBatch(GetBatchRequest) returns (GetBatchResponse); // subscribe to sensor and actuator values rpc Subscribe(SubscribeRequest) returns (stream SubscribeResponse); @@ -44,7 +44,7 @@ service VAL { rpc Actuate(ActuateRequest) returns (ActuateResponse); // actuate on more than one actuators values - rpc ActuateBatch(ActuateRequestBatch) returns (ActuateResponseBatch); + rpc ActuateBatch(ActuateBatchRequest) returns (ActuateBatchResponse); // provide current value of attributes, sensors and actuator - for low update frequency rpc ProvideOnce(ProvideOnceRequest) returns (ProvideOnceResponse); @@ -60,65 +60,69 @@ service VAL { } message GetRequest { - EntryRequest entry = 1; + string path = 1; } message GetResponse { - DataEntry entry = 1; + Datapoint entry = 1; } -message GetRequestBatch { - map entries = 1; +message GetBatchRequest { + repeated string paths = 1; } -message GetResponseBatch { - map entries = 1; +message GetBatchResponse { + map entries = 1; } message SubscribeRequest { - repeated EntryRequest entries = 1; + repeated string paths = 1; } message SubscribeResponse { - repeated DataEntry entries = 1; + map entries = 1; } message ActuateRequest { - DatapointUpdate actuator = 1; + string actutator_path = 1; + Value actutator_value = 2; } message ActuateResponse { - ActuationResult result = 1; + ActuateStatus status = 1; } -message ActuateRequestBatch { - map actuators = 1; +message ActuateBatchRequest { + map actuators_values = 1; } -message ActuateResponseBatch { - map responses = 1; +message ActuateBatchResponse { + map status = 1; } message ProvideOnceRequest { - UpdateDatapoints update_datapoints = 1; + string path = 1; + + oneof value_state { + ValueFailure failure = 2; + Value value = 3; + } } message ProvideOnceResponse { - oneof action { - ValueFailure failure = 1; - } + ProvideStatus status = 1; } message ProvideUpwardsStream { oneof action { - UpdateDatapoints update_datapoints = 1; + DatapointsUpdateRequest update_datapoints_request = 1; ActuateCommandResponse actuate_command_response = 2; } } message ProvideDownwardsStream { oneof action { - UpdateValueFailures update_failure = 1; + DatapointsUpdateResponse update_status_response = 1; ActuateCommandRequest actuate_command_request = 2; } } From 233138e9d9a25d2679a6ade8414368d94b9511fd Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Tue, 4 Jun 2024 17:22:32 +0200 Subject: [PATCH 11/21] Move ValueFailure to bottom --- proto/kuksa/val/v2/types.proto | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto index d61940be..17fe9522 100644 --- a/proto/kuksa/val/v2/types.proto +++ b/proto/kuksa/val/v2/types.proto @@ -48,22 +48,6 @@ message Value { } } -enum ValueFailure { - // Unspecified value failure, reserved for gRPC backwards compatibility - // (see https://protobuf.dev/programming-guides/dos-donts/#unspecified-enum) - UNSPECIFIED = 0; - // The signal is known and provided, but doesn't have a valid value - INVALID_VALUE = 1; - // The signal is known, but no value is provided currently - NOT_PROVIDED = 2; - // The referred signal is unknown on the system - UNKNOWN_SIGNAL = 3; - // The client does not have the necessary access rights to the signal - ACCESS_DENIED = 4; - // Unexpected internal error - INTERNAL_ERROR = 5; -} - message DatapointsUpdateRequest { message ValueUpdate { oneof value_state { @@ -164,6 +148,22 @@ message ValueRestrictionString { repeated string allowed_values = 3; } +enum ValueFailure { + // Unspecified value failure, reserved for gRPC backwards compatibility + // (see https://protobuf.dev/programming-guides/dos-donts/#unspecified-enum) + UNSPECIFIED = 0; + // The signal is known and provided, but doesn't have a valid value + INVALID_VALUE = 1; + // The signal is known, but no value is provided currently + NOT_PROVIDED = 2; + // The referred signal is unknown on the system + UNKNOWN_SIGNAL = 3; + // The client does not have the necessary access rights to the signal + ACCESS_DENIED = 4; + // Unexpected internal error + INTERNAL_ERROR = 5; +} + enum ActuateStatus { // Unspecified value failure, reserved for gRPC backwards compatibility // (see https://protobuf.dev/programming-guides/dos-donts/#unspecified-enum) From 48a603ff3c8514e3a9a3eec8fc660423119f1a6f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?John=20Arg=C3=A9rus?= Date: Fri, 7 Jun 2024 09:34:04 +0200 Subject: [PATCH 12/21] Add proposed API --- proto/kuksa/val/v2/val.proto | 182 +++++++++++++++++++++++------------ 1 file changed, 122 insertions(+), 60 deletions(-) diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index bae9e953..037966a2 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -19,60 +19,96 @@ option go_package = "kuksa/val/v2"; import "types.proto"; -// Note on authorization: -// Tokens (auth-token or auth-uuid) are sent as (GRPC / http2) metadata. -// -// The auth-token is a JWT compliant token as the examples found here: -// https://github.com/eclipse-kuksa/kuksa-databroker/tree/main/certificates/jwt -// -// See also https://github.com/eclipse-kuksa/kuksa-databroker/blob/main/doc/authorization.md#jwt-access-token -// -// Upon reception of auth-token, server shall generate an auth-uuid in metadata -// that the client can use instead of auth-token in subsequent calls. - service VAL { - // get current value of a single attribute, sensor or actuator - rpc Get(GetRequest) returns (GetResponse); + // Get the latest value of a signal + // + // Returns (GRPC error code): + // NOT_FOUND if the requested datapoints doesn't exist + // PERMISSION_DENIED if access is denied + rpc GetValue(GetValueRequest) returns (GetValueResponse); - // get current values of a set of attributes, sensors or actuators - rpc GetBatch(GetBatchRequest) returns (GetBatchResponse); - - // subscribe to sensor and actuator values + // Get the lastest value of a set of signals + // + // Returns (GRPC error code): + // NOT_FOUND if any of the requested signals doesn't exist. + // PERMISSION_DENIED if access is denied for any of the requested signals. + // + // grpc NOT_FOUND: Vehicle.Speed2 couldn't be found. + // grpc.Status.details = message BatchGetValueError { + // map + // } + rpc GetValues(GetValuesRequest) returns (GetValuesResponse); + + // List values of signals matching the request. + // + // Returns a list of signal values. Only value that the user is allowed to + // read are included (everything else is ignored). + // + // Returns (grpc error code): + // not_found if the specified root branch does not exist. + rpc ListValues(ListValuesRequest) returns (ListValuesResponse); + + // Subscribe to a set of signals + // Returns (GRPC error code): + // NOT_FOUND if any of the signals are non-existant. + // PERMISSION_DENIED if access is denied for any of the signals. rpc Subscribe(SubscribeRequest) returns (stream SubscribeResponse); - // actuate on a single actuator value + // Actuate a single actuator + // + // Returns (GRPC error code): + // NOT_FOUND if the actuator does not exist. + // PERMISSION_DENIED if access is denied for of the actuator. + // UNAVAILABLE if there is no provider currently providing the actuator rpc Actuate(ActuateRequest) returns (ActuateResponse); - // actuate on more than one actuators values - rpc ActuateBatch(ActuateBatchRequest) returns (ActuateBatchResponse); - - // provide current value of attributes, sensors and actuator - for low update frequency - rpc ProvideOnce(ProvideOnceRequest) returns (ProvideOnceResponse); - - // provide stream of current values of attributes, sensors and actuator - for high frequency - // return stream of ACK - rpc ProvideStream(stream ProvideUpwardsStream) returns (stream ProvideDownwardsStream); - - //get static metadata - rpc GetMetadata(MetadataRequest) returns (MetadataResponse); - + // Actuate multiple actuators + // + // Returns (GRPC error code): + // NOT_FOUND if any of the actuators are non-existant. + // PERMISSION_DENIED if access is denied for any of the actuators. + // UNAVAILABLE if there is no provider currently providing an actuator + rpc Actuate(ActuateRequest) returns (ActuateResponse); + rpc BatchActuate(BatchActuateRequest) returns (BatchActuateResponse); + + // List metadata of signals matching the request. + // NOT_FOUND if the specified root branch does not exist. + rpc ListMetadata(ListMetadataRequest) returns (ListMetadataResponse); + + // Publish a signal value. Used for low frequency signals (e.g. attributes). + // + // Returns (GRPC error code): + // NOT_FOUND if any of the signals are non-existant. + // PERMISSION_DENIED if access is denied for any of the signals. + rpc PublishValue(PublishValueRequest) returns (PublishValueResponse); + + // Open a stream used to provide actuation and/or publishing values using + // a streaming interface. Used to provide actuators and to enable high frequency + // updates of values. + // + // 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. + rpc OpenProviderStream(stream OpenProviderStreamRequest) returns (stream OpenProviderStreamResponse); + + // Get server information rpc GetServerInfo(GetServerInfoRequest) returns (GetServerInfoResponse); } -message GetRequest { +message GetValueRequest { string path = 1; } -message GetResponse { - Datapoint entry = 1; +message GetValueResponse { + Datapoint data_point = 1; } -message GetBatchRequest { +message GetValuesRequest { repeated string paths = 1; } -message GetBatchResponse { - map entries = 1; +message GetValuesResponse { + repeated Datapoint datapoints = 1; } message SubscribeRequest { @@ -84,52 +120,78 @@ message SubscribeResponse { } message ActuateRequest { - string actutator_path = 1; - Value actutator_value = 2; + string path = 1; + Value value = 2; } message ActuateResponse { - ActuateStatus status = 1; } -message ActuateBatchRequest { - map actuators_values = 1; +message BatchActuateRequest { + repeated ActuateRequest actuate_requests = 1; } -message ActuateBatchResponse { - map status = 1; +message BatchActuateResponse { } -message ProvideOnceRequest { - string path = 1; +message PublishValueRequest { + // Unique request id that can be used to identify the response. + int32 request_id = 1; + + // Signal identified by either id or path + oneof signal { + int32 id = 10; + string path = 11; + } - oneof value_state { - ValueFailure failure = 2; - Value value = 3; + // The value to publish + oneof data { + Value value = 20; + Failure failure = 21; } } -message ProvideOnceResponse { - ProvideStatus status = 1; +message PublishValueResponse { + int32 request_id = 1; + // TODO: Add error cases } -message ProvideUpwardsStream { +message OpenProviderStreamRequest { oneof action { - DatapointsUpdateRequest update_datapoints_request = 1; - ActuateCommandResponse actuate_command_response = 2; + // Inform server of a sensor this provider provides. + ProvideSensorRequest provide_sensor_request = 1; + // Inform server of an actuator this provider provides. + ProvideActuatorRequest provide_actuator_request = 2; + // Publish a value. + PublishValueRequest publish_value_request = 3; + // Sent to acknowledge the acceptance of a actuate request. + ActuateResponse actuate_response = 4; + // Sent to acknowledge the acceptance of a batch actuate + // request. + BatchActuateResponse batch_actuate_response = 5; } } -message ProvideDownwardsStream { +message OpenProviderStreamResponse { oneof action { - DatapointsUpdateResponse update_status_response = 1; - ActuateCommandRequest actuate_command_request = 2; + // Response to a provide sensor request. + ProvideSensorResponse provide_sensor_response = 1; + // Response to a provide actuator request. + ProvideActuatorResponse provide_actuator_response = 2; + // Acknowledgement that a published value was received. + PublishValueResponse publish_value_response = 3; + // Send an actuate request to a provider. + ActuateRequest actuate_request = 4; + // Send a batch actuate request to a provider. + BatchActuateRequest batch_actuate_request = 5; } } -message MetadataRequest { - repeated string path = 1; - repeated Field fields = 2; +message ListMetadataRequest { + // Path of a branch or signal (i.e. the "root" path) + string root = 1; + // Optional filter + string filter = 2; } message MetadataResponse { From 982968dfcc6a56670c36e1fdc011ed0e01caf0b6 Mon Sep 17 00:00:00 2001 From: "Ruiz-Lucena Rafael (ETAS-E2E/XPC-Fe)" Date: Thu, 20 Jun 2024 18:50:03 +0200 Subject: [PATCH 13/21] Updates after review session --- proto/kuksa/val/v2/types.proto | 104 +++++++------------------- proto/kuksa/val/v2/val.proto | 130 +++++++++++++++++++-------------- 2 files changed, 101 insertions(+), 133 deletions(-) diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto index 17fe9522..a5ec917f 100644 --- a/proto/kuksa/val/v2/types.proto +++ b/proto/kuksa/val/v2/types.proto @@ -23,7 +23,7 @@ message Datapoint { oneof value_state { ValueFailure failure = 2; - Value value = 3; + Value value = 3; } } @@ -48,27 +48,23 @@ message Value { } } -message DatapointsUpdateRequest { - message ValueUpdate { - oneof value_state { - ValueFailure failure = 2; - Value value = 3; - } +message SignalID { + oneof signal { + int32 id = 1; + string path = 2; } - map datapoints = 1; } -message DatapointsUpdateResponse { - map status = 1; -} - -message ActuateCommandRequest { - int32 request_id = 1; - map actuators_values = 2; +message Error { + ErrorCode code = 1; + string message = 2; } -message ActuateCommandResponse { - int32 request_id = 1; +enum ErrorCode { + OK = 0; + INVALID_ARGUMENT = 1; + NOT_FOUND = 2; + PERMISSION_DENIED = 3; } message Metadata { @@ -77,28 +73,28 @@ message Metadata { // // NOTE: protobuf doesn't have int8, int16, uint8 or uint16 which means // that these values must be serialized as int32 and uint32 respectively. - DataType data_type = 11; // [field: FIELD_METADATA_DATA_TYPE] + DataType data_type = 11; // [field: FIELD_METADATA_DATA_TYPE] // Entry type - EntryType entry_type = 12; // [field: FIELD_METADATA_ENTRY_TYPE] + EntryType entry_type = 12; // [field: FIELD_METADATA_ENTRY_TYPE] // Description // Describes the meaning and content of the entry. - optional string description = 13; // [field: FIELD_METADATA_DESCRIPTION] + optional string description = 13; // [field: FIELD_METADATA_DESCRIPTION] // Comment [optional] // A comment can be used to provide additional informal information // on a entry. - optional string comment = 14; // [field: FIELD_METADATA_COMMENT] + optional string comment = 14; // [field: FIELD_METADATA_COMMENT] // Deprecation [optional] // Whether this entry is deprecated. Can contain recommendations of what // to use instead. - optional string deprecation = 15; // [field: FIELD_METADATA_DEPRECATION] + optional string deprecation = 15; // [field: FIELD_METADATA_DEPRECATION] // Unit [optional] // The unit of measurement - optional string unit = 16; // [field: FIELD_METADATA_UNIT] + optional string unit = 16; // [field: FIELD_METADATA_UNIT] // Value restrictions [optional] // Restrict which values are allowed. @@ -113,11 +109,11 @@ message Metadata { // message ValueRestriction { oneof type { - ValueRestrictionString string = 21; + ValueRestrictionString string = 21; // For signed VSS integers - ValueRestrictionInt signed = 22; + ValueRestrictionInt signed = 22; // For unsigned VSS integers - ValueRestrictionUint unsigned = 23; + ValueRestrictionUint unsigned = 23; // For floating point VSS values (float and double) ValueRestrictionFloat floating_point = 24; } @@ -151,59 +147,19 @@ message ValueRestrictionString { enum ValueFailure { // Unspecified value failure, reserved for gRPC backwards compatibility // (see https://protobuf.dev/programming-guides/dos-donts/#unspecified-enum) - UNSPECIFIED = 0; + UNSPECIFIED = 0; // The signal is known and provided, but doesn't have a valid value - INVALID_VALUE = 1; + INVALID_VALUE = 1; // The signal is known, but no value is provided currently - NOT_PROVIDED = 2; + NOT_PROVIDED = 2; // The referred signal is unknown on the system UNKNOWN_SIGNAL = 3; // The client does not have the necessary access rights to the signal - ACCESS_DENIED = 4; + ACCESS_DENIED = 4; // Unexpected internal error INTERNAL_ERROR = 5; } -enum ActuateStatus { - // Unspecified value failure, reserved for gRPC backwards compatibility - // (see https://protobuf.dev/programming-guides/dos-donts/#unspecified-enum) - UNSPECIFIED = 0; - // The actuator value was successfully forwarded to the corresponding provider - OK_FORWARDED = 1; - // The passed value is not allowed - INVALID_VALUE = 2; - // The data type of the signal is not correct - INVALID_DATA_TYPE = 3; - // The signal is known, but there is no provider connected to Databroker - PROVIDER_NOT_AVAILABE = 4; - // The referred signal is unknown on the system - UNKNOWN_SIGNAL = 5; - // The client does not have the necessary access rights to the signal - ACCESS_DENIED = 6; - // Unexpected internal error - INTERNAL_ERROR = 7; -} - -enum ProvideStatus { - // Unspecified value failure, reserved for gRPC backwards compatibility - // (see https://protobuf.dev/programming-guides/dos-donts/#unspecified-enum) - UNSPECIFIED = 0; - // The actuator value was successfully forwarded to the corresponding provider - ACCEPTED = 1; - // The passed value is not allowed - INVALID_VALUE = 2; - // The data type of the signal is not correct - INVALID_DATA_TYPE = 3; - // The signal is already claimed by another provider. - OWNERSHIP_DENIED = 4; - // The referred signal is unknown on the system - UNKNOWN_SIGNAL = 5; - // The client does not have the necessary access rights to the signal - ACCESS_DENIED = 6; - // Unexpected internal error - INTERNAL_ERROR = 7; -} - // VSS Data type of a signal // // Protobuf doesn't support int8, int16, uint8 or uint16. @@ -273,14 +229,6 @@ enum Field { FIELD_METADATA_ATTRIBUTE = 40; // metadata.attribute.* } -// Error response shall be an HTTP-like code. -// Should follow https://www.w3.org/TR/viss2-transport/#status-codes. -message Error { - uint32 code = 1; - string reason = 2; - string message = 3; -} - message StringArray { repeated string values = 1; } diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 037966a2..0046b52a 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -17,17 +17,17 @@ package kuksa.val.v2; option go_package = "kuksa/val/v2"; -import "types.proto"; +import "kuksa/val/v2/types.proto"; service VAL { // Get the latest value of a signal // // Returns (GRPC error code): - // NOT_FOUND if the requested datapoints doesn't exist + // NOT_FOUND if the requested signal doesn't exist // PERMISSION_DENIED if access is denied rpc GetValue(GetValueRequest) returns (GetValueResponse); - // Get the lastest value of a set of signals + // Get the latest values of a set of signals // // Returns (GRPC error code): // NOT_FOUND if any of the requested signals doesn't exist. @@ -35,17 +35,17 @@ service VAL { // // grpc NOT_FOUND: Vehicle.Speed2 couldn't be found. // grpc.Status.details = message BatchGetValueError { - // map + // map // } rpc GetValues(GetValuesRequest) returns (GetValuesResponse); // List values of signals matching the request. // - // Returns a list of signal values. Only value that the user is allowed to - // read are included (everything else is ignored). + // Returns a list of signal values. Only values of signals that the user + // is allowed to read are included (everything else is ignored). // // Returns (grpc error code): - // not_found if the specified root branch does not exist. + // NOT_FOUND if the specified root branch does not exist. rpc ListValues(ListValuesRequest) returns (ListValuesResponse); // Subscribe to a set of signals @@ -60,15 +60,26 @@ service VAL { // NOT_FOUND if the actuator does not exist. // PERMISSION_DENIED if access is denied for of the actuator. // UNAVAILABLE if there is no provider currently providing the actuator + // INVALID_ARGUMENT + // - if the data type used in the request does not match + // the data type of the addressed signal + // - if the requested value is not accepted, + // e.g. if sending an unsupported enum value rpc Actuate(ActuateRequest) returns (ActuateResponse); - // Actuate multiple actuators + // Actuate simultaneously multiple actuators. + // If any error occurs, the entire operation will be aborted + // and no single actuator value will be forwarded to the provider. // // Returns (GRPC error code): // NOT_FOUND if any of the actuators are non-existant. // PERMISSION_DENIED if access is denied for any of the actuators. // UNAVAILABLE if there is no provider currently providing an actuator - rpc Actuate(ActuateRequest) returns (ActuateResponse); + // INVALID_ARGUMENT + // - if the data type used in the request does not match + // the data type of the addressed signal + // - if the requested value is not accepted, + // e.g. if sending an unsupported enum value rpc BatchActuate(BatchActuateRequest) returns (BatchActuateResponse); // List metadata of signals matching the request. @@ -79,7 +90,14 @@ service VAL { // // Returns (GRPC error code): // NOT_FOUND if any of the signals are non-existant. - // PERMISSION_DENIED if access is denied for any of the signals. + // PERMISSION_DENIED + // - if access is denied for any of the signals. + // - if the signal is already provided by another provider. + // INVALID_ARGUMENT + // - if the data type used in the request does not match + // the data type of the addressed signal + // - if the published value is not accepted, + // e.g. if sending an unsupported enum value rpc PublishValue(PublishValueRequest) returns (PublishValueResponse); // Open a stream used to provide actuation and/or publishing values using @@ -96,7 +114,7 @@ service VAL { } message GetValueRequest { - string path = 1; + SignalID signal_id = 1; } message GetValueResponse { @@ -104,15 +122,23 @@ message GetValueResponse { } message GetValuesRequest { - repeated string paths = 1; + repeated SignalID signal_ids = 1; } message GetValuesResponse { repeated Datapoint datapoints = 1; } +message ListValuesRequest { + repeated SignalID signal_ids = 1; +} + +message ListValuesResponse { + repeated Datapoint datapoints = 1; +} + message SubscribeRequest { - repeated string paths = 1; + repeated SignalID signal_ids = 1; } message SubscribeResponse { @@ -120,8 +146,8 @@ message SubscribeResponse { } message ActuateRequest { - string path = 1; - Value value = 2; + SignalID signal_id = 1; + Value value = 2; } message ActuateResponse { @@ -134,70 +160,64 @@ message BatchActuateRequest { message BatchActuateResponse { } -message PublishValueRequest { - // Unique request id that can be used to identify the response. - int32 request_id = 1; +message ListMetadataRequest { + string root = 1; + string filter = 2; +} - // Signal identified by either id or path - oneof signal { - int32 id = 10; - string path = 11; - } +message ListMetadataResponse { + repeated Metadata metadata = 1; +} - // The value to publish - oneof data { - Value value = 20; - Failure failure = 21; - } +message PublishValueRequest { + SignalID signal_id = 1; + Datapoint data_point = 2; } message PublishValueResponse { - int32 request_id = 1; - // TODO: Add error cases + Error error = 2; +} + +message PublishValuesRequest { + int32 request_id = 1; /// Unique request id for the stream that can be used to identify the response. + map datapoints = 2; +} + +message PublishValuesResponse { + int32 request_id = 1; + map status = 2; +} + +message ProvidedActuation { + repeated SignalID actuator_identifiers = 1; +} + +message ProvideActuatorResponse { } message OpenProviderStreamRequest { oneof action { - // Inform server of a sensor this provider provides. - ProvideSensorRequest provide_sensor_request = 1; // Inform server of an actuator this provider provides. - ProvideActuatorRequest provide_actuator_request = 2; + ProvidedActuation provided_actuation = 1; // Publish a value. - PublishValueRequest publish_value_request = 3; - // Sent to acknowledge the acceptance of a actuate request. - ActuateResponse actuate_response = 4; + PublishValuesRequest publish_values_request = 2; // Sent to acknowledge the acceptance of a batch actuate // request. - BatchActuateResponse batch_actuate_response = 5; + BatchActuateResponse batch_actuate_response = 3; } } message OpenProviderStreamResponse { oneof action { - // Response to a provide sensor request. - ProvideSensorResponse provide_sensor_response = 1; // Response to a provide actuator request. - ProvideActuatorResponse provide_actuator_response = 2; + ProvideActuatorResponse provide_actuator_response = 1; // Acknowledgement that a published value was received. - PublishValueResponse publish_value_response = 3; - // Send an actuate request to a provider. - ActuateRequest actuate_request = 4; + PublishValuesResponse publish_value_response = 2; // Send a batch actuate request to a provider. - BatchActuateRequest batch_actuate_request = 5; + BatchActuateRequest batch_actuate_request = 3; } } -message ListMetadataRequest { - // Path of a branch or signal (i.e. the "root" path) - string root = 1; - // Optional filter - string filter = 2; -} - -message MetadataResponse { - repeated Metadata metadata = 1; -} - message GetServerInfoRequest { // Nothing yet } From 6f129900ce42a147812ac160af7dd83ee29ad961 Mon Sep 17 00:00:00 2001 From: "Ruiz-Lucena Rafael (ETAS-E2E/XPC-Fe)" Date: Thu, 20 Jun 2024 18:56:27 +0200 Subject: [PATCH 14/21] format --- databroker-proto/build.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/databroker-proto/build.rs b/databroker-proto/build.rs index 9d21cfe0..60e40af6 100644 --- a/databroker-proto/build.rs +++ b/databroker-proto/build.rs @@ -24,7 +24,7 @@ fn main() -> Result<(), Box> { "proto/kuksa/val/v1/val.proto", "proto/kuksa/val/v1/types.proto", "proto/kuksa/val/v2/types.proto", - "proto/kuksa/val/v2/val.proto" + "proto/kuksa/val/v2/val.proto", ], &["proto"], )?; From 70c41c473f93af38c0a97eace0fde6bf97055487 Mon Sep 17 00:00:00 2001 From: "Ruiz-Lucena Rafael (ETAS-E2E/XPC-Fe)" Date: Thu, 20 Jun 2024 19:06:36 +0200 Subject: [PATCH 15/21] pre commit --- proto/kuksa/val/v2/val.proto | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 0046b52a..30883e47 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -26,7 +26,6 @@ service VAL { // NOT_FOUND if the requested signal doesn't exist // PERMISSION_DENIED if access is denied rpc GetValue(GetValueRequest) returns (GetValueResponse); - // Get the latest values of a set of signals // // Returns (GRPC error code): @@ -41,7 +40,7 @@ service VAL { // List values of signals matching the request. // - // Returns a list of signal values. Only values of signals that the user + // Returns a list of signal values. Only values of signals that the user // is allowed to read are included (everything else is ignored). // // Returns (grpc error code): @@ -61,9 +60,9 @@ service VAL { // PERMISSION_DENIED if access is denied for of the actuator. // UNAVAILABLE if there is no provider currently providing the actuator // INVALID_ARGUMENT - // - if the data type used in the request does not match + // - if the data type used in the request does not match // the data type of the addressed signal - // - if the requested value is not accepted, + // - if the requested value is not accepted, // e.g. if sending an unsupported enum value rpc Actuate(ActuateRequest) returns (ActuateResponse); @@ -76,9 +75,9 @@ service VAL { // PERMISSION_DENIED if access is denied for any of the actuators. // UNAVAILABLE if there is no provider currently providing an actuator // INVALID_ARGUMENT - // - if the data type used in the request does not match + // - if the data type used in the request does not match // the data type of the addressed signal - // - if the requested value is not accepted, + // - if the requested value is not accepted, // e.g. if sending an unsupported enum value rpc BatchActuate(BatchActuateRequest) returns (BatchActuateResponse); @@ -90,13 +89,13 @@ service VAL { // // Returns (GRPC error code): // NOT_FOUND if any of the signals are non-existant. - // PERMISSION_DENIED + // PERMISSION_DENIED // - if access is denied for any of the signals. // - if the signal is already provided by another provider. // INVALID_ARGUMENT - // - if the data type used in the request does not match + // - if the data type used in the request does not match // the data type of the addressed signal - // - if the published value is not accepted, + // - if the published value is not accepted, // e.g. if sending an unsupported enum value rpc PublishValue(PublishValueRequest) returns (PublishValueResponse); From 5ce44cea3bfecd5837c5f5cb8be0506519d0ff1b Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Mon, 24 Jun 2024 12:28:40 +0200 Subject: [PATCH 16/21] Improve documentation --- proto/kuksa/val/v2/types.proto | 28 +--------------------------- proto/kuksa/val/v2/val.proto | 15 +++++++-------- 2 files changed, 8 insertions(+), 35 deletions(-) diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto index a5ec917f..b910b85e 100644 --- a/proto/kuksa/val/v2/types.proto +++ b/proto/kuksa/val/v2/types.proto @@ -141,7 +141,7 @@ message ValueRestrictionFloat { // min, max doesn't make much sense for a string message ValueRestrictionString { - repeated string allowed_values = 3; + repeated string allowed_values = 1; } enum ValueFailure { @@ -203,32 +203,6 @@ enum EntryType { ENTRY_TYPE_ACTUATOR = 3; } -// A `Field` corresponds to a specific field of a `DataEntry`. -// -// It can be used to: -// * populate only specific fields of a `DataEntry` response. -// * specify which fields of a `DataEntry` should be set as -// part of a `Set` request. -// * subscribe to only specific fields of a data entry. -// * convey which fields of an updated `DataEntry` have changed. -enum Field { - FIELD_UNSPECIFIED = 0; // "*" i.e. everything - FIELD_PATH = 1; // path - FIELD_VALUE = 2; // value - FIELD_ACTUATOR_TARGET = 3; // actuator_target - FIELD_METADATA = 10; // metadata.* - FIELD_METADATA_DATA_TYPE = 11; // metadata.data_type - FIELD_METADATA_DESCRIPTION = 12; // metadata.description - FIELD_METADATA_ENTRY_TYPE = 13; // metadata.entry_type - FIELD_METADATA_COMMENT = 14; // metadata.comment - FIELD_METADATA_DEPRECATION = 15; // metadata.deprecation - FIELD_METADATA_UNIT = 16; // metadata.unit - FIELD_METADATA_VALUE_RESTRICTION = 17; // metadata.value_restriction.* - FIELD_METADATA_ACTUATOR = 20; // metadata.actuator.* - FIELD_METADATA_SENSOR = 30; // metadata.sensor.* - FIELD_METADATA_ATTRIBUTE = 40; // metadata.attribute.* -} - message StringArray { repeated string values = 1; } diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 30883e47..4e4e4505 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -26,16 +26,13 @@ service VAL { // NOT_FOUND if the requested signal doesn't exist // PERMISSION_DENIED if access is denied rpc GetValue(GetValueRequest) returns (GetValueResponse); - // Get the latest values of a set of signals + + // Get the latest values of a set of signals. + // The returned list of data points has the same order as the list of the request. // // Returns (GRPC error code): // NOT_FOUND if any of the requested signals doesn't exist. // PERMISSION_DENIED if access is denied for any of the requested signals. - // - // grpc NOT_FOUND: Vehicle.Speed2 couldn't be found. - // grpc.Status.details = message BatchGetValueError { - // map - // } rpc GetValues(GetValuesRequest) returns (GetValuesResponse); // List values of signals matching the request. @@ -43,7 +40,7 @@ service VAL { // Returns a list of signal values. Only values of signals that the user // is allowed to read are included (everything else is ignored). // - // Returns (grpc error code): + // Returns (GRPC error code): // NOT_FOUND if the specified root branch does not exist. rpc ListValues(ListValuesRequest) returns (ListValuesResponse); @@ -82,6 +79,8 @@ service VAL { rpc BatchActuate(BatchActuateRequest) returns (BatchActuateResponse); // List metadata of signals matching the request. + // + // Returns (GRPC error code): // NOT_FOUND if the specified root branch does not exist. rpc ListMetadata(ListMetadataRequest) returns (ListMetadataResponse); @@ -174,7 +173,7 @@ message PublishValueRequest { } message PublishValueResponse { - Error error = 2; + Error error = 1; } message PublishValuesRequest { From 49f2a8f15ff7804d1ebac06789742edddfe74683 Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Mon, 24 Jun 2024 12:50:27 +0200 Subject: [PATCH 17/21] Avoid reusing messages among calls --- proto/kuksa/val/v2/val.proto | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 4e4e4505..7448945c 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -193,26 +193,33 @@ message ProvidedActuation { message ProvideActuatorResponse { } +message BatchActuateStreamRequest { + repeated ActuateRequest actuate_requests = 1; +} + +message BatchActuateStreamResponse { +} + message OpenProviderStreamRequest { oneof action { // Inform server of an actuator this provider provides. - ProvidedActuation provided_actuation = 1; + ProvidedActuation provided_actuation = 1; // Publish a value. - PublishValuesRequest publish_values_request = 2; + PublishValuesRequest publish_values_request = 2; // Sent to acknowledge the acceptance of a batch actuate // request. - BatchActuateResponse batch_actuate_response = 3; + BatchActuateStreamResponse batch_actuate_stream_response = 3; } } message OpenProviderStreamResponse { oneof action { // Response to a provide actuator request. - ProvideActuatorResponse provide_actuator_response = 1; + ProvideActuatorResponse provide_actuator_response = 1; // Acknowledgement that a published value was received. - PublishValuesResponse publish_value_response = 2; + PublishValuesResponse publish_value_response = 2; // Send a batch actuate request to a provider. - BatchActuateRequest batch_actuate_request = 3; + BatchActuateStreamRequest batch_actuate_stream_request = 3; } } From 077d488324f4efabe4f23d54c96dfad0c052ed4f Mon Sep 17 00:00:00 2001 From: "Ruiz-Lucena Rafael (ETAS-E2E/XPC-Fe)" Date: Mon, 15 Jul 2024 10:34:23 +0200 Subject: [PATCH 18/21] Add signal i32 id to metadata --- proto/kuksa/val/v2/types.proto | 7 +++++-- proto/kuksa/val/v2/val.proto | 14 +++++++------- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto index b910b85e..8f21cd60 100644 --- a/proto/kuksa/val/v2/types.proto +++ b/proto/kuksa/val/v2/types.proto @@ -56,8 +56,8 @@ message SignalID { } message Error { - ErrorCode code = 1; - string message = 2; + ErrorCode code = 1; + string message = 2; } enum ErrorCode { @@ -68,6 +68,9 @@ enum ErrorCode { } message Metadata { + // ID field + int32 id = 10; // Unique identifier for the metadata entry + // Data type // The VSS data type of the entry (i.e. the value, min, max etc). // diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 7448945c..03a6734d 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -177,13 +177,13 @@ message PublishValueResponse { } message PublishValuesRequest { - int32 request_id = 1; /// Unique request id for the stream that can be used to identify the response. - map datapoints = 2; + int32 request_id = 1; /// Unique request id for the stream that can be used to identify the response. + map datapoints = 2; } message PublishValuesResponse { - int32 request_id = 1; - map status = 2; + int32 request_id = 1; + map status = 2; } message ProvidedActuation { @@ -215,11 +215,11 @@ message OpenProviderStreamRequest { message OpenProviderStreamResponse { oneof action { // Response to a provide actuator request. - ProvideActuatorResponse provide_actuator_response = 1; + ProvideActuatorResponse provide_actuator_response = 1; // Acknowledgement that a published value was received. - PublishValuesResponse publish_value_response = 2; + PublishValuesResponse publish_values_response = 2; // Send a batch actuate request to a provider. - BatchActuateStreamRequest batch_actuate_stream_request = 3; + BatchActuateStreamRequest batch_actuate_stream_request = 3; } } From d11f942fc7700993409bd6eae57cf41fc0d4ad51 Mon Sep 17 00:00:00 2001 From: "Ruiz-Lucena Rafael (ETAS-E2E/XPC-Fe)" Date: Mon, 15 Jul 2024 10:35:19 +0200 Subject: [PATCH 19/21] Fix year comment --- proto/kuksa/val/v2/types.proto | 2 +- proto/kuksa/val/v2/val.proto | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/proto/kuksa/val/v2/types.proto b/proto/kuksa/val/v2/types.proto index 8f21cd60..9adc6053 100644 --- a/proto/kuksa/val/v2/types.proto +++ b/proto/kuksa/val/v2/types.proto @@ -1,5 +1,5 @@ /******************************************************************************** - * Copyright (c) 2022 Contributors to the Eclipse Foundation + * Copyright (c) 2024 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 03a6734d..8ebea5a4 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -1,5 +1,5 @@ /******************************************************************************** - * Copyright (c) 2022 Contributors to the Eclipse Foundation + * Copyright (c) 2024 Contributors to the Eclipse Foundation * * See the NOTICE file(s) distributed with this work for additional * information regarding copyright ownership. From 440b82af5eacb4c0291812669dd5dc73d38393e2 Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Thu, 15 Aug 2024 13:40:03 +0200 Subject: [PATCH 20/21] Introduce subscribe i32 parameter due to performance reasons --- proto/kuksa/val/v2/val.proto | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 8ebea5a4..6717f919 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -44,12 +44,18 @@ service VAL { // NOT_FOUND if the specified root branch does not exist. rpc ListValues(ListValuesRequest) returns (ListValuesResponse); - // Subscribe to a set of signals + // Subscribe to a set of signals using string path parameters // Returns (GRPC error code): // NOT_FOUND if any of the signals are non-existant. // PERMISSION_DENIED if access is denied for any of the signals. rpc Subscribe(SubscribeRequest) returns (stream SubscribeResponse); + // Subscribe to a set of signals using i32 id parameters + // Returns (GRPC error code): + // NOT_FOUND if any of the signals are non-existant. + // PERMISSION_DENIED if access is denied for any of the signals. + rpc SubscribeId(SubscribeRequestId) returns (stream SubscribeResponseId); + // Actuate a single actuator // // Returns (GRPC error code): @@ -136,13 +142,21 @@ message ListValuesResponse { } message SubscribeRequest { - repeated SignalID signal_ids = 1; + repeated string signal_path = 1; } message SubscribeResponse { map entries = 1; } +message SubscribeRequestId { + repeated int32 signal_ids = 1; +} + +message SubscribeResponseId { + map entries = 1; +} + message ActuateRequest { SignalID signal_id = 1; Value value = 2; @@ -173,7 +187,6 @@ message PublishValueRequest { } message PublishValueResponse { - Error error = 1; } message PublishValuesRequest { From 84477a21af44687024f15173ac671c90980fbb4f Mon Sep 17 00:00:00 2001 From: Rafael RL Date: Thu, 15 Aug 2024 14:03:51 +0200 Subject: [PATCH 21/21] Correct parameter name --- proto/kuksa/val/v2/val.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 6717f919..67d1a86f 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -142,7 +142,7 @@ message ListValuesResponse { } message SubscribeRequest { - repeated string signal_path = 1; + repeated string signal_paths = 1; } message SubscribeResponse {