Editing SimTX API/Packets/StationList

{{SimTX API navigation}}
{{SimTX packet
| name = StationList
| frame = ServerFrame
| field = 30
| member = station_list
| direction = s2c
| session = [[SimTX API/Control session|Control]], [[SimTX API/Moderation session|moderation]]
| roles = <code>ROLE_CONTROL</code>, <code>ROLE_MODERATION</code>.
| permission = None
| answers = [[SimTX API/Packets/ListStations|ListStations]]
| group = control
| file = control.proto
}}
'''StationList''' lists the stations on the server: every persistent station with live sessions, every visible satellite (with or without sessions), and every ad-hoc session. Each live receiver or transmitter appears as a [[#LiveSession|LiveSession]] under its station.

== Definition ==
<syntaxhighlight lang="protobuf">
message StationList {
  int64 request_id = 1;
  int64 captured_at_ms = 2;
  repeated Station stations = 3;
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>request_id</code> || <code>int64</code> || The [[SimTX API/Packets/ListStations|ListStations]] <code>request_id</code>.
|-
| 2 || <code>captured_at_ms</code> || <code>int64</code> || Simulation time of the snapshot, Unix ms.
|-
| 3 || <code>stations</code> || <code>repeated</code> [[#Station|Station]] || Persistent stations with live sessions, every visible satellite, and ad-hoc sessions.
|}

=== Station ===
<syntaxhighlight lang="protobuf">
message Station {
  StationCore core = 1;
  repeated LiveSession sessions = 2;
}
</syntaxhighlight>
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>core</code> || [[SimTX API/Data types#StationCore|StationCore]] || The station. For ad-hoc entries <code>kind</code> is <code>ADHOC</code> and <code>station_id</code> is empty. For satellites <code>location</code> is the sub-satellite point at <code>captured_at_ms</code>.
|-
| 2 || <code>sessions</code> || <code>repeated</code> [[#LiveSession|LiveSession]] || Live sessions attached to the station. Exactly one for ad-hoc entries; may be empty for satellites.
|}

=== LiveSession ===
<syntaxhighlight lang="protobuf">
message LiveSession {
  bytes session_id = 1;
  SessionRole role = 2;
  bytes antenna_id = 3;
  string callsign = 4;
  double frequency_hz = 5;
  string modulation = 6;       // string enum (common.proto); empty for receivers
  float power_watts = 7;
  float bandwidth_hz = 8;
  string address = 9;          // moderation sessions only
  GeoPoint location = 10;      // where the session's antenna is right now
}
</syntaxhighlight>
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>session_id</code> || <code>bytes</code> || 16-byte session id, as in the session's [[SimTX API/Packets/SessionStatus|SessionStatus]].
|-
| 2 || <code>role</code> || [[SimTX API/Data types#SessionRole|SessionRole]] || <code>SESSION_ROLE_TX</code> or <code>SESSION_ROLE_RX</code>.
|-
| 3 || <code>antenna_id</code> || <code>bytes</code> || 16-byte UUID of the station antenna in use. Empty for ad-hoc sessions.
|-
| 4 || <code>callsign</code> || <code>string</code> || Callsign of the session.
|-
| 5 || <code>frequency_hz</code> || <code>double</code> || Transmitter: carrier frequency. Receiver: centre frequency.
|-
| 6 || <code>modulation</code> || <code>string</code> || Transmitter: [[SimTX API/Data types#Modulation|Modulation]] name. Empty for receivers.
|-
| 7 || <code>power_watts</code> || <code>float</code> || Transmitter: requested power. Receiver: 0.
|-
| 8 || <code>bandwidth_hz</code> || <code>float</code> || Transmitter: occupied bandwidth as measured by the server. Receiver: filter bandwidth.
|-
| 9 || <code>address</code> || <code>string</code> || Client address. Moderation sessions only; empty on control sessions.
|-
| 10 || <code>location</code> || [[SimTX API/Data types#GeoPoint|GeoPoint]] || Where the session's antenna is now. For a satellite, the sub-satellite point, which moves.
|}

== Contents ==
* '''Persistent stations''' appear with their live sessions. <code>core</code> carries the station's id, revision, kind, name, callsign, owner, visibility and placement.
* '''Satellites:''' every ACTIVE or DEORBITING PUBLIC satellite is listed even with nobody attached. <code>core.location</code> is the sub-satellite point at <code>captured_at_ms</code>; <code>core.orbit</code> and <code>core.attitude</code> let a client propagate it. A satellite with <code>core.deorbit</code> set disappears at <code>reentry_at_ms</code>.
* '''Ad-hoc sessions''' appear as entries with <code>kind = STATION_KIND_ADHOC</code>, an empty <code>station_id</code> and exactly one session.
* '''UNLISTED stations''' of other accounts appear only as ad-hoc-style entries with the callsign; their id and placement are hidden.

== Usage ==
* The list is a snapshot. Poll [[SimTX API/Packets/ListStations|ListStations]] to follow changes, every few seconds at most.
* Do not rely on the order of the entries.
* Use <code>LiveSession.location</code> for map markers. For a satellite it is the satellite's position, and it moves.
* A session's id changes every time it reconnects. Callsigns are not unique.
* Client addresses are filled in only on moderation sessions.

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

'''<code>station_list</code>''' (server to client, 560 bytes):

<syntaxhighlight lang="text">
AE 04 F2 01 AA 04 08 05 10 E8 9B 83 B9 97 34 1A
90 02 0A 50 0A 10 11 11 11 11 22 22 43 33 84 44
55 55 55 55 55 55 10 04 18 01 22 08 42 75 64 61
70 65 73 74 2A 05 48 41 35 47 53 32 08 6F 70 65
72 61 74 6F 72 38 01 42 1B 09 00 00 00 00 00 C0
47 40 11 00 00 00 00 00 00 33 40 19 00 00 00 00
00 00 5E 40 12 62 0A 10 AA AA AA AA BB BB 4C CC
8D DD EE EE EE EE EE EE 10 01 1A 10 11 11 11 11
22 22 43 33 84 44 66 66 66 66 66 66 22 05 48 41
35 47 53 29 00 00 00 00 12 D8 6A 41 32 03 55 53
42 3D 00 00 48 42 45 00 C0 28 45 52 1B 09 00 00
00 00 00 C0 47 40 11 00 00 00 00 00 00 33 40 19
00 00 00 00 00 00 5E 40 12 58 0A 10 AA AA AA AA
BB BB 4C CC 8D DD FF FF FF FF FF FF 10 02 1A 10
11 11 11 11 22 22 43 33 84 44 66 66 66 66 66 66
22 05 48 41 35 47 53 29 00 00 00 00 34 FC 5A 41
45 00 80 3B 46 52 1B 09 00 00 00 00 00 C0 47 40
11 00 00 00 00 00 00 33 40 19 00 00 00 00 00 00
5E 40 1A A2 01 0A 9F 01 0A 10 99 99 99 99 88 88
47 77 86 66 55 55 55 55 55 55 10 03 18 02 22 08
53 69 6D 53 61 74 2D 31 2A 05 53 53 41 54 31 32
08 6F 70 65 72 61 74 6F 72 38 01 42 1B 09 00 00
00 00 00 00 24 40 11 00 00 00 00 00 00 34 40 19
00 00 00 00 E0 C8 20 41 4A 49 0A 0B 73 69 6D 74
78 2D 6A 32 2D 76 31 10 C0 BB F2 D6 06 21 00 00
00 00 00 09 BB 40 29 FC A9 F1 D2 4D 62 50 3F 31
66 66 66 66 66 66 58 40 39 00 00 00 00 00 00 5E
40 41 00 00 00 00 00 80 56 40 49 00 00 00 00 00
00 24 40 52 02 0A 00 1A 67 0A 1C 2A 06 4E 30 43
41 4C 4C 42 12 09 33 33 33 33 33 F3 40 C0 11 66
66 66 66 66 E6 62 40 12 47 0A 10 12 34 56 78 9A
BC 4D EF 81 23 45 67 89 AB CD EF 10 01 22 06 4E
30 43 41 4C 4C 29 00 00 00 00 84 42 4B 41 32 02
43 57 3D 00 00 A0 40 45 00 00 FA 43 52 12 09 33
33 33 33 33 F3 40 C0 11 66 66 66 66 66 E6 62 40
</syntaxhighlight>

In protobuf text form:

<syntaxhighlight lang="text">
station_list { request_id: 5 captured_at_ms: 1793000001000 stations { core { station_id: "\021\021\021\021\"\"C3\204DUUUUUU" revision: 4 kind: STATION_KIND_GROUND name: "Budapest" callsign: "HA5GS" owner_handle: "operator" visibility: STATION_VISIBILITY_PUBLIC location { latitude_deg: 47.5 longitude_deg: 19.0 altitude_meters: 120.0 } } sessions { session_id: "\252\252\252\252\273\273L\314\215\335\356\356\356\356\356\356" role: SESSION_ROLE_TX antenna_id: "\021\021\021\021\"\"C3\204Dffffff" callsign: "HA5GS" frequency_hz: 1.4074E7 modulation: "USB" power_watts: 50.0 bandwidth_hz: 2700.0 location { latitude_deg: 47.5 longitude_deg: 19.0 altitude_meters: 120.0 } } sessions { session_id: "\252\252\252\252\273\273L\314\215\335\377\377\377\377\377\377" role: SESSION_ROLE_RX antenna_id: "\021\021\021\021\"\"C3\204Dffffff" callsign: "HA5GS" frequency_hz: 7074000.0 bandwidth_hz: 12000.0 location { latitude_deg: 47.5 longitude_deg: 19.0 altitude_meters: 120.0 } } } stations { core { station_id: "\231\231\231\231\210\210Gw\206fUUUUUU" revision: 3 kind: STATION_KIND_SATELLITE name: "SimSat-1" callsign: "SSAT1" owner_handle: "operator" visibility: STATION_VISIBILITY_PUBLIC location { latitude_deg: 10.0 longitude_deg: 20.0 altitude_meters: 550000.0 } orbit { model: "simtx-j2-v1" epoch_seconds: 1792843200 semi_major_axis_km: 6921.0 eccentricity: 0.001 inclination_deg: 97.6 raan_deg: 120.0 argument_of_perigee_deg: 90.0 mean_anomaly_deg: 10.0 } attitude { nadir { } } } } stations { core { callsign: "N0CALL" location { latitude_deg: -33.9 longitude_deg: 151.2 } } sessions { session_id: "\0224Vx\232\274M\357\201#Eg\211\253\315\357" role: SESSION_ROLE_TX callsign: "N0CALL" frequency_hz: 3573000.0 modulation: "CW" power_watts: 5.0 bandwidth_hz: 500.0 location { latitude_deg: -33.9 longitude_deg: 151.2 } } } }
</syntaxhighlight>

'''<code>station_list_deorbiting_satellite</code>''' (server to client, 225 bytes):

<syntaxhighlight lang="text">
DF 01                                           frame length 223
F2 01 DB 01                                     station_list (StationList), 219 bytes
  08 06                                         request_id = 6
  10 D0 A3 83 B9 97 34                          captured_at_ms = 1793000002000
  1A CF 01                                      stations (Station), 207 bytes
    0A CC 01                                    core (StationCore), 204 bytes
      0A 10 99 99 99 99 …                       station_id = 99999999-8888-4777-8666-555555555555
      10 04                                     revision = 4
      18 02                                     kind = 2 (STATION_KIND_SATELLITE)
      22 08 53 69 6D 53 61 74 2D 31             name = "SimSat-1"
      2A 05 53 53 41 54 31                      callsign = "SSAT1"
      32 08 6F 70 65 72 61 74 6F 72             owner_handle = "operator"
      38 01                                     visibility = 1 (STATION_VISIBILITY_PUBLIC)
      42 1B                                     location (GeoPoint), 27 bytes
        09 00 00 00 00 00 00 29 C0              latitude_deg = -12.5
        11 00 00 00 00 00 80 40 40              longitude_deg = 33.0
        19 00 00 00 00 40 06 19 41              altitude_meters = 410000.0
      4A 49                                     orbit (OrbitalElements), 73 bytes
        0A 0B 73 69 6D 74 78 2D 6A 32 2D 76 31  model = "simtx-j2-v1"
        10 D0 D7 F2 D6 06                       epoch_seconds = 1792846800
        21 00 00 00 00 00 23 BA 40              semi_major_axis_km = 6691.0
        29 22 FD F6 75 E0 9C 91 3F              eccentricity = 0.0172
        31 66 66 66 66 66 66 58 40              inclination_deg = 97.6
        39 00 00 00 00 00 00 5E 40              raan_deg = 120.0
        41 00 00 00 00 00 80 56 40              argument_of_perigee_deg = 90.0
        49 00 00 00 00 00 00 69 40              mean_anomaly_deg = 200.0
      52 02                                     attitude (Attitude), 2 bytes
        0A 00                                   nadir (Nadir), 0 bytes
      5A 2B                                     deorbit (Deorbit), 43 bytes
        08 80 C9 FC EF 96 34                    burn_at_ms = 1792846800000
        10 90 C6 94 F1 96 34                    reentry_at_ms = 1792849290000
        1A 12                                   reentry_point (GeoPoint), 18 bytes
          09 00 00 00 00 00 20 43 C0            latitude_deg = -38.25
          11 00 00 00 00 00 70 62 40            longitude_deg = 147.5
        21 00 00 00 00 00 E0 4E 40              delta_v_mps = 61.75
</syntaxhighlight>

== See also ==
* [[SimTX API/Control session#Station list|Station list]]
* [[SimTX API/Stations]]
* [[SimTX API/Satellites]]

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