Editing SimTX API/Packets/EphemerisRequest

{{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.

'''<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]]