sdv_databroker_v1_broker.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;
  TIMESTAMP    = 12;
  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;
  TIMESTAMP_ARRAY = 32;
}

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 Broker {
  // Request a set of datapoints (values)
  //
  // Returns a list of requested data points.
  //
  // InvalidArgument is returned if the request is malformed.
  rpc GetDatapoints(GetDatapointsRequest) returns (GetDatapointsReply);

  // Set a datapoint (values)
  rpc SetDatapoints(SetDatapointsRequest) returns (SetDatapointsReply);

  // Subscribe to a set of data points or conditional expressions
  // using the Data Broker Query Syntax (described in QUERY.md)
  //
  // Returns a stream of replies.
  //
  // InvalidArgument is returned if the request is malformed.
  rpc Subscribe(SubscribeRequest) returns (stream SubscribeReply);

  // Request the metadata of a set of datapoints
  //
  // Returns metadata of the requested data points that exist.
  rpc GetMetadata(GetMetadataRequest) returns (GetMetadataReply);
}

message GetDatapointsRequest {
  // A list of requested data points.
  repeated string datapoints = 1;
}

message GetDatapointsReply {
  // Contains the values of the requested data points.
  // If a requested data point is not available, the corresponding Datapoint
  // will have the respective failure value set.
  map<string, Datapoint> datapoints = 1;
}

message SetDatapointsRequest {
  // A map of data points to set
  map<string, Datapoint> datapoints = 1;
}

message SetDatapointsReply {
  // A map of errors (if any)
  map<string, DatapointError> errors = 1;
}

message SubscribeRequest {
  // Subscribe to a set of data points (or expressions) described
  // by the provided query.
  // The query syntax is a subset of SQL and is described in more
  // detail in the QUERY.md file.
  string query = 2;
}

message SubscribeReply {
  // Contains the fields specified by the query.
  // If a requested data point value is not available, the corresponding
  // Datapoint will have it's respective failure value set.
  map<string, Datapoint> fields = 1;
}

message GetMetadataRequest {
  // Request metadata for a list of data points referenced by their names.
  // e.g. "Vehicle.Cabin.Seat.Row1.Pos1.Position" or "Vehicle.Speed".
  //
  // If no names are provided, metadata for all known data points will be
  // returned.
  repeated string names = 1;
}

message GetMetadataReply {
  // Contains metadata of the requested data points. If a data point
  // doesn't exist (i.e. not known to the Data Broker) the corresponding
  // Metadata isn't part of the returned list.
  repeated Metadata list = 1;
}