SimTX API/Packet list

This page lists every message that can be sent as a frame of the SimTX API game protocol, version 25. Each frame is a ClientFrame (client to server) or a ServerFrame (server to client) with exactly one oneof 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 weather_map both ways, but this is only a convention.

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

Framing

varint      length
bytes       ClientFrame or ServerFrame, exactly one member set

A reader skips a frame whose member it does not know and keeps reading. See Unknown frames and fields.

Client to server

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

Server to client

#	Member	Message	Session	Summary
1	hello_result	ServerHello	All roles	Answers the ClientHello.
2	pong	Pong	All roles	Answers a Ping.
3	error	Error	All roles	The single error frame of protocol v25.
4	banner	Banner	Control	Carries a server-wide notice for the client to display, such as planned maintenance, a performance warning or a ban notice.
10	session_status	SessionStatus	Receiver, transmitter	The server's account of a receiver or transmitter session: once when the start is accepted (BOUND), on every change the session survives (UPDATED), and when it is refused or stopped (REJECTED, ENDED).
11	iq_descriptor	IqStreamDescriptor	Receiver	States the parameters of the IQ stream a receiver is about to get.
12	iq	IqBlock	Receiver	Carries one block of received complex baseband samples.
13	tx_queue	TxQueue	Transmitter	Tells a transmitter client that every transmitter slot on the server is taken and that its start is waiting in line.
14	tx_accept	TxAccept	Transmitter	Tells a transmitter client that its station is on the air.
17	tx_telemetry	TxTelemetry	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	tx_update_ack	TxUpdateAck	Transmitter	Reports the outcome of a TxUpdate, one result per field that was set.
30	station_list	StationList	Control, 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	monitor_block	MonitorBlock	Control, moderation	Carries a block of a monitored transmitter's signal, as requested with StartMonitor.
32	monitor_end	MonitorEnd	Control, moderation	Tells the client that the server ended a running monitor stream, for example because the transmitter went off the air.
33	weather_map	WeatherMapResponse	Control	Returns the raster requested by a WeatherMapRequest, with a summary of the weather at the centre of the area.
34	health	ServerHealthReport	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	coverage_map	CoverageMapResponse	Control	Returns the predicted received power of a CoverageMapRequest as a global raster.
36	catalog_list	CatalogList	Control (catalog)	The index of the extension catalog: one summary per entry, without file contents.
37	catalog_entry	CatalogEntry	Control (catalog)	Returns the files of one catalog entry requested with CatalogFetch.
38	catalog_upload_result	CatalogUploadResult	Control (catalog)	Confirms a successful CatalogUpload.
39	catalog_delete_result	CatalogDeleteResult	Control (catalog)	Confirms that a CatalogDelete removed the entry.
40	ephemeris	EphemerisResponse	Control	Returns the satellite positions requested by an EphemerisRequest.
41	passes	PassPredictionResponse	Control	Lists the passes found for a PassPredictionRequest.
42	monitor_ack	MonitorAck	Control, moderation	Confirms a StartMonitor (active = true) or a StopMonitor (active = false).
60	kick_result	KickResult	Moderation	Reports how many sessions a KickRequest disconnected.
61	ip_moderation_result	IpModerationResult	Moderation	Reports the outcome of an IpModerationRequest.
63	station_impacts	StationImpactList	Moderation	An interference analysis for moderators.

Reserved in this direction (never reused): 15, 16, 62 (tx_reject, tx_kick, moderation_error).

By session

Session	Client sends	Server sends
All roles	hello (first), ping	hello_result (first), pong, error
Receiver	forwarded_address (proxies only), receiver_start, receiver_retune, pointing	session_status, iq_descriptor, iq
Transmitter	transmitter_start, samples, tx_update, tx_mode_info, pointing	session_status, tx_queue, tx_accept, tx_telemetry, tx_update_ack
Control	list_stations, start_monitor, stop_monitor, weather_map, health, coverage_map, catalog_*, ephemeris, passes	the matching responses, monitor_ack, monitor_block, monitor_end, banner
Moderation	list_stations, kick, ip_moderation, broadcast_banner, start_monitor, stop_monitor	station_list, station_impacts, kick_result, ip_moderation_result, monitor frames

A frame that is known but not allowed in the current session is a protocol violation: the server answers Error INVALID_REQUEST and closes the connection.

Removed v24 packets

These v24 packets have no v25 message of the same name. Their pages explain what replaced them.

v24 packet	Replaced in v25 by
Handshake	The preface and ClientHello
HandshakeResult	ServerHello
ReceiverSessionRequest	ReceiverStart
TransmitterSessionRequest	TransmitterStart
TimedIqBlock	IqBlock with timestamps
ControlAck	Nothing; an accepted ServerHello suffices
TxReject	SessionStatus REJECTED
TxKick	SessionStatus ENDED
ModerationError	Error

The packet pages are also grouped in Category:SimTX API packets. The v24 packet list is archived at SimTX API v24/Packet list.