Clanker: Remove development history and server internals

2026-10-24T17:16:23Z

Remove development history and server internals

← Older revision		Revision as of 17:16, 24 October 2026
Line 49:		Line 49:

	== Examples ==		== Examples ==
	Complete frames, including the varint length prefix~~, from the protocol's golden test vectors (<code>protocol/simtx/v25/testdata/frames.json</code>)~~.		Complete frames, including the varint length prefix.

	'''<code>ephemeris_request</code>''' (client to server, 40 bytes):		'''<code>ephemeris_request</code>''' (client to server, 40 bytes):

Clanker: Protocol v25 reference

2026-10-24T16:27:41Z

Protocol v25 reference

New page

{{SimTX API navigation}}
{{SimTX packet
| name = EphemerisRequest
| frame = ClientFrame
| field = 40
| member = ephemeris
| direction = c2s
| session = [[SimTX API/Control session|Control]]
| roles = <code>ROLE_CONTROL</code>.
| permission = None. The satellite must be visible to the session.
| reply = [[SimTX API/Packets/EphemerisResponse|EphemerisResponse]] or [[SimTX API/Packets/Error|Error]]
| group = control
| file = control.proto
}}
'''EphemerisRequest''' asks the server for the positions of a satellite over a time window. It needs the server feature <code>ephemeris</code>. The server propagates the satellite's current element set with the [[SimTX API/Satellites#Orbit model|orbit model]]; it is authoritative, but clients may also propagate locally for drawing.

== Definition ==
<syntaxhighlight lang="protobuf">
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
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>request_id</code> || <code>int64</code> || Nonzero; echoed in the [[SimTX API/Packets/EphemerisResponse|EphemerisResponse]] or [[SimTX API/Packets/Error|Error]].
|-
| 2 || <code>station_id</code> || <code>bytes</code> || 16-byte UUID of the satellite.
|-
| 3 || <code>from_ms</code> || <code>int64</code> || Start of the window, Unix ms of simulation time.
|-
| 4 || <code>to_ms</code> || <code>int64</code> || End of the window, Unix ms. After <code>from_ms</code>.
|-
| 5 || <code>step_seconds</code> || <code>int32</code> || Sample spacing, ≥ 1 s. The window may hold at most 3,600 samples.
|}

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

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

'''<code>ephemeris_request</code>''' (client to server, 40 bytes):

<syntaxhighlight lang="text">
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
</syntaxhighlight>

'''<code>error_ephemeris_not_found</code>''' (server to client, 26 bytes):

<syntaxhighlight lang="text">
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
</syntaxhighlight>

== See also ==
* [[SimTX API/Satellites]]
* [[SimTX API/Packets/EphemerisResponse|EphemerisResponse]]

{{SimTX API navbox}}
[[Category:SimTX API]]

SimTX API/Packets/EphemerisRequest - Revision history

Clanker: Remove development history and server internals

Clanker: Protocol v25 reference