SimTX API/Packets/EphemerisRequest

EphemerisRequest

Frame	ClientFrame, field 40
Member	ephemeris
Direction	Client → server
Session	Control
Roles	ROLE_CONTROL.
Permission	None. The satellite must be visible to the session.
Answered by	EphemerisResponse or Error
Answers
Defined in	control.proto

EphemerisRequest asks the server for the positions of a satellite over a time window. It needs the server feature ephemeris. The server propagates the satellite's current element set with the orbit model; it is authoritative, but clients may also propagate locally for drawing.

Definition

message EphemerisRequest {
  int64 request_id = 1;
  bytes station_id = 2;
  int64 from_ms = 3;
  int64 to_ms = 4;
  int32 step_seconds = 5;      // >= 1; at most 3600 samples
}

Fields

#	Field	Type	Description
1	request_id	int64	Nonzero; echoed in the EphemerisResponse or Error.
2	station_id	bytes	16-byte UUID of the satellite.
3	from_ms	int64	Start of the window, Unix ms of simulation time.
4	to_ms	int64	End of the window, Unix ms. After from_ms.
5	step_seconds	int32	Sample spacing, ≥ 1 s. The window may hold at most 3,600 samples.

Behaviour

• At most 3,600 samples: (to_ms − from_ms) / step_seconds must not exceed that.
• Use the server's simulation clock (ServerHello.simulation_time_ms, or a recent StationList.captured_at_ms) as "now".
• The satellite must be PUBLIC or your own. Failures are answered with Error: NOT_FOUND (Unknown satellite) for an unknown or invisible satellite, INVALID_REQUEST for a window that ends before it starts, a step below 1 s or more than 3,600 samples, STATION_INACTIVE when the satellite has already reentered, and UNAVAILABLE when orbit computations are busy.
• For a deorbiting satellite, samples stop just before deorbit.reentry_at_ms.
• Heavy request.

Examples

Complete frames, including the varint length prefix, from the protocol's golden test vectors (protocol/simtx/v25/testdata/frames.json).

ephemeris_request (client to server, 40 bytes):

27                      frame length 39
C2 02 24                ephemeris (EphemerisRequest), 36 bytes
  08 15                 request_id = 21
  12 10 99 99 99 99 …   station_id = 99999999-8888-4777-8666-555555555555
  18 80 94 83 B9 97 34  from_ms = 1793000000000
  20 E0 E8 86 B9 97 34  to_ms = 1793000060000
  28 1E                 step_seconds = 30

error_ephemeris_not_found (server to client, 26 bytes):

19                                 frame length 25
1A 17                              error (Error), 23 bytes
  08 04                            code = 4 (ERROR_CODE_NOT_FOUND)
  12 11 55 6E 6B 6E 6F 77 6E 20 …  message = "Unknown satellite"
  18 15                            request_id = 21

See also

• SimTX API/Satellites
• EphemerisResponse