yamcs.protobuf.activities.activities_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.activities;

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

import "google/protobuf/timestamp.proto";

import "yamcs/api/annotations.proto";
import "yamcs/protobuf/activities/activities.proto";

service ActivitiesApi {

  // List activities
  rpc ListActivities(ListActivitiesRequest) returns (ListActivitiesResponse) {
    option (yamcs.api.route) = {
      get: "/api/activities/{instance}/activities"
    };
  }

  // Get an activity
  rpc GetActivity(GetActivityRequest) returns (ActivityInfo) {
    option (yamcs.api.route) = {
      get: "/api/activities/{instance}/activities/{activity}"
    };
  }

  // Get the activity log
  rpc GetActivityLog(GetActivityLogRequest) returns (GetActivityLogResponse) {
    option (yamcs.api.route) = {
      get: "/api/activities/{instance}/activities/{activity}/log"
    };
  }

  // Start an activity
  //
  // The request body allows for the execution of arbitrary activities.
  // The following activity types are included in the core Yamcs module:
  //
  // .. rubric:: Command
  //
  // Execute a single command
  //
  // ``type`` (string)
  //     Set to ``COMMAND``.
  //
  // ``args`` (map)
  //     Map accepting the following options:
  //
  //     ``command``
  //         **Required.** Qualified name of a command
  //
  //     ``args`` (map)
  //         Named arguments, if the command requires any
  //
  //     ``extra`` (map)
  //         Extra command options
  //
  //     ``processor`` (string)
  //         Optional processor name. If not provided, Yamcs defaults
  //         to any processor it can find with commanding enabled.
  //
  // Example:
  //
  // .. code-block:: json
  //
  //     {
  //         "type": "COMMAND",
  //         "args": {
  //             "command": "/YSS/SIMULATOR/SWITCH_VOLTAGE_ON",
  //             "args": {
  //                 "voltage_num": 3
  //             },
  //             "processor": "realtime"
  //         }
  //     }
  //
  // .. rubric:: Command Stack
  //
  // Execute a command stack
  //
  // ``type`` (string)
  //     Set to ``COMMAND_STACK``.
  //
  // ``args`` (map)
  //     Map accepting the following options:
  //
  //     ``bucket``
  //         **Required.** The name of the bucket containg the stack
  //
  //     ``stack``
  //         **Required.** The name of the stack object inside the bucket
  //
  //     ``processor`` (string)
  //         Optional processor name. If not provided, Yamcs defaults
  //         to any processor it can find with commanding enabled.
  //
  // Example:
  //
  // .. code-block:: json
  //
  //     {
  //         "type": "COMMAND_STACK",
  //         "args": {
  //             "bucket": "mybucket",
  //             "stack": "mystack.ycs",
  //             "processor": "realtime"
  //         }
  //     }
  //
  // .. rubric:: Script
  //
  // Run a script
  //
  // ``type`` (string)
  //     Set to ``SCRIPT``.
  // ``args`` (map)
  //     Map accepting the following options:
  //
  //     ``script``
  //         **Required.** Script identifier.
  //
  //         This should be the relative path to an executable file in one of the
  //         search locations. When unconfigured, the default search location is
  //         :file:`etc/scripts/` relative to the Yamcs working directory.
  //
  //     ``args`` (string or string[])
  //         Script arguments
  //
  //     ``processor`` (string)
  //         If provided, this information is passed to the script in an environment
  //         variable ``YAMCS_PROCESSOR``.
  //
  // Example:
  //
  // .. code-block:: json
  //
  //     {
  //         "type": "SCRIPT",
  //         "args": {
  //             "script": "simulate_los.py",
  //             "args": "--duration 60",
  //             "processor": "realtime"
  //         }
  //     }
  rpc StartActivity(StartActivityRequest) returns (ActivityInfo) {
    option (yamcs.api.route) = {
      post: "/api/activities/{instance}/activities",
      body: "activityDefinition"
    };
  }

  // Cancel an ongoing activity
  rpc CancelActivity(CancelActivityRequest) returns (ActivityInfo) {
    option (yamcs.api.route) = {
      post: "/api/activities/{instance}/activities/{activity}:cancel"
    };
  }

  // Mark an ongoing activity as completed.
  //
  // This method may only be used with manual activities.
  rpc CompleteManualActivity(CompleteManualActivityRequest) returns (ActivityInfo) {
    option (yamcs.api.route) = {
      post: "/api/activities/{instance}/activities/{activity}:complete",
      body: "*"
    };
  }

  // Receive activity status updates
  rpc SubscribeGlobalStatus(SubscribeGlobalStatusRequest) returns (stream GlobalActivityStatus) {
    option (yamcs.api.websocket) = {
      topic: "global-activity-status"
    };
  }

  // Receive activity updates
  rpc SubscribeActivities(SubscribeActivitiesRequest) returns (stream ActivityInfo) {
    option (yamcs.api.websocket) = {
      topic: "activities"
    };
  }

  // Receive activity log updates
  rpc SubscribeActivityLog(SubscribeActivityLogRequest) returns (stream ActivityLogInfo) {
    option (yamcs.api.websocket) = {
      topic: "activity-log"
    };
  }

  // List available executors
  rpc ListExecutors(ListExecutorsRequest) returns (ListExecutorsResponse) {
    option (yamcs.api.route) = {
      get: "/api/activities/{instance}/executors"
    };
  }

  // List scripts available for activities of type SCRIPT
  rpc ListScripts(ListScriptsRequest) returns (ListScriptsResponse) {
    option (yamcs.api.route) = {
      get: "/api/activities/{instance}/scripts"
    };
  }
}

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

  // 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 = 2;
  
  // The order of the returned results. Can be either ``asc`` or ``desc``.
  // Default: ``desc``
  optional string order = 3;

  // Filter on activity status
  repeated string status = 4;

  // The type of activity. Names must match exactly.
  repeated string type = 5;

  // Continuation token returned by a previous page response.
  optional string next = 6;

  // Filter the lower bound of the activity's start 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 activity's generation time. Specify a
  // datestring in ISO 8601 format. This bound is exclusive.
  optional google.protobuf.Timestamp stop = 8;

  // Text to search for in the description.
  optional string q = 9;
}

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

  // Activity identifier
  optional string activity = 2;
}

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

  // Activity identifier
  optional string activity = 2;
}

message GetActivityLogResponse {
  // Log entries
  repeated ActivityLogInfo logs = 1;
}

message ListActivitiesResponse {
  // Resulting activities, possibly limited   
  repeated ActivityInfo activities = 1;

  // 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 ListExecutorsRequest {
  // Yamcs instance name
  optional string instance = 1;
}

message ListExecutorsResponse {
  // Yamcs instance name
  repeated ExecutorInfo executors = 1;
}

message ListScriptsRequest {
  // Yamcs instance name
  optional string instance = 1;
}

message ListScriptsResponse {
  repeated string scripts = 1;
}

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

  // Activity definition
  optional ActivityDefinitionInfo activityDefinition = 2;
}

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

  // Activity identifier
  optional string activity = 2;
}

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

  // Activity identifier
  optional string activity = 2;

  // Failure message, if not provided the
  // activity is considered successful.
  optional string failureReason = 3;
}

message SubscribeActivitiesRequest {
  // Yamcs instance name
  optional string instance = 1;
}

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

  // Activity identifier
  optional string activity = 2;
}

message SubscribeGlobalStatusRequest {
  // Yamcs instance name
  optional string instance = 1;
}

message GlobalActivityStatus {
  // The number of ongoing activities
  optional int32 ongoingCount = 1;
}