package stellarstation.api.v1
Get desktop application:
View/edit binary Protocol Buffers messages
The public API service of StellarStation, a system supporting communication between satellites and ground stations. This API is for use by an operator of a satellite - it is invalid to specify satellites that the operator does not own or plans they have not reserved. Only using IDs shown on the StellarStation Console or returned in API responses will ensure all inputs are valid. A pass is a time range where an ground station and satellite can communicate with each other, i.e., the period between Acquisition of Signal (AOS) and Loss of Signal (LOS) of the ground station and satellite pair. A plan is a scheduled pass that will be executed to send and receive data between the ground station and satellite during the time range.
rpc AddTle (, )
stellarstation.proto:131Adds TLE for a satellite. The TLE will be used for satellite orbit calculation until it is superseded by a newly added TLE. Adding TLE using this API will automatically change the satellite's TLE source to `MANUAL` if it was previously set to `NORAD` to allow for immediate use. An 'INVALID_ARGUMENT' error will be returned in the following conditions: - the TLE cannot be parsed - the TLE norad ID does not correspond to the requested satellite. If the satellite is not found or the client is not authorized for it, the request will return a `NOT_FOUND` error.
message
stellarstation.proto:661Request for the 'AddTle' method.
string satellite_id = 1
The ID of the satellite to add TLE for. The ID can be found on the StellarStation Console page for the satellite.
optional tle = 2
The TLE to be added.
message
stellarstation.proto:671Response for the `AddTle` method.
Currently no payload in the response.
(message has no fields)
rpc CancelPlan (, )
stellarstation.proto:68Cancel a previously reserved upcoming plan. Cancelling the plan will cause it to not be executed. This action cannot be undone, but it is still possible to reserve the corresponding pass again by calling `ListUpcomingAvailablePasses` and `ReservePass` as usual - this will cause a new plan to be reserved. The plan cannot be cancelled less than ten minutes before AOS. Canceling a plan may incur a charge based on the time left to AOS. See our cancellation policy for details. If the plan is not found, the request will return a `NOT_FOUND` error. If the plan has already been canceled or is less than ten minutes away from its AOS, the request will return a `FAILED_PRECONDITION` error. If the plan is ongoing or has already finished executing, the request will return a `OUT_OF_RANGE` error.
message
stellarstation.proto:405Request for the `CancelPlan` method.
string plan_id = 1
The id of the plan to cancel, i.e., the value of `Plan.id`.
message
stellarstation.proto:411Response for the `CancelPlan` method.
Currently no payload in the response.
(message has no fields)
rpc GetTle (, )
stellarstation.proto:140Gets the TLE for a satellite. The returned TLE will be the one that has most recently been added to StellarStation and matches the satellite's TLE source. This TLE is used when calculating satellite orbits. If the satellite is not found or the client is not authorized for it, the request will return a `NOT_FOUND` error.
message
stellarstation.proto:676Request for the 'GetTle' method.
string satellite_id = 1
The ID of the satellite for which to fetch TLE. The ID can be found on the StellarStation Console page for the satellite.
message
stellarstation.proto:683Response for the 'GetTle' method.
optional tle = 1
The TLE for the given satellite.
rpc ListPlans (, )
stellarstation.proto:50Lists the plans for a particular satellite. The request will be closed with an `INVALID_ARGUMENT` status if `satellite_id`, `aos_after`, or `aos_before` are missing, or the duration between the two times is longer than 31 days.
message
stellarstation.proto:451Request for the `ListPlans` method.
string satellite_id = 1
The ID of the satellite to list plans for. The ID can be found on the StellarStation Console page for the satellite.
optional aos_after = 2
The start time of the range of plans to list (inclusive). Only plans with an Acquisition of Signal (AOS) at or after this time will be returned. It is an error for the duration between `aos_after` and `aos_before` to be longer than 31 days.
optional aos_before = 3
The end time of the range of plans to list (exclusive). Only plans with an Acquisition of Signal (AOS) before this time will be returned. It is an error for the duration between `aos_after` and `aos_before` to be longer than 31 days.
message
stellarstation.proto:468A response from the `ListPlans` method.
repeated plan = 1
The requested list of plans for the satellite.
Lists upcoming passes for a satellite. Passes that can be scheduled for the satellite with an Acquisition of Signal (AOS) within 14 days from now will be returned. This method does not reserve passes in any way - it is possible for a pass that is returned by this method to be unschedulable when actually trying to schedule because a conflict appeared during that time. If the satellite is not found or the client is not authorized for it, the request will return a `NOT_FOUND` error.
message
stellarstation.proto:416Request for the `ListUpcomingAvailablePasses` method.
string satellite_id = 1
The ID of the satellite to list passes for. The ID of a satellite can be found on the StellarStation Console page for the satellite.
message
stellarstation.proto:423Response for the `ListUpcomingAvailablePasses` method.
repeated pass = 1
The upcoming, schedulable passes for the satellite.
rpc OpenSatelliteStream (stream , stream )
stellarstation.proto:101Open a stream to a satellite. The returned stream is bi-directional - it can be used by the client to send commands to the satellite and data received from the satellite will be returned as it is made available. All telemetry received from the satellite on reserved passes along with associated events from this point on will be returned as soon as this method is called. If `SatelliteStreamRequest.stream_id` is specified, any messages that have been buffered for the stream will be returned as well. If `SatelliteStreamRequest.plan_id` is provided, only messages for the specified plan will be returned. The first `SatelliteStreamRequest` sent on the stream is used for configuring the stream. Unless otherwise specified, all configuration is taken from the first request and configuration values in subsequent requests will be ignored. The stream can be left open for any amount of time and telemetry will be received as available and returned. When the client is done with the stream, it should close it successfully. If the stream is cancelled with an unexpected error at any point, telemetry received before the next call to `OpenSatelliteStream` to resume the stream will be buffered up to 1 minute, and if no call to `OpenSatelliteStream` is made with `stream_id` specified to resume the stream, it will expire in 10 minutes and a call to `OpenSatelliteStream` with that `stream_id` will be closed with a `ABORTED` error. If the satellite is not found or the client is not authorized for it, the stream will be closed with a `NOT_FOUND` error.
message
stellarstation.proto:175Request for the `OpenSatelliteStream` method. Next ID: 12
string satellite_id = 1
The ID of the satellite to open a stream with. The ID of a satellite can be found on the StellarStation Console page for the satellite.
string plan_id = 11
The ID of the plan to open a stream for. If `plan_id` is set, only messages for the provided plan ID will be returned on this stream. A valid `plan_id` can be found in the response for the `ListPlans` method or on the StellarStation Console page for the satellite. Status: ALPHA This API is under development and may not work correctly or be changed in backwards incompatible ways in the future.
string ground_station_id = 12
Optional. The ID of the ground station to open a stream with. `satellite_id` must also be set when specifying `ground_station_id`. Only messages for the provided `ground_station_id` from the provided `satellite_id` will be returned on this stream. Status: ALPHA This API is under development and may not work correctly or be changed in backwards incompatible ways in the future.
string stream_id = 2
The `SatelliteStreamResponse.stream_id` from a previously opened stream to resume. If the specified stream has already expired or been closed, the stream is closed with a `ABORTED` error.
bool enable_events = 5
Whether monitoring events should be returned by the stream in `SatelliteStreamResponse.stream_event`. If set in the first request of the stream, events of type `StreamEvent` will be returned throughout the lifetime of the stream.
string request_id = 6
A unique ID identifying this request. If `enable_events` is true and this is filled, events returned in `SatelliteStreamResponse.stream_event` that correspond to this request will have this value copied into `StreamEvent.request_id` for correlation. The API will treat this as an opaque identifier which can be set to any value, e.g., to the same value as the request ID or command number in a downstream system. For simple cases, it is often simplest to set this to a standard UUID.
oneof Request
A request to send on the satellite stream. Currently only command sending to the satellite is supported. The request does not need to be filled on the first request to `OpenSatelliteStream`.
send_satellite_commands_request = 3
A request to send commands to the satellite.
ground_station_configuration_request = 7
A request to modify a configuration of a ground station. Status: ALPHA This API is under development and may not work correctly or be changed in backwards incompatible ways in the future.
telemetry_received_ack = 9
An ack message to respond to each ReceiveTelemetryResponse when `enable_flow_control` is true. Status: ALPHA This API is under development and may not work correctly or be changed in backwards incompatible ways in the future.
repeated Framing accepted_framing = 4
The `Framing` types to accept, for satellites that have been configured for multiple framings (e.g., IQ + AX25). If empty, all framings produced by the satellite will be returned.
string resume_stream_message_ack_id = 8
Optional. The `ReceiveTelemetryResponse.message_ack_id` of the most recently received telemetry. This may be specified in attempt to resume streaming after a connection or application error. If specified, the server will attempt to resume transfer assuming the provided value is that of the most recent Telemetry received & processed by the client. If not specified (or if provided value is invalid), server will resume streaming from the most recent telemetry message sent by the server which may or may not have been received by the client. This feature is only available if enable_flow_control is true. This feature may not be available for Out-of-order-allowed-satellites. Status: ALPHA This API is under development and may not work correctly or be changed in backwards incompatible ways in the future.
bool enable_flow_control = 10
Whether flow control is enabled on the client side. If set to true, client must respond to each ReceiveTelemetryResponse received with a corresponding ReceiveTelemetryAck message. Status: ALPHA This API is under development and may not work correctly or be changed in backwards incompatible ways in the future.
message
stellarstation.proto:355A response from the `OpenSatelliteStream` method.
string stream_id = 1
The ID of this stream, which can be used in a subsequent call to `OpenSatelliteStream` to resume this stream on interruption (e.g., if a network failure causes the connection to be closed mid-stream). Telemetry received on a previously opened stream with no current listener will be buffered for a maximum of 1 minute, and the stream itself will be cancelled and no more buffering will occur if no client resumes the stream with `OpenSatelliteStream` within 10 minutes.
oneof Response
A response on the stream. Currently the only types of response are telemetry received from the satellite and stream events.
receive_telemetry_response = 2
A response from a satellite containing telemetry.
stream_event = 3
An event that occurred while processing the stream. Often used for monitoring the stream. Never returned if `SatelliteStreamRequest.enable_events` is false in the first `SatelliteStreamRequest` of the stream.
rpc ReservePass (, )
stellarstation.proto:117Reserves a pass for later execution as a plan. The pass must be specified by a `reservation_token` returned in another method like `ListUpcomingAvailablePasses` and its `aos_time` must be at least one hour in the future. If the `reservation_token` is invalid, the request will return an `INVALID_ARGUMENT` error. If the requested pass cannot be scheduled due to a conflict with existing plans or other scheduling constraints, the request will return a `FAILED_PRECONDITION` error. This includes if the pass `aos_time` is less than one hour in the future. Note that the reservation_token may have become unreservable since it was fetched. If that's the case, the call to `ReservePass` will fail with a 'FAILED_PRECONDITION' error and `ListUpcomingAvailablePasses` should be called again to get a fresh list of reservable passes. The pass must be scheduled at least one hour in advance of `aos_time` or it will be rejected.
message
stellarstation.proto:436Request for the `ReservePass` method.
string reservation_token = 1
The token that specifies the pass, as returned in `Pass.reservation_token` or one of the `Pass.channel_set_token.reservation_token` values.
Priority priority = 2
message
stellarstation.proto:445Response for the `ReservePass` method.
optional plan = 1
The reserved plan.
Sets the metadata for a plan. Metadata added to a plan is available via ListPlans RPCs for both satellite and ground station APIs. Because of this, it is important not to store sensitive information that the plan's satellite operator and ground station operator should not have access to. Any metadata set with this method will overwrite existing metadata. Status: ALPHA This API is under development and may not work correctly or be changed in backwards incompatible ways in the future.
message
stellarstation.proto:729Request for the `SetPlanMetadata` method.
string plan_id = 1
The ID of the plan to set the metadata for. Required.
optional metadata = 2
The metadata to set.
message
stellarstation.proto:740Response for the `SetPlanMetadata` method.
Currently no payload in the response.
(message has no fields)
rpc SetTleSource (, )
stellarstation.proto:153Sets the TLE source for a satellite. The selected source will be used for all upcoming pass calculations for the satellite. If TLE does not exist for a specific source, no passes will be generated. An 'INVALID_ARGUMENT' error will be returned in the following condition: - no satellite_id is provided. - the source provided is invalid. If the satellite is not found or the client is not authorized for it, the request will return a `NOT_FOUND` error.
message
stellarstation.proto:689Request for the `SetTleSource` method.
string satellite_id = 1
The ID of the satellite to set the TLE for. Required.
SetTleSourceRequest.Source source = 2
The source of the TLE the satellite will use for pass calculations. Required.
message
stellarstation.proto:714Response for the `SetTleSource` method.
Currently no payload in the response.
(message has no fields)
message
stellarstation.proto:480A channel set defines one or both of the uplink and downlink `RadioDeviceConfiguration`s to be used when executing a pass. A channel set is unique to a specific satellite, and a satellite may have one or more channel sets. A common example is to have a channel set for TT&C with both uplink and downlink configurations, and a second channel set only for mission downlink. In this case it is necessary to select the configuration that will be used during plan execution.
Used in: , ,
string id = 1
The unique ID of the channel set.
string name = 2
The name used to identify the channel set (for example, TT&C UHF).
optional uplink = 3
The radio device configuration used for uplinking. Optional if downlink is set.
optional downlink = 4
The radio device configuration used for downlinking. Optional if uplink is set.
A type of framing of a binary payload used in satellite communication.
Used in: ,
BITSTREAM = 0
No framing done in the API. All payloads are assumed to be pre-framed and ready for transmission to the satellite or API client with no additional processing.
AX25 = 1
AX.25 (Amateur X.25) framing - https://en.wikipedia.org/wiki/AX.25
IQ = 2
No framing or demodulation done in the API. Raw IQ data is sent to the API client with no additional processing.
IMAGE_PNG = 3
A decoded PNG image frame.
IMAGE_JPEG = 4
A decoded JPEG image.
FREE_TEXT_UTF8 = 5
Completely arbitrary, freeform text contained in a frame.
WATERFALL = 6
A waterfall diagram. This is actually for the whole plan and does not correspond to an individual frame.
message
stellarstation.proto:288A request to modify configuration of ground station hardware. Next ID: 3 Status: ALPHA This API is under development and may not work correctly or be changed in backwards incompatible ways in the future.
Used in: ,
optional transmitter_configuration_request = 1
A request to modify transmitter configuration at a ground station.
optional receiver_configuration_request = 2
A request to modify receiver configuration at a ground station.
message
stellarstation.proto:501A pass during which a satellite can be communicated with from a given ground station. Next ID: 14
Used in:
optional aos_time = 2
The time of Acquisition of Signal (AOS) between the ground station and satellite in this pass.
optional los_time = 3
The time of Loss of Signal (LOS) between the ground station and satellite in this pass.
double ground_station_latitude = 4
The latitude, in degrees, of the ground station's location.
double ground_station_longitude = 5
The longitude, in degrees, of the ground station's location.
string ground_station_organization_name = 12
The organization name of the ground station.
string ground_station_id = 13
The ID of the ground station.
string ground_station_country_code = 6
The ISO 3166-1 alpha-2 2-letter country code for the ground station's location. See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
double max_elevation_degrees = 7
The max elevation during the pass, in degrees.
optional max_elevation_time = 8
The time of the max elevation during the pass.
repeated channel_set_token = 11
List of channel set and corresponding reservation token groupings. Only channel sets that are compatible with this pass's ground station will be present.
message
stellarstation.proto:531A mapping of channel set to its unique reservation token.
Used in:
optional channel_set = 1
A channel set that can be reserved.
string reservation_token = 2
A unique token for this pass, specific to this channel set, that can be used for scheduling it by copying to ReservePassRequest.reservation_token.
double unit_price = 3
The price per minute (USD) for this pass and channel set combination.
message
stellarstation.proto:572A plan, specifying a time range within which a satellite will be communicated with. Next ID: 22
Used in: ,
string id = 1
The unique ID of the plan.
string satellite_id = 2
The id of the satellite to be tracked in the plan.
string satellite_organization_name = 17
The organization name of the satellite to be tracked in the plan.
Plan.Status status = 3
The status of this plan.
optional start_time = 14
The start of the time window reserved for the plan. This value does not change over time.
optional end_time = 15
The end of the time window reserved for the plan. This value does not change over time.
optional aos_time = 4
The time of Acquisition of Signal (AOS) between the ground station and satellite in this plan. This value is never before 'start_time'. It may change over time (for example, if updated TLE becomes available).
optional los_time = 5
The time of Loss of Signal (LOS) between the ground station and satellite in this plan. This value is never after 'end_time'. It may change over time (for example, if updated TLE becomes available).
double ground_station_latitude = 6
The latitude, in degrees, of the ground station's location.
double ground_station_longitude = 7
The longitude, in degrees, of the ground station's location.
string ground_station_country_code = 8
The ISO 3166-1 alpha-2 2-letter country code for the ground station's location. See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
string ground_station_organization_name = 18
The organization name of the ground station.
string ground_station_id = 20
The ID of the ground station.
double max_elevation_degrees = 9
The max elevation during the plan, in degrees.
optional max_elevation_time = 10
The time of the max elevation during the plan.
repeated telemetry_metadata = 13
Metadata for telemetry received during the pass. Only populated when the pass has completed successfully and data processing is complete.
optional channel_set = 16
The channel set used to reserve this plan.
double unit_price = 19
The price per minute (USD) for this plan set by the ground station owner at the time of reservation.
Priority priority = 21
The priority of the plan.
A description of the status of a plan.
Used in:
RESERVED = 0
The plan is reserved for execution in the future at `aos_time`.
EXECUTING = 1
The plan is currently executing and will end in the future at `los_time`.
SUCCEEDED = 2
The plan already finished executing successfully.
FAILED = 3
The plan failed to execute correctly.
CANCELED = 4
The plan was canceled. This can be explicitly by calling `CancelPlan` or implicit due to cancellation by the ground station in the plan (e.g., due to bad weather).
PROCESSING = 5
The plan completed execution and telemetry data is being processed.
message
stellarstation.proto:720Message to be nested inside of a SetPlanMetadataRequest message in order to get around the limitation of protobuf maps not allowing repeated values.
Used in:
map<string, > metadata = 2
message
stellarstation.proto:721Used in:
repeated string data = 1
message
transport.proto:120A monitoring event that occurred during the execution of the plan. Information about the current configuration of the ground station and state of components is returned to provide information that can help to troubleshoot issues with the plan.
Used in:
string plan_id = 1
The ID of the plan being monitored.
string channel_set_id = 5
Channel set ID
oneof Info
ground_station_configuration = 2
Information about the current configuration of the ground station when beginning to execute a plan. This will only be returned once at the beginning of execution. Information that is provided by the ground station executing the plan will be returned - any fields that are not supported by the ground station will be left unfilled.
ground_station_state = 3
Information about the current state of the ground station while executing a plan. This will be returned periodically during execution of the plan. Information that is provided by the ground station executing the plan will be returned - any fields that are not supported by the ground station will be left unfilled.
ground_station_event = 4
Information about events generated by the ground station while executing a plan.
The priority level of a plan.
Used in: ,
LOW = 0
MEDIUM = 1
HIGH = 2
message
stellarstation.proto:300An ack message for client to notify server of sucessful receive of a ReceiveTelemetryResponse message. Status: ALPHA This API is under development and may not work correctly or be changed in backwards incompatible ways in the future.
Used in:
string message_ack_id = 1
The `ReceiveTelemetryResponse.message_ack_id` value of the telemetry message received
optional received_timestamp = 2
Optional. The local timestamp of message reception, used for statistics collection.
message
stellarstation.proto:378A response from a satellite containing telemetry.
Used in:
repeated telemetry = 1
The telemetry received.
string plan_id = 2
The ID of the plan the telemetry was received for.
string satellite_id = 4
The ID of the satellite.
string ground_station_id = 5
The ID of the ground station.
string message_ack_id = 3
The ID to be used to when creating a `ReceiveTelemetryAck.message_ack_id` response This value may not be available for Out-of-order-allowed-satellites Status: ALPHA This API is under development and may not work correctly or be changed in backwards incompatible ways in the future.
message
stellarstation.proto:345A request to configure a receiver at a ground station. Default state of these parameters depends on hardware configuration at each ground station. Please check ReceiverConfiguration and ReceiverState in monitoring message. Not all configuration requests are supported by some receivers. If a field isn't set, the configuration will not be changed. Next ID: 3
Used in:
optional bitrate = 1
Bitrate of the receiver.
radio.Modulation modulation = 2
Modulation of the receiver. Note that the default modulation is DISABLED and will be ignored. There is no way to disable modulation using this method.
message
stellarstation.proto:263A request to send commands to a satellite. Next ID: 4
Used in:
repeated bytes command = 2
The command frames to send to the satellite. All commands will be transmitted in sequence immediately, during which time telemetry will not be received. After all commands have been transmitted, telemetry receive will be immediately re-enabled. The maximum size of each command is 2MB. If a command larger than 2MB is received, the stream will be closed with a `RESOURCE_EXHAUSTED` error.
string channel_set_id = 3
The ID of the channel set to be used when sending the command. Required if two uplink-capable plans are simultaneously executing. If not provided and only one plan is executing, the channel set will be automatically determined. If a channel set without an uplink component is provided or two uplink-capable plans are simultaneously executing and no ID is provided, the command will be ignored. Status: ALPHA This API is under development and may not work correctly or be changed in backwards incompatible ways in the future.
The source of the TLE.
Used in:
UNKNOWN = 0
This is not allowed and will cause an error.
NORAD = 1
Provided by NORAD.
MANUAL = 2
Manually provided by the owner of the satellite.
message
transport.proto:91An event that occurred while processing the stream. A `StreamEvent` will have one of several types of event payloads corresponding to event types. Many of these payloads will be empty, depending on the context of an event, but are still returned as messages to allow future extension.
Used in: ,
string request_id = 1
The ID of the request this event corresponds to, copied from `SatelliteStreamRequest.request_id` when present. If the event doesn't correspond to a request, this is always empty.
optional timestamp = 4
Timestamp of the event occurrence
oneof Event
A stream event payload.
command_sent = 2
An event indicating the commands in the request were sent by the ground station through its radio.
plan_monitoring_event = 3
An event with monitoring information for a particular executed plan.
message
transport.proto:102An event indicating the commands in the request were sent by the ground station through its radio.
Empty, may be extended in the future.
Used in:
(message has no fields)
message
transport.proto:61A chunk or frame of telemetry data that has been received from a satellite.
Used in: ,
Framing framing = 1
The framing of this telemetry data.
bytes data = 2
The payload of this telemetry.
uint64 downlink_frequency_hz = 3
The actual downlink frequency, in Hz, used when receiving `data`, including adjustments for doppler shift.
optional time_first_byte_received = 4
Timestamp when the first byte of `data` was received.
optional time_last_byte_received = 5
Timestamp when the last byte of `data` was received.
bytes frame_header = 6
The binary header of the telemetry frame available for certain framing types. * AX25 - This is either Address + Control, or Address + Control + PID. The checksum is not returned. * BITSTREAM - Streams for certain protocols such as CCSDS may contain frame headers according to the applicable standards.
message
stellarstation.proto:549Metadata for telemetry downlinked during a pass.
Used in:
string url = 1
URL of the data. This URL is valid for one hour after being returned.
TelemetryMetadata.DataType data_type = 2
The type of data received during downlinking.
The type of data available at the above URL.
Used in:
RAW = 0
Raw IQ data.
DEMODULATED = 1
Demodulated IQ data.
DECODED = 2
Decoded data.
message
stellarstation.proto:316A request to configure a transmitter at a ground station. Default state of these parameters depends on hardware configuration at each ground station. Please check TransmitterConfiguration and TransmitterState in monitoring message. Not all configuration requests are supported by some transmitters. If a field isn't set, the configuration will not be changed. Next ID: 7
Used in:
optional enable_carrier = 1
Enable carrier transmission.
optional enable_if_modulation = 2
Enable IF modulation.
optional enable_idle_pattern = 3
Enable idle pattern transmission.
optional enable_if_sweep = 4
Enable IF sweep.
optional bitrate = 5
Bitrate of the transmitter
radio.Modulation modulation = 6
Modulation of the transmitter. Note that the default modulation is DISABLED and will be ignored. There is no way to disable modulation using this method.