Init Databroker API V2

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;
+}

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;
+}