yamcs.protobuf.processing.processing.proto Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of yamcs-api Show documentation
Used by external clients to communicate with Yamcs
There is a newer version: 5.10.9
syntax="proto2";
  
package yamcs.protobuf.processing;

option java_package = "org.yamcs.protobuf";
option java_outer_classname = "ProcessingProto";
option java_multiple_files = true;

import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";

import "yamcs/api/annotations.proto";
import "yamcs/protobuf/mdb/mdb.proto";
import "yamcs/protobuf/pvalue/pvalue.proto";
import "yamcs/protobuf/yamcsManagement/yamcsManagement.proto";
import "yamcs/protobuf/yamcs.proto";

service ProcessingApi {

  // List processor types
  rpc ListProcessorTypes(google.protobuf.Empty) returns (ListProcessorTypesResponse) {
    option (yamcs.api.route) = {
      get: "/api/processor-types"
    };
  }
  
  // List processors
  rpc ListProcessors(ListProcessorsRequest) returns (ListProcessorsResponse) {
    option (yamcs.api.route) = {
      get: "/api/processors"
    };
  }
  
  // Get a processor
  rpc GetProcessor(GetProcessorRequest) returns (yamcsManagement.ProcessorInfo) {
    option (yamcs.api.route) = {
      get: "/api/processors/{instance}/{processor}"
    };
  }
  
  // Delete a processor
  //
  // Only replay processors can be removed.
  rpc DeleteProcessor(DeleteProcessorRequest) returns (google.protobuf.Empty) {
    option (yamcs.api.route) = {
      delete: "/api/processors/{instance}/{processor}"
    };
  }
  
  // Update a processor
  rpc EditProcessor(EditProcessorRequest) returns (google.protobuf.Empty) {
    option (yamcs.api.route) = {
      patch: "/api/processors/{instance}/{processor}"
      body: "*"
    };
  }
  
  // Create a processor
  rpc CreateProcessor(CreateProcessorRequest) returns (google.protobuf.Empty) {
    option (yamcs.api.route) = {
      post: "/api/processors"
      body: "*"
    };
  }

  // Get a parameter's value
  rpc GetParameterValue(GetParameterValueRequest) returns (pvalue.ParameterValue) {
    option (yamcs.api.route) = {
      get: "/api/processors/{instance}/{processor}/parameters/{name*}"
    };
  }
  
  // Set a parameter's value
  //
  // Only some type of parameters can be updated.
  rpc SetParameterValue(SetParameterValueRequest) returns (google.protobuf.Empty) {
    option (yamcs.api.route) = {
      put: "/api/processors/{instance}/{processor}/parameters/{name*}"
      body: "value"
      additional_bindings {
        post: "/api/processors/{instance}/{processor}/parameters/{name*}"
        body: "value"
      }
    };
  }
  
  // Batch get the value of multiple parameters
  rpc BatchGetParameterValues(BatchGetParameterValuesRequest) returns (BatchGetParameterValuesResponse) {
    option (yamcs.api.route) = {
      post: "/api/processors/{instance}/{processor}/parameters:batchGet"
      body: "*"
    };
  }
  
  // Batch set the value of multiple parameters
  rpc BatchSetParameterValues(BatchSetParameterValuesRequest) returns (google.protobuf.Empty) {
    option (yamcs.api.route) = {
      post: "/api/processors/{instance}/{processor}/parameters:batchSet"
      body: "*"
    };
  }

  // Receive TM statistics updates
  rpc SubscribeTMStatistics(SubscribeTMStatisticsRequest) returns (stream yamcsManagement.Statistics) {
    option (yamcs.api.websocket) = {
      topic: "tmstats"
    };
  }
  
  // Receive parameter updates
  //
  // The input message can be sent multiple types, allowing to alter a
  // subscription with the ``action`` field.
  rpc SubscribeParameters(stream SubscribeParametersRequest) returns (stream SubscribeParametersData) {
    option (yamcs.api.websocket) = {
      topic: "parameters"
    };
  }
  
  // Receive processor updates
  rpc SubscribeProcessors(SubscribeProcessorsRequest) returns (stream yamcsManagement.ProcessorInfo) {
    option (yamcs.api.websocket) = {
      topic: "processors"
    };
  }

 // Get the algorithm status
  rpc GetAlgorithmStatus(GetAlgorithmStatusRequest) returns (AlgorithmStatus) {
    option (yamcs.api.route) = {
      get: "/api/processors/{instance}/{processor}/algorithms/{name*}/status"
    };
  }
  
  // Receive algorithm status updates
  rpc SubscribeAlgorithmStatus(SubscribeAlgorithmStatusRequest) returns (stream AlgorithmStatus) {
    option (yamcs.api.websocket) = {
      topic: "algorithm-status"
    };
  }
  
  // Get the algorithm trace
  rpc GetAlgorithmTrace(GetAlgorithmTraceRequest) returns (AlgorithmTrace) {
    option (yamcs.api.route) = {
      get: "/api/processors/{instance}/{processor}/algorithms/{name*}/trace"
    };
  }

  // Enable/disable algorithm tracing
  rpc EditAlgorithmTrace(EditAlgorithmTraceRequest) returns (google.protobuf.Empty) {
    option (yamcs.api.route) = {
      patch: "/api/processors/{instance}/{processor}/algorithms/{name*}/trace"
      body: "*"
    };
  }
}

// Response message for `ListProcessorTypes`
message ListProcessorTypesResponse {
  repeated string types = 1;
}

// Request message for `ListProcessors`.
message ListProcessorsRequest {
  // Return only processors of this instance
  optional string instance = 1;
}

// Response message for `ListProcessors`.
message ListProcessorsResponse {
  repeated yamcsManagement.ProcessorInfo processors = 1;
}

// Request message for `SubscribeTMStatistics`.
message SubscribeTMStatisticsRequest {
  // Yamcs instance name
  optional string instance = 1;

  // Processor name
  optional string processor = 2;
}

// Request message for `SubscribeProcessors`.
message SubscribeProcessorsRequest {
  // Yamcs instance name
  optional string instance = 1;

  // Processor name
  optional string processor = 2;
}

// Request message for `SubscribeParameters`.
message SubscribeParametersRequest {

  // Specifies what Yamcs should do with the parameter identifiers
  // that are specifiedwith the ``id`` field.
  enum Action {

    // The parameter identifiers specified with ``id``, replace any that were
    // previously subscribed to on this call.
    REPLACE = 0;

    // The parameter identifiers specified with ``id`` are added to any
    // that were previously subscribed to on this call.
    ADD = 1;

    // The parameter identifiers specified with ``id`` are removed from those
    // that were previously subscribed to on this call.
    REMOVE = 2;
  }
  
  // Yamcs instance name
  optional string instance = 1;
 
  // Processor name
  optional string processor = 2;

  // Parameter identifiers. Each identifier takes the form of
  // a namespace and a name.
  //
  // For Yamcs-native naming only the name field is required and
  // should be the fully qualified name. The namespace is only
  // required when the name represents an alias of that parameter.
  repeated NamedObjectId id = 3;

  // Send an error message if any parameter is invalid.
  // Default: true
  optional bool abortOnInvalid = 4;

  // Send parameter updates when parameters expire.
  // The update will have the same value and timestamp like
  // the preceding update, but with acquisition status set to
  // EXPIRED (instead of ACQUIRED)
  // Default: false
  optional bool updateOnExpiration = 5;

  // If available, send immediately the last cached value
  // of each subscribed parameter.
  // Default: true
  optional bool sendFromCache = 6;
  
  // How to interpret the submitted parameter ids. Default
  // is to replace an existing subscription with the newly
  // submitted list.
  optional Action action = 7;

  // If set, truncate binary values to the specified byte length.
  // This may be necessary when Yamcs contains large binary values.
  //
  // A negative value implies no truncating, which is the default.
  optional int32 maxBytes = 8;
}

message SubscribeParametersData {
  // Mapping between numeric and subscribed identifier.
  // This information is provided only once, following a subscription.
  map mapping = 1;

  // Mapping between numeric identifier, and matching parameter.
  // This information is provided only once, following a subscription.
  map info = 4;

  // Parameter identifiers that were subscribed to, but that
  // cannot be matched against the Mission Database.
  repeated NamedObjectId invalid = 2;

  // Values of updated parameters.
  repeated pvalue.ParameterValue values = 3;
}

// Static information for a subscribed parameter.
message SubscribedParameterInfo {
  // Qualified parameter name
  optional string parameter = 1;

  // Engineering units
  optional string units =  2;

  // Data source
  optional mdb.DataSourceType dataSource = 3;

  // Enumeration states, in case this concerns an enumerated parameter
  repeated mdb.EnumValue enumValues = 4;
}

// Request message for `GetProcessor`.
message GetProcessorRequest {
  // Yamcs instance name
  optional string instance = 1;

  // Processor name
  optional string processor = 2;
}

// Request message for `DeleteProcessor`.
message DeleteProcessorRequest {
  // Yamcs instance name
  optional string instance = 1;

  // Processor name
  optional string processor = 2;
}

// Request message for `CreateProcessor`.
message CreateProcessorRequest {
  // **Required.** The name of the Yamcs instance.
  optional string instance = 1;

  // **Required.** The name of the processor. Must be unique for the Yamcs instance.
  optional string name = 2;

  // Keep the processor when terminated. Default: ``no``.
  optional bool persistent = 4;

  // **Required.** The type of the processor. The available values depend on how
  // Yamcs Server is configured. Most Yamcs deployments support at least a type
  // ``Archive`` which allows for the creation of processors replaying archived
  // data.
  optional string type = 5;

  // Configuration options specific to the processor type. Note that this should
  // be a string representation of a valid JSON structure.
  optional string config = 6;
}

// Request message for `EditProcessor`.
message EditProcessorRequest {
  // Yamcs instance name
  optional string instance = 1;

  // Processor name
  optional string processor = 2;
  
  // The state this replay processor should be updated to. Either ``paused`` or
  // ``running``.
  optional string state = 3;
  
  // The time where the processing needs to jump towards. Must be a date string
  // in ISO 8601 format.
  optional google.protobuf.Timestamp seek = 4;
  
  // The speed of the processor. One of:
  // * ``afap``
  // * a speed factor relative to the original speed. Example: ``2x``
  // * a fixed delay value in milliseconds. Example: ``2000``
  optional string speed = 5;

  // New start time
  optional google.protobuf.Timestamp start = 6;

  // New stop time
  optional google.protobuf.Timestamp stop = 7;

  // Continue replaying from ``start`` after having reached ``stop``.
  optional bool loop = 8;
}

// Request message for `GetParameterValue`.
message GetParameterValueRequest {
  // Yamcs instance name.
  optional string instance = 1;

  // Processor name
  optional string processor = 2;

  // Parameter name.
  optional string name = 3;

  // Whether the latest cached value may be returned. Default: ``yes``.
  optional bool fromCache = 4;
  
  // Time in milliseconds to wait on a value (only considered if
  // ``fromCache=no``). When the timeout is met, the call will return
  // with no or partial data. Default: ``10000``.
  optional uint64 timeout = 5;
}

// Request message for `SetParameterValue`.
message SetParameterValueRequest {
  // Yamcs instance name
  optional string instance = 1;
  
  // Processor name
  optional string processor = 2;
  
  // Parameter name
  optional string name = 3;
  
  // The new value
  optional Value value = 4;

  // The generation time of the value. If specified, must be a date
  // string in ISO 8601 format.
  optional google.protobuf.Timestamp generationTime = 5;

  // How long before this value is expired, in milliseconds
  optional uint64 expiresIn = 6;
}

// Request message for `BatchGetParameterValues`.
message BatchGetParameterValuesRequest {
  // Yamcs instance name
  optional string instance = 4;
  
  // Processor name
  optional string processor = 5;

  // Parameter identifiers. Each identifier takes the form of
  // a namespace and a name.
  //
  // For Yamcs-native naming only the name field is required and
  // should be the fully qualified name. The namespace is only
  // required when the name represents an alias of that parameter.
  repeated NamedObjectId id = 1;

  optional bool fromCache = 2;

  // If not fromCache, wait this time (in milliseconds) to receive the parameter
  optional uint64 timeout = 3;
}

// Response message for `BatchGetParameterValues`.
message BatchGetParameterValuesResponse {
  repeated pvalue.ParameterValue value = 1;
}

// Request message for `BatchSetParameterValues`.
message BatchSetParameterValuesRequest {
  message SetParameterValueRequest {
    // Parameter identifier. This takes the form of a namespace and
    // a name.
    //
    // For Yamcs-native naming only the name field is required and
    // should be the fully qualified name. The namespace is only
    // required when the name represents an alias of that parameter.
    optional NamedObjectId id = 1;

    // The new value
    optional Value value = 2;

    // The generation time of the value. If specified, must be a date
    // string in ISO 8601 format.
    optional google.protobuf.Timestamp generationTime = 3;

    // How long before this value is expired, in milliseconds
    optional uint64 expiresIn = 4;
  }
  
  // Yamcs instance name
  optional string instance = 2;
  
  // Processor name
  optional string processor = 3;

  // Requests, one for each new value
  repeated SetParameterValueRequest request = 1;
}

// Request message for `GetAlgorithmStatus`.
message GetAlgorithmStatusRequest {
  // Yamcs instance name.
  optional string instance = 1;
  
  // Processor name
  optional string processor = 2;
  
  // Algorithm name
  optional string name = 3;
}

// Request message for `SubscribeAlgorithmStatus`.
message SubscribeAlgorithmStatusRequest {
  // Yamcs instance name
  optional string instance = 1;
  
  // Processor name
  optional string processor = 2;
  
  // Algorithm name
  optional string name = 3;
}

// Request message for `GetAlgorithmTrace`.
message GetAlgorithmTraceRequest {
  // Yamcs instance name
  optional string instance = 1;
  
  // Processor name
  optional string processor = 2;
  
  // Algorithm name
  optional string name = 3;
}

// Request message for `EditAlgorithmTrace`.
message EditAlgorithmTraceRequest {
  // Yamcs instance name
  optional string instance = 1;
  
  // Processor name
  optional string processor = 2;
  
  // Algorithm name
  optional string name = 3;

  // Trace state: either ``enabled`` or ``disabled``.
  optional string state = 4;
}

message AlgorithmStatus {

  //true if the algorithm is active
  optional bool active = 1;
  
  //true if the tracing has been enabled 
  optional bool traceEnabled = 2;
    
  // how many times the algorithm ran (successfully or with error)
  optional uint32 runCount = 3;
  
  // when the algorithm was last run
  optional google.protobuf.Timestamp lastRun = 4;
  
  // how many times the algorithm ran with errors
  optional uint32 errorCount = 5;
  
  // if the algorithm produced an error, 
  // the fields below contain the error message and the time when the error was raised 
  optional string errorMessage = 6;
  optional google.protobuf.Timestamp errorTime = 7;
  
  //total execution time in nanoseconds
  optional uint64 execTimeNs = 8;
}

message AlgorithmTrace {

  // A single execution of an algorithm
  message Run {
    // When this run was started
    optional google.protobuf.Timestamp time = 1;

    // Values of input parameters for this run
    repeated pvalue.ParameterValue inputs = 2;

    // Values of output parameters for this run
    repeated pvalue.ParameterValue outputs = 3;

    // The return value, if the algorithm returned something.
    // This can be useful in the context of verifiers.
    optional string returnValue = 4;

    // Error message, if any
    optional string error = 5;
  }

  // A log message that was emitted by the algorithm
  // using the `Yamcs.log` function.
  message Log {
    // Log time
    optional google.protobuf.Timestamp time = 2;

    // Logged message
    optional string msg = 3;
  }

  // Latest algorithm runs
  repeated Run runs = 1;

  // Latest log entries
  repeated Log logs = 2;
}