Editing SimTX API/Packet list

{{SimTX API navigation}}
This page lists every message that can be sent as a frame of the [[SimTX API]] game protocol, version 25. Each frame is a <code>ClientFrame</code> (client to server) or a <code>ServerFrame</code> (server to client) with exactly one <code>oneof</code> member set; the member's number identifies the message. The two directions have separate number spaces, allocated in the same blocks: 1 to 9 for the connection, 10 to 29 for receiver and transmitter sessions, 30 to 59 for control and 60 to 79 for moderation. Some numbers mean the same thing in both directions, for example 33 is <code>weather_map</code> both ways.

Every message has its own page, and the wire format is described on [[SimTX API/Framing]].

== Framing ==
<syntaxhighlight lang="text">
varint      length
bytes       ClientFrame or ServerFrame, exactly one member set
</syntaxhighlight>

A reader skips a frame whose member it does not know and keeps reading. See [[SimTX API/Framing#Unknown frames and fields|Unknown frames and fields]].

== Client to server ==
{| class="wikitable sortable"
! # !! Member !! Message !! Session !! Summary
|-
| 1 || <code>hello</code> || [[SimTX API/Packets/ClientHello|ClientHello]] || [[SimTX API/Connection and handshake|All roles]] || Opens every game connection.
|-
| 2 || <code>ping</code> || [[SimTX API/Packets/Ping|Ping]] || [[SimTX API/Connection and handshake|All roles]] || Asks the server for a [[SimTX API/Packets/Pong|Pong]].
|-
| 3 || <code>forwarded_address</code> || [[SimTX API/Packets/ForwardedClientAddress|ForwardedClientAddress]] || [[SimTX API/Receiver session|Receiver]] || Lets a trusted proxy, such as a web receiver that relays SimTX to browsers, tell the server the real address of the person it serves.
|-
| 10 || <code>receiver_start</code> || [[SimTX API/Packets/ReceiverStart|ReceiverStart]] || [[SimTX API/Receiver session|Receiver]] || Starts a [[SimTX API/Receiver session|receiver session]].
|-
| 11 || <code>receiver_retune</code> || [[SimTX API/Packets/ReceiverRetune|ReceiverRetune]] || [[SimTX API/Receiver session|Receiver]] || Moves a running receiver to a new centre frequency without reconnecting.
|-
| 12 || <code>transmitter_start</code> || [[SimTX API/Packets/TransmitterStart|TransmitterStart]] || [[SimTX API/Transmitter session|Transmitter]] || Starts a [[SimTX API/Transmitter session|transmitter session]].
|-
| 13 || <code>samples</code> || [[SimTX API/Packets/SampleBlock|SampleBlock]] || [[SimTX API/Transmitter session|Transmitter]] || Carries samples for the server to transmit.
|-
| 14 || <code>tx_update</code> || [[SimTX API/Packets/TxUpdate|TxUpdate]] || [[SimTX API/Transmitter session|Transmitter]] || Changes transmitter settings while the station is on air, without reconnecting.
|-
| 15 || <code>tx_mode_info</code> || [[SimTX API/Packets/TxModeInfo|TxModeInfo]] || [[SimTX API/Transmitter session|Transmitter]] || Declares a human-readable name and occupied bandwidth for the signal a transmitter is sending.
|-
| 16 || <code>pointing</code> || [[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]] || [[SimTX API/Receiver session|Receiver]], [[SimTX API/Transmitter session|transmitter]] || Steers the antenna of a running station-bound session, or changes its tracking and Doppler correction, without reconnecting.
|-
| 30 || <code>list_stations</code> || [[SimTX API/Packets/ListStations|ListStations]] || [[SimTX API/Control session|Control]], [[SimTX API/Moderation session|moderation]] || Asks for the list of stations on the server.
|-
| 31 || <code>start_monitor</code> || [[SimTX API/Packets/StartMonitor|StartMonitor]] || [[SimTX API/Control session|Control]], [[SimTX API/Moderation session|moderation]] || Asks the server to stream the signal of a transmitter back to the client.
|-
| 32 || <code>stop_monitor</code> || [[SimTX API/Packets/StopMonitor|StopMonitor]] || [[SimTX API/Control session|Control]], [[SimTX API/Moderation session|moderation]] || Ends a monitor stream started with [[SimTX API/Packets/StartMonitor|StartMonitor]].
|-
| 33 || <code>weather_map</code> || [[SimTX API/Packets/WeatherMapRequest|WeatherMapRequest]] || [[SimTX API/Control session|Control]] || Asks for a raster of the simulated tropospheric weather over an area.
|-
| 34 || <code>health</code> || [[SimTX API/Packets/ServerHealthRequest|ServerHealthRequest]] || [[SimTX API/Control session|Control]] || Asks for a [[SimTX API/Packets/ServerHealthReport|ServerHealthReport]].
|-
| 35 || <code>coverage_map</code> || [[SimTX API/Packets/CoverageMapRequest|CoverageMapRequest]] || [[SimTX API/Control session|Control]] || Asks the server to predict where a hypothetical transmitter could be heard.
|-
| 36 || <code>catalog_list</code> || [[SimTX API/Packets/CatalogListRequest|CatalogListRequest]] || [[SimTX API/Extension catalog protocol|Control (catalog)]] || Asks for the index of the server's [[SimTX API/Extension catalog protocol|extension catalog]].
|-
| 37 || <code>catalog_fetch</code> || [[SimTX API/Packets/CatalogFetch|CatalogFetch]] || [[SimTX API/Extension catalog protocol|Control (catalog)]] || Downloads one entry of the [[SimTX API/Extension catalog protocol|extension catalog]], including the contents of all its files.
|-
| 38 || <code>catalog_upload</code> || [[SimTX API/Packets/CatalogUpload|CatalogUpload]] || [[SimTX API/Extension catalog protocol|Control (catalog)]] || Publishes an extension or preset to the server's [[SimTX API/Extension catalog protocol|extension catalog]], or a new revision of an entry the account already owns.
|-
| 39 || <code>catalog_delete</code> || [[SimTX API/Packets/CatalogDelete|CatalogDelete]] || [[SimTX API/Extension catalog protocol|Control (catalog)]] || Removes an entry from the [[SimTX API/Extension catalog protocol|extension catalog]].
|-
| 40 || <code>ephemeris</code> || [[SimTX API/Packets/EphemerisRequest|EphemerisRequest]] || [[SimTX API/Control session|Control]] || Asks the server for the positions of a satellite over a time window.
|-
| 41 || <code>passes</code> || [[SimTX API/Packets/PassPredictionRequest|PassPredictionRequest]] || [[SimTX API/Control session|Control]] || Asks the server when a satellite will be above an observer's horizon within a time window.
|-
| 60 || <code>kick</code> || [[SimTX API/Packets/KickRequest|KickRequest]] || [[SimTX API/Moderation session|Moderation]] || Disconnects sessions from the server.
|-
| 61 || <code>ip_moderation</code> || [[SimTX API/Packets/IpModerationRequest|IpModerationRequest]] || [[SimTX API/Moderation session|Moderation]] || Bans or unbans a client address.
|-
| 62 || <code>broadcast_banner</code> || [[SimTX API/Packets/BroadcastBanner|BroadcastBanner]] || [[SimTX API/Moderation session|Moderation]] || Sets, replaces or clears the server-wide notice.
|}

== Server to client ==
{| class="wikitable sortable"
! # !! Member !! Message !! Session !! Summary
|-
| 1 || <code>hello_result</code> || [[SimTX API/Packets/ServerHello|ServerHello]] || [[SimTX API/Connection and handshake|All roles]] || Answers the [[SimTX API/Packets/ClientHello|ClientHello]].
|-
| 2 || <code>pong</code> || [[SimTX API/Packets/Pong|Pong]] || [[SimTX API/Connection and handshake|All roles]] || Answers a [[SimTX API/Packets/Ping|Ping]].
|-
| 3 || <code>error</code> || [[SimTX API/Packets/Error|Error]] || [[SimTX API/Connection and handshake|All roles]] || Reports a failed control or moderation request, a refused live request on a receiver or transmitter session, or a protocol violation of the connection as a whole.
|-
| 4 || <code>banner</code> || [[SimTX API/Packets/Banner|Banner]] || [[SimTX API/Control session|Control]] || Carries a server-wide notice for the client to display, such as planned maintenance, a performance warning or a ban notice.
|-
| 10 || <code>session_status</code> || [[SimTX API/Packets/SessionStatus|SessionStatus]] || [[SimTX API/Receiver session|Receiver]], [[SimTX API/Transmitter session|transmitter]] || The server's account of a receiver or transmitter session: once when the start is accepted (<code>BOUND</code>), on every change the session survives (<code>UPDATED</code>), and when it is refused or stopped (<code>REJECTED</code>, <code>ENDED</code>).
|-
| 11 || <code>iq_descriptor</code> || [[SimTX API/Packets/IqStreamDescriptor|IqStreamDescriptor]] || [[SimTX API/Receiver session|Receiver]] || States the parameters of the IQ stream a receiver is about to get.
|-
| 12 || <code>iq</code> || [[SimTX API/Packets/IqBlock|IqBlock]] || [[SimTX API/Receiver session|Receiver]] || Carries one block of received complex baseband samples.
|-
| 13 || <code>tx_queue</code> || [[SimTX API/Packets/TxQueue|TxQueue]] || [[SimTX API/Transmitter session|Transmitter]] || Tells a transmitter client that every transmitter slot on the server is taken and that its start is waiting in line.
|-
| 14 || <code>tx_accept</code> || [[SimTX API/Packets/TxAccept|TxAccept]] || [[SimTX API/Transmitter session|Transmitter]] || Tells a transmitter client that its station is on the air.
|-
| 17 || <code>tx_telemetry</code> || [[SimTX API/Packets/TxTelemetry|TxTelemetry]] || [[SimTX API/Transmitter session|Transmitter]] || Reports the state of a transmitter on air: power at each point of the chain, standing-wave ratio, amplifier compression and temperature, and the server's playout buffer.
|-
| 18 || <code>tx_update_ack</code> || [[SimTX API/Packets/TxUpdateAck|TxUpdateAck]] || [[SimTX API/Transmitter session|Transmitter]] || Reports the outcome of a [[SimTX API/Packets/TxUpdate|TxUpdate]], one result per field that was set.
|-
| 30 || <code>station_list</code> || [[SimTX API/Packets/StationList|StationList]] || [[SimTX API/Control session|Control]], [[SimTX API/Moderation session|moderation]] || Lists the stations on the server: every persistent station with live sessions, every visible satellite (with or without sessions), and every ad-hoc session.
|-
| 31 || <code>monitor_block</code> || [[SimTX API/Packets/MonitorBlock|MonitorBlock]] || [[SimTX API/Control session|Control]], [[SimTX API/Moderation session|moderation]] || Carries a block of a monitored transmitter's signal, as requested with [[SimTX API/Packets/StartMonitor|StartMonitor]].
|-
| 32 || <code>monitor_end</code> || [[SimTX API/Packets/MonitorEnd|MonitorEnd]] || [[SimTX API/Control session|Control]], [[SimTX API/Moderation session|moderation]] || Tells the client that the server ended a running monitor stream, for example because the transmitter went off the air.
|-
| 33 || <code>weather_map</code> || [[SimTX API/Packets/WeatherMapResponse|WeatherMapResponse]] || [[SimTX API/Control session|Control]] || Returns the raster requested by a [[SimTX API/Packets/WeatherMapRequest|WeatherMapRequest]], with a summary of the weather at the centre of the area.
|-
| 34 || <code>health</code> || [[SimTX API/Packets/ServerHealthReport|ServerHealthReport]] || [[SimTX API/Control session|Control]] || Describes the load and internal state of a game server: CPU and memory, simulation timing, worker queues, and per-session statistics for every transmitter and receiver.
|-
| 35 || <code>coverage_map</code> || [[SimTX API/Packets/CoverageMapResponse|CoverageMapResponse]] || [[SimTX API/Control session|Control]] || Returns the predicted received power of a [[SimTX API/Packets/CoverageMapRequest|CoverageMapRequest]] as a global raster.
|-
| 36 || <code>catalog_list</code> || [[SimTX API/Packets/CatalogList|CatalogList]] || [[SimTX API/Extension catalog protocol|Control (catalog)]] || The index of the [[SimTX API/Extension catalog protocol|extension catalog]]: one summary per entry, without file contents.
|-
| 37 || <code>catalog_entry</code> || [[SimTX API/Packets/CatalogEntry|CatalogEntry]] || [[SimTX API/Extension catalog protocol|Control (catalog)]] || Returns the files of one catalog entry requested with [[SimTX API/Packets/CatalogFetch|CatalogFetch]].
|-
| 38 || <code>catalog_upload_result</code> || [[SimTX API/Packets/CatalogUploadResult|CatalogUploadResult]] || [[SimTX API/Extension catalog protocol|Control (catalog)]] || Confirms a successful [[SimTX API/Packets/CatalogUpload|CatalogUpload]].
|-
| 39 || <code>catalog_delete_result</code> || [[SimTX API/Packets/CatalogDeleteResult|CatalogDeleteResult]] || [[SimTX API/Extension catalog protocol|Control (catalog)]] || Confirms that a [[SimTX API/Packets/CatalogDelete|CatalogDelete]] removed the entry.
|-
| 40 || <code>ephemeris</code> || [[SimTX API/Packets/EphemerisResponse|EphemerisResponse]] || [[SimTX API/Control session|Control]] || Returns the satellite positions requested by an [[SimTX API/Packets/EphemerisRequest|EphemerisRequest]].
|-
| 41 || <code>passes</code> || [[SimTX API/Packets/PassPredictionResponse|PassPredictionResponse]] || [[SimTX API/Control session|Control]] || Lists the passes found for a [[SimTX API/Packets/PassPredictionRequest|PassPredictionRequest]].
|-
| 42 || <code>monitor_ack</code> || [[SimTX API/Packets/MonitorAck|MonitorAck]] || [[SimTX API/Control session|Control]], [[SimTX API/Moderation session|moderation]] || Confirms a [[SimTX API/Packets/StartMonitor|StartMonitor]] (<code>active = true</code>) or a [[SimTX API/Packets/StopMonitor|StopMonitor]] (<code>active = false</code>).
|-
| 60 || <code>kick_result</code> || [[SimTX API/Packets/KickResult|KickResult]] || [[SimTX API/Moderation session|Moderation]] || Reports how many sessions a [[SimTX API/Packets/KickRequest|KickRequest]] disconnected.
|-
| 61 || <code>ip_moderation_result</code> || [[SimTX API/Packets/IpModerationResult|IpModerationResult]] || [[SimTX API/Moderation session|Moderation]] || Reports the outcome of an [[SimTX API/Packets/IpModerationRequest|IpModerationRequest]].
|-
| 63 || <code>station_impacts</code> || [[SimTX API/Packets/StationImpactList|StationImpactList]] || [[SimTX API/Moderation session|Moderation]] || An interference analysis for moderators.
|}

Member numbers 15, 16 and 62 are reserved; do not use them.

== By session ==
{| class="wikitable"
! Session !! Client sends !! Server sends
|-
| All roles || <code>hello</code> (first), <code>ping</code> || <code>hello_result</code> (first), <code>pong</code>, <code>error</code>
|-
| [[SimTX API/Receiver session|Receiver]] || <code>forwarded_address</code> (proxies only), <code>receiver_start</code>, <code>receiver_retune</code>, <code>pointing</code> || <code>session_status</code>, <code>iq_descriptor</code>, <code>iq</code>
|-
| [[SimTX API/Transmitter session|Transmitter]] || <code>transmitter_start</code>, <code>samples</code>, <code>tx_update</code>, <code>tx_mode_info</code>, <code>pointing</code> || <code>session_status</code>, <code>tx_queue</code>, <code>tx_accept</code>, <code>tx_telemetry</code>, <code>tx_update_ack</code>
|-
| [[SimTX API/Control session|Control]] || <code>list_stations</code>, <code>start_monitor</code>, <code>stop_monitor</code>, <code>weather_map</code>, <code>health</code>, <code>coverage_map</code>, <code>catalog_*</code>, <code>ephemeris</code>, <code>passes</code> || the matching responses, <code>monitor_ack</code>, <code>monitor_block</code>, <code>monitor_end</code>, <code>banner</code>
|-
| [[SimTX API/Moderation session|Moderation]] || <code>list_stations</code>, <code>kick</code>, <code>ip_moderation</code>, <code>broadcast_banner</code>, <code>start_monitor</code>, <code>stop_monitor</code> || <code>station_list</code>, <code>station_impacts</code>, <code>kick_result</code>, <code>ip_moderation_result</code>, monitor frames
|}

A frame that is known but not allowed in the current session is a protocol violation: the server answers [[SimTX API/Packets/Error|Error]] <code>INVALID_REQUEST</code> and closes the connection.

The packet pages are also grouped in [[:Category:SimTX API packets]].

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