Editing SimTX API/Packets/PassPredictionRequest

{{SimTX API navigation}}
{{SimTX packet
| name = PassPredictionRequest
| frame = ClientFrame
| field = 41
| member = passes
| direction = c2s
| session = [[SimTX API/Control session|Control]]
| roles = <code>ROLE_CONTROL</code>.
| permission = None. The satellite and an observer station must be visible to the session.
| reply = [[SimTX API/Packets/PassPredictionResponse|PassPredictionResponse]] or [[SimTX API/Packets/Error|Error]]
| group = control
| file = control.proto
}}
'''PassPredictionRequest''' asks the server when a satellite will be above an observer's horizon within a time window. It needs the server feature <code>passes</code>. The observer is one of your ground stations (or a PUBLIC one) or an arbitrary position.

== Definition ==
<syntaxhighlight lang="protobuf">
message PassPredictionRequest {
  int64 request_id = 1;
  bytes satellite_id = 2;
  oneof observer_site {
    bytes observer_station_id = 3;
    GeoPoint observer = 4;
  }
  int64 from_ms = 5;
  int64 to_ms = 6;             // at most 7 days after from_ms
  double min_elevation_deg = 7;
  double frequency_hz = 8;     // for max Doppler; 0 = skip
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>request_id</code> || <code>int64</code> || Nonzero; echoed in the [[SimTX API/Packets/PassPredictionResponse|PassPredictionResponse]] or [[SimTX API/Packets/Error|Error]].
|-
| 2 || <code>satellite_id</code> || <code>bytes</code> || 16-byte UUID of the satellite.
|-
| 3 || <code>observer_station_id</code> || <code>bytes</code> || Member of <code>oneof observer_site</code>. A ground station to observe from.
|-
| 4 || <code>observer</code> || [[SimTX API/Data types#GeoPoint|GeoPoint]] || Member of <code>oneof observer_site</code>. An arbitrary observer position.
|-
| 5 || <code>from_ms</code> || <code>int64</code> || Start of the window, Unix ms of simulation time.
|-
| 6 || <code>to_ms</code> || <code>int64</code> || End of the window, Unix ms. At most 7 days after <code>from_ms</code>.
|-
| 7 || <code>min_elevation_deg</code> || <code>double</code> || Elevation threshold for acquisition and loss of signal, degrees.
|-
| 8 || <code>frequency_hz</code> || <code>double</code> || Carrier frequency for <code>max_doppler_hz</code>, Hz. 0 skips the Doppler computation.
|}

== Behaviour ==
* Exactly one of <code>observer_station_id</code> and <code>observer</code>. An observer station must be a ground station that currently has a live session on that server and is PUBLIC or your own; otherwise the request is answered with [[SimTX API/Packets/Error|Error]] <code>NOT_FOUND</code> (<i>Unknown observer station on this server; send the observer location instead</i>).
* The window may be at most 7 days long, between the years 1970 and 2200.
* Elevations are geometric (no refraction), on the 6,371 km sphere. See [[SimTX API/Satellites#Passes|Passes]] for the algorithm.
* Passes that overlap the window are clipped to it, and to a deorbiting satellite's reentry. An always-visible geostationary satellite gives one window-long pass; a never-visible one gives none.
* Satellite failures are answered with [[SimTX API/Packets/Error|Error]] as for [[SimTX API/Packets/EphemerisRequest|EphemerisRequest]].
* Heavy request.

== Examples ==
Complete frames, including the varint length prefix.

'''<code>pass_request_station_observer</code>''' (client to server, 74 bytes):

<syntaxhighlight lang="text">
49                            frame length 73
CA 02 46                      passes (PassPredictionRequest), 70 bytes
  08 16                       request_id = 22
  12 10 99 99 99 99 …         satellite_id = 99999999-8888-4777-8666-555555555555
  1A 10 11 11 11 11 …         observer_station_id = 11111111-2222-4333-8444-555555555555
  28 80 94 83 B9 97 34        from_ms = 1793000000000
  30 80 CC 9C E2 97 34        to_ms = 1793086400000
  39 00 00 00 00 00 00 24 40  min_elevation_deg = 10.0
  41 00 00 00 60 19 EF B9 41  frequency_hz = 435100000.0
</syntaxhighlight>

'''<code>pass_request_point_observer</code>''' (client to server, 67 bytes):

<syntaxhighlight lang="text">
42                              frame length 66
CA 02 3F                        passes (PassPredictionRequest), 63 bytes
  08 17                         request_id = 23
  12 10 99 99 99 99 …           satellite_id = 99999999-8888-4777-8666-555555555555
  22 1B                         observer (GeoPoint), 27 bytes
    09 00 00 00 00 00 C0 47 40  latitude_deg = 47.5
    11 00 00 00 00 00 00 33 40  longitude_deg = 19.0
    19 00 00 00 00 00 00 5E 40  altitude_meters = 120.0
  28 80 94 83 B9 97 34          from_ms = 1793000000000
  30 80 CC 9C E2 97 34          to_ms = 1793086400000
</syntaxhighlight>

== See also ==
* [[SimTX API/Satellites#Passes|Passes]]
* [[SimTX API/Packets/PassPredictionResponse|PassPredictionResponse]]

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