sdv_databroker_v1_collector.proto

/********************************************************************************
 * 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 sdv.databroker.v1;

import "google/protobuf/timestamp.proto";

// Data type of a signal
//
// Protobuf doesn't support int8, int16, uint8 or uint16.
// These are mapped to sint32 and uint32 respectively.
//
enum DataType {
  STRING       = 0;
  BOOL         = 1;
  INT8         = 2;
  INT16        = 3;
  INT32        = 4;
  INT64        = 5;
  UINT8        = 6;
  UINT16       = 7;
  UINT32       = 8;
  UINT64       = 9;
  FLOAT        = 10;
  DOUBLE       = 11;
  STRING_ARRAY = 20;
  BOOL_ARRAY   = 21;
  INT8_ARRAY   = 22;
  INT16_ARRAY  = 23;
  INT32_ARRAY  = 24;
  INT64_ARRAY  = 25;
  UINT8_ARRAY  = 26;
  UINT16_ARRAY = 27;
  UINT32_ARRAY = 28;
  UINT64_ARRAY = 29;
  FLOAT_ARRAY  = 30;
  DOUBLE_ARRAY = 31;
}

enum DatapointError {
  UNKNOWN_DATAPOINT = 0;
  INVALID_TYPE      = 1;
  ACCESS_DENIED     = 2;
  INTERNAL_ERROR    = 3;
  OUT_OF_BOUNDS     = 4;
}

enum EntryType {
  ENTRY_TYPE_UNSPECIFIED = 0;
  ENTRY_TYPE_SENSOR      = 1;
  ENTRY_TYPE_ACTUATOR    = 2;
  ENTRY_TYPE_ATTRIBUTE   = 3;
}

enum ChangeType {
  STATIC    = 0;   // Value never changes
  ON_CHANGE = 1;   // Updates are provided every time the value changes (i.e.
                   // window is open / closed)
  CONTINUOUS = 2;  // Value is updated continuously. Broker needs to tell
                   // provider the preferred (update) frequency.
}

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

message Datapoint {
  // Timestamp of the value
  google.protobuf.Timestamp timestamp = 1;

  // values
  oneof value {
    Failure failure_value    = 10;
    string string_value      = 11;
    bool bool_value          = 12;
    sint32 int32_value       = 13;
    sint64 int64_value       = 14;
    uint32 uint32_value      = 15;
    uint64 uint64_value      = 16;
    float float_value        = 17;
    double double_value      = 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;
  }

  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 {
  // Id to be used in "get" and "subscribe" requests. Ids stay valid during
  // one power cycle, only.
  int32 id               = 1;
  EntryType entry_type   = 2;
  string name            = 4;
  DataType data_type     = 5;
  ChangeType change_type = 6;  // CONTINUOUS or STATIC or ON_CHANGE
  string description     = 7;

  // int32             min_update_hz       = 10; // Only for CONTINUOUS
  // int32             max_update_hz       = 11; // Only for CONTINUOUS
}

service Collector {
  // Register new datapoint (metadata)
  //
  // If the registration of at least one of the passed data point fails, the overall registration
  // is rejected and the gRPC status code ABORTED is returned (to indicate the "aborted" registration).
  // The details, which data point(s) caused the failure and the reason, is passed in back in human-
  // readable form in the status message. Possible failure resaons are:
  //  * PERMISSION_DENIED - Not allowed to register this name
  //  * ALREADY_REGISTERED - The data point is already registered by some other feeder
  //  * RE_REGISTRATION_MISMATCH - Already registered by this feeder but with differing metadata
  //  * INVALID_NAME - The passed name of the datapoint has an invalid structure
  //  * INVALID_VALUE_TYPE - The passed ValueType is not supported
  //  * INVALID_CHANGE_TYPE - The passed ChangeType is not supported
  rpc RegisterDatapoints(RegisterDatapointsRequest) returns (RegisterDatapointsReply);

  // Provide a set of updated datapoint values to the broker.
  // This is the unary equivalent of `StreamDatapoints` below and is better suited for cases
  // where the frequency of updates is rather low.
  //
  // NOTE: The values provided in a single request are handled as a single update in the
  // data broker. This ensures that any clients requesting (or subscribing to) a set of
  // datapoints will get a consistent update, i.e. that either all values are updated or
  // none are.
  //
  // Returns: any errors encountered updating the datapoints
  //
  rpc UpdateDatapoints(UpdateDatapointsRequest) returns (UpdateDatapointsReply);

  // Provide a stream with updated datapoint values to the broker.
  // This is the streaming equivalent of `UpdateDatapoints` above and is better suited for
  // cases where the frequency of updates is high.
  //
  // NOTE: The values provided in a single request are handled as a single update in the
  // data broker. This ensures that any clients requesting (or subscribing to) a set of
  // datapoints will get a consistent update, i.e. that either all values are updated or
  // none are.
  //
  // Returns: any errors encountered updating the datapoints
  //
  rpc StreamDatapoints(stream StreamDatapointsRequest) returns (stream StreamDatapointsReply);
}

message UpdateDatapointsRequest {
  map<int32, Datapoint> datapoints = 1;
}

message UpdateDatapointsReply {
  map<int32, DatapointError> errors = 1;  // If empty, everything went well
}

message StreamDatapointsRequest {
  map<int32, Datapoint> datapoints = 1;
}

message StreamDatapointsReply {
  map<int32, DatapointError> errors = 1;  // If empty, everything went well
}

message RegisterDatapointsRequest {
  repeated RegistrationMetadata list = 1;
}

message RegistrationMetadata {
  // Name of the data point
  // (e.g. "Vehicle.Cabin.Seat.Row1.Pos1.Position" or "Vehicle.Speed")
  string name            = 1;
  DataType data_type     = 2;
  string description     = 3;
  ChangeType change_type = 4;

  // int32             min_update_hz       = 10; // Only for CONTINUOUS
  // int32             max_update_hz       = 11; // Only for CONTINUOUS
};

message RegisterDatapointsReply {
  // Maps each data point name passed in RegisterDatapointsRequest to a data point id
  map<string, int32> results = 1;
}