yamcs.protobuf.commanding.commands_service.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.commanding;

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

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

import "yamcs/api/annotations.proto";
import "yamcs/api/httpbody.proto";
import "yamcs/protobuf/commanding/commanding.proto";
import "yamcs/protobuf/yamcs.proto";

service CommandsApi {

  // Issue a command
  //
  // After validating the input parameters, the command is added to the appropriate
  // command queue for further dispatch.
  rpc IssueCommand(IssueCommandRequest) returns (IssueCommandResponse) {
    option (yamcs.api.route) = {
      post: "/api/processors/{instance}/{processor}/commands/{name*}"
      body: "*"
    };
  }

  // Update command history
  rpc UpdateCommandHistory(UpdateCommandHistoryRequest) returns (google.protobuf.Empty) {
    option (yamcs.api.route) = {
      post: "/api/processors/{instance}/{processor}/commandhistory/{name*}"
      body: "*"
    };
  }

  // List commands
  rpc ListCommands(ListCommandsRequest) returns (ListCommandsResponse) {
    option (yamcs.api.route) = {
      get: "/api/archive/{instance}/commands"
    };
  }
  
  // Get a command
  rpc GetCommand(GetCommandRequest) returns (CommandHistoryEntry) {
    option (yamcs.api.route) = {
      get: "/api/archive/{instance}/commands/{id}"
    };
  }
  
  // Streams back commands
  rpc StreamCommands(StreamCommandsRequest) returns (stream CommandHistoryEntry) {
    option (yamcs.api.route) = {
      post: "/api/stream-archive/{instance}:streamCommands"
      body: "*"
    };
  }
  
  // Receive updates on issued commands
  rpc SubscribeCommands(SubscribeCommandsRequest) returns (stream CommandHistoryEntry) {
    option (yamcs.api.websocket) = {
      topic: "commands"
    };
  }
  
  // Export a raw command
  rpc ExportCommand(ExportCommandRequest) returns (yamcs.api.HttpBody) {
    option (yamcs.api.route) = {
      get: "/api/archive/{instance}/commands/{id}:export"
    };
  }

  // Export commands in CSV format
  rpc ExportCommands(ExportCommandsRequest) returns (stream yamcs.api.HttpBody) {
    option (yamcs.api.route) = {
      get: "/api/archive/{instance}:exportCommands"
    };
  }
}

message ListCommandsRequest {
  // Yamcs instance name
  optional string instance = 1;
  
  // The zero-based row number at which to start outputting results.
  // Default: ``0``
  // 
  // This option is deprecated and will be removed in a later version.
  // Use the returned continuationToken instead.
  optional int64 pos = 2 [deprecated = true];
  
  // The maximum number of returned records per page. Choose this value too
  // high and you risk hitting the maximum response size limit enforced by
  // the server. Default: ``100``
  optional int32 limit = 3;
  
  // The order of the returned results. Can be either ``asc`` or ``desc``.
  // Default: ``desc``
  optional string order = 4;
  
  // Text to search in the name of the command. This searches both the
  // qualified name, and any aliases.
  optional string q = 5;

  // Continuation token returned by a previous page response.
  optional string next = 6;
  
  // Filter the lower bound of the command's generation time. Specify a date
  // string in ISO 8601 format. This bound is inclusive.
  optional google.protobuf.Timestamp start = 7;
  
  // Filter the upper bound of the command's generation time. Specify a date
  // string in ISO 8601 format. This bound is exclusive.
  optional google.protobuf.Timestamp stop = 8;

  // Filter the results by the used queue.
  optional string queue = 9;
}

message IssueCommandRequest {
  message Assignment {
    optional string name = 1;
    optional string value = 2;
  }
  
  // Yamcs instance name
  optional string instance = 6;
  
  // Processor name
  optional string processor = 7;
  
  // Command name
  optional string name = 8;

  // The name/value assignments for this command.
  optional google.protobuf.Struct args = 16;

  // The origin of the command. Typically a hostname.
  optional string origin = 2;
  
  // The sequence number as specified by the origin. This gets
  // communicated back in command history and command queue entries,
  // thereby allowing clients to map local with remote command
  // identities.
  optional int32 sequenceNumber = 3;
  
  // Whether a response will be returned without actually issuing
  // the command. This is useful when debugging commands.
  // Default ``no``
  optional bool dryRun = 4;
  
  // Comment attached to this command.
  optional string comment = 5;
  
  // Override the stream on which the command should be sent out.
  //
  // Requires elevated privilege.
  optional string stream = 11;
  
  // Disable verification of all transmission constrains (if any
  // specified in the MDB).
  //
  // Requires elevated privilege.
  optional bool disableTransmissionConstraints = 12;
  
  // Disable all post transmission verifiers (if any specified in the MDB)
  //
  // Requires elevated privilege.
  optional bool disableVerifiers = 13;
  
  // Override verifier configuration. Keyed by verifier name
  //
  // Requires elevated privilege.
  map verifierConfig = 14;
  
  // Specify custom options for interpretation by non-core extensions.
  // Extensions must register these options against org.yamcs.YamcsServer
  map extra = 15;
}

message IssueCommandResponse {
  // Command ID
  optional string id = 5;

  // Command generation time
  optional google.protobuf.Timestamp generationTime = 6;

  // The origin of the command. Typically a hostname.
  optional string origin = 7;

  // The sequence number for the origin
  optional int32 sequenceNumber = 8;

  // Qualified name
  optional string commandName = 9;

  // Name aliases keyed by namespace.
  // (as currently present in Mission Database)
  map aliases = 14;

  // The name/value assignments for this command
  repeated CommandAssignment assignments = 12;

  // Generated binary, before any link post-processing
  optional bytes unprocessedBinary = 13;

  // Generated binary, after link post-processing.
  //
  // The differences compared to ``unprocessedBinary``,
  // can be anything. Typical manipulations include
  // sequence numbers or checksum calculations.
  optional bytes binary = 4;

  // Command issuer
  optional string username = 11;

  // Queue that was selected for this command
  optional string queue = 10;
}

message UpdateCommandHistoryRequest {
  // Yamcs instance name
  optional string instance = 1;
  
  // Processor name
  optional string processor = 2;
  
  // Command name
  optional string name = 3;

  // Command ID
  optional string id = 4;

  repeated commanding.CommandHistoryAttribute attributes = 5;
}

message ListCommandsResponse {
  // Deprecated, use ``commands`` instead
  repeated CommandHistoryEntry entry = 1 [deprecated=true];

  // Page  of matching commands
  repeated CommandHistoryEntry commands = 3;

  // Token indicating the response is only partial. More results can then
  // be obtained by performing the same request (including all original
  // query parameters) and setting the ``next`` parameter to this token.
  optional string continuationToken = 2;
}

message GetCommandRequest {
  // Yamcs instance name
  optional string instance = 1;

  // Command ID
  optional string id = 2;
}

message ExportCommandRequest {
  // Yamcs instance name
  optional string instance = 1;

  // Command ID
  optional string id = 2;
}

message StreamCommandsRequest {
  // Yamcs instance name
  optional string instance = 1;

  // Filter the lower bound of the command's generation time. Specify a date
  // string in ISO 8601 format.
  optional google.protobuf.Timestamp start = 2;

  // Filter the upper bound of the command's generation time. Specify a date
  // string in ISO 8601 format.
  optional google.protobuf.Timestamp stop = 3;

  // Command names to include. Leave unset, to include all.
  repeated string name = 4;
}

message SubscribeCommandsRequest {
  // Yamcs instance name
  optional string instance = 1;

  // Processor name
  optional string processor = 2;

  // If true, send only updates for commands that
  // were issued after the subscription start.
  //
  // For clients that piece together command updates, this
  // can help avoid partially received commands. 
  optional bool ignorePastCommands = 3;
}

message ExportCommandsRequest {
  // Yamcs instance name
  optional string instance = 1;

  // Filter the lower bound of the command's generation time.
  // Specify a date string in ISO 8601 format. This bound is inclusive.
  optional google.protobuf.Timestamp start = 2;

  // Filter the upper bound of the command's generation time. Specify a date
  // string in ISO 8601 format. This bound is exclusive.
  optional google.protobuf.Timestamp stop = 3;

  // Command names to include. Leave unset, to include all.
  repeated string name = 4;

  // Column delimiter. One of ``TAB``, ``COMMA`` or ``SEMICOLON``.
  // Default: ``TAB``.
  optional string delimiter = 5;
}