package stellarstation.api.v1.groundstation
Get desktop application:
View/edit binary Protocol Buffers messages
The public API of StellarStation for use by ground station operators integrating with the StellarStation ground network. It is invalid to specify ground station IDs that the operator does not own. 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 CancelPlan (, )
groundstation.proto:67Cancel 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 for the pass to be reserved again. 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
groundstation.proto:122Request for the `CancelPlan` method.
string plan_id = 1
The id of the plan to cancel, i.e., the value of `Plan.id`.
message
groundstation.proto:128Response for the `CancelPlan` method.
Currently no payload in the response.
(message has no fields)
For internal use only - retrieve current plan
message
groundstation.proto:406Currently no payload in the request.
(message has no fields)
message
groundstation.proto:410optional plan = 1
rpc ListPlans (, )
groundstation.proto:80Lists the plans for a particular ground station. The request will be closed with an `INVALID_ARGUMENT` status if `ground_station_id`, `aos_after`, or `aos_before` are missing, or the duration between the two times is longer than 31 days.
message
groundstation.proto:133Request for the `ListPlans` method.
string ground_station_id = 1
The ID of the ground station to list plans for. The ID can be found on the StellarStation Console page for the ground station.
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
groundstation.proto:150A response from the `ListPlans` method.
repeated plan = 1
The requested list of plans for the ground station.
rpc OpenGroundStationStream (stream , stream )
groundstation.proto:111Open a stream from a ground station. The returned stream is bi-directional - it is used by the ground station to send telemetry received from a satellite and receive commands to send to the satellite. The ground station must keep this stream open while it is connected to the StellarStation network for use in executing plans - if the stream is cut, it must be reconnected with exponential backoff. The first `GroundStationStreamRequest` 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. There is no restriction on the number of active streams from a ground station (i.e., streams opened with the same `ground_station_id`). Most ground stations will issue a single stream to receive commands and send telemetry, but in certain cases, such as if uplink and downlink are handled by different computers, it can be appropriate to have multiple processes with their own stream. If opening multiple streams for a single ground station, it is the client's responsibility to handle the streams appropriately, for example by ensuring only one stream sends commands so they are not duplicated. If the ground station is not found or the API client is not authorized for it, the stream will be closed with a `NOT_FOUND` error. Status: ALPHA This API is under development and may not work correctly or be changed in backwards incompatible ways in the future.
message
groundstation.proto:327A request for the `OpenGroundStationStream` method.
string ground_station_id = 1
The ID of the ground station that is opening a stream. The ID of a ground station can be found on the StellarStation Console page for the ground station.
string stream_tag = 2
A tag to identify this stream. This tag is not used semantically and is only for logging, monitoring, and debugging. This does not need to be set if there will only ever be one stream for a particular `ground_station_id` open at a time. If multiple streams will be open, this should be set to identify the stream. Some examples include 'uplink', 'downlink', 'uhf', 's-band'.
oneof Request
A payload to send on the ground station stream. The payload does not need to be filled on the first request to `OpenGroundStationStream`.
satellite_telemetry = 3
stream_event = 4
An event that occurred while processing the stream. Satellite operators will often use these events for debugging and monitoring. - `command_sent` must be returned right after completing transmission of commands received in a `SendSatelliteCommandsResponse`. - `plan_monitoring_event.ground_station_configuration` must be returned once at the beginning of the execution of a plan and contains information about the actual configuration of the ground station at the time. - `plan_monitoring_event.ground_station_state` must be sent regularly throughout the plan and contains real-time monitoring of the hardware of the ground station. - `plan_monitoring_event.ground_station_event` must be sent once at each of the transitions documented in `PlanLifecycleEvent` when executing a plan.
message
groundstation.proto:374A response for the `OpenGroundStationStream` method. The ground station must process a response immediately when received on the stream.
string plan_id = 1
The ID of the plan this response corresponds to. Unfilled if this response does not correspond to a plan.
string response_id = 2
A unique ID identifying this response. If filled, any `StreamEvent` generated when handling this GroundStationStreamResponse` must have this value copied into `StreamEvent.request_id`. Currently, this includes - Returning `CommandSentFromGroundStation` after completing transmission of the commands in a `SendSatelliteCommandsResponse`.
oneof Response
A payload sent on the stream to be processed by the ground station. Currently only commands to send to a satellite will be returned to the ground station.
satellite_commands = 3
Commands to send to the satellite.
ground_station_configuration_request = 4
Request to configure ground station devices.
message
groundstation.proto:159A scheduled pass. The plan will be executed on its ground station to communicate with its satellite during a time range between AOS and LOS, unless explicitly cancelled. Next ID: 16
Used in: ,
string plan_id = 1
The ID of this plan.
optional tle = 2
The TLE for the satellite in this plan.
optional start_time = 7
The start of the time window reserved for the plan. This timestamp does not change over time, and is set to allow sufficient time at the start of a plan to allow the ground station to prepare for plan execution.
optional end_time = 8
The end of the time window reserved for the plan. This timestamp does not change over time, and is set to allow sufficient time at the end of a plan to allow the ground station to perform cleanup tasks after executing the plan.
optional aos_time = 3
The time of AOS between the ground station and satellite in this plan. This timestamp will never be before 'start_time'. If may change over time (for example, if updated TLE becomes available).
optional los_time = 4
The time of LOS between the ground station and satellite in this plan. This timestamp will never be after 'end_time'. If may change over time (for example, if updated TLE becomes available).
optional downlink_radio_device = 5
Configuration of the radio device used for downlinking from the satellite. Ground stations will need to configure reception during the plan to match this device. Deprecated. Use channel_set.downlink.
optional uplink_radio_device = 6
Configuration of the radio device used for uplinking to the satellite. Ground stations will need to configure transmission during the plan to match this device. Deprecated. Use channel_set.uplink.
repeated satellite_coordinates = 9
Predicted coordinates of the tracked satellite for every second between AOS and LOS. This information is intended for calculating device states such as rotator angles and radio frequencies. This field is only populated for future plans.
string satellite_organization_name = 10
The organization name of the satellite to be tracked in the plan.
string ground_station_organization_name = 11
The organization name of the ground station.
string ground_station_id = 13
The ID of the ground station.
double unit_price = 12
The price per minute (USD) for this plan set by the ground station owner at the time of reservation.
string satellite_id = 14
The id of the satellite to be tracked in the plan.
optional channel_set = 15
The channel set used to reserve this plan.
optional metadata = 16
The metadata of the plan.
message
groundstation.proto:231Used in:
map<string, > metadata = 2
message
groundstation.proto:232Used in:
repeated string data = 1
message
groundstation.proto:399Command to transmit to the satellite.
Used in:
repeated bytes command = 1
The command frames to send to the satellite. All commands must be transmitted in sequence immediately. After all commands have been transmitted, telemetry receive must be immediately enabled again.
message
groundstation.proto:249Coordinates of a satellite observed from a ground station tracking it.
Used in:
optional time = 1
The time which the coordinates are for.
optional angle = 2
The angle of the satellite.
double range_rate = 3
The range rate (change rate of distance) of the satellite. You can use this value to calculate Doppler shifted communication frequencies using the following formulae. uplink: shifted_freq = original_freq * (1.0 + range_rate / speed_of_light) downlink: shifted_freq = original_freq * (1.0 - range_rate / speed_of_light) where speed_of_light is 299792458.0 m/s.
message
groundstation.proto:361Telemetry received from a satellite to send to a satellite operator.
Used in:
string plan_id = 1
The ID of the plan the telemetry is being sent for.
string channel_set_id = 3
Channel set ID
optional telemetry = 2
The telemetry being sent.
message
groundstation.proto:240Unparsed TLE data for a satellite - https://en.wikipedia.org/wiki/Two-line_element_set
Used in:
string line_1 = 1
The first line of the TLE. Not a title line.
string line_2 = 2
The second line of the TLE.
A time window during which a ground station is unavailable e.g. for local maintenance.
Used in:
string window_id = 1
The ID of the unavailability window.
optional start_time = 2
Start time of the unavailabilty window.
optional end_time = 3
End time of the unavailability window.