SimTX API v24/Control session - Revision history

Clanker: Archive the v24 protocol reference: use the v24 templates, links and categories

2026-10-24T16:13:33Z

Archive the v24 protocol reference: use the v24 templates, links and categories

Clanker: Clanker moved page SimTX API/Control session to SimTX API v24/Control session: Archive the v24 protocol reference

2026-10-24T16:12:02Z

Clanker moved page SimTX API/Control session to SimTX API v24/Control session: Archive the v24 protocol reference

← Older revision	Revision as of 16:12, 24 October 2026
(No difference)

Clanker: SimTX API documentation

2026-10-24T09:56:41Z

SimTX API documentation

New page

{{SimTX API navigation}}
A '''control session''' is a request–response channel for everything that is not a radio stream: the list of stations on the server, server-wide notices, health statistics, predicted coverage and tropospheric weather maps, monitoring one's own transmitter, and the [[SimTX API/Extension catalog protocol|extension catalog]]. Control sessions use role 4 (<code>CONTROL</code>) and accept anonymous connections.

The official transmitter keeps one control session open for its station list, banners and catalog browser. A station map, a band-activity bot or a status page needs nothing else.

== Packets ==
{| class="wikitable"
! Request (C2S) !! Response (S2C) !! Heavy !! Purpose
|-
| [[SimTX API/Packets/ListStations|ListStations]] (4) || [[SimTX API/Packets/StationList|StationList]] (9) || Yes || All stations on the server.
|-
| [[SimTX API/Packets/ServerHealthRequest|ServerHealthRequest]] (10) || [[SimTX API/Packets/ServerHealthReport|ServerHealthReport]] (16) || Yes || Load and session statistics.
|-
| [[SimTX API/Packets/CoverageMapRequest|CoverageMapRequest]] (24) || [[SimTX API/Packets/CoverageMapResponse|CoverageMapResponse]] (27) || Yes || Predicted received power for a hypothetical transmitter.
|-
| [[SimTX API/Packets/WeatherMapRequest|WeatherMapRequest]] (8) || [[SimTX API/Packets/WeatherMapResponse|WeatherMapResponse]] (14) || Yes || Tropospheric weather raster.
|-
| [[SimTX API/Packets/StartMonitor|StartMonitor]] (6) || [[SimTX API/Packets/MonitorBlock|MonitorBlock]] (10) … [[SimTX API/Packets/MonitorEnd|MonitorEnd]] (11) || No || Stream of one's own transmitted signal.
|-
| [[SimTX API/Packets/StopMonitor|StopMonitor]] (7) || None || No || Ends a monitor stream.
|-
| [[SimTX API/Packets/CatalogListRequest|CatalogListRequest]] (20) || [[SimTX API/Packets/CatalogList|CatalogList]] (24) || Yes || Catalog index.
|-
| [[SimTX API/Packets/CatalogFetch|CatalogFetch]] (21) || [[SimTX API/Packets/CatalogEntry|CatalogEntry]] (25) || Yes || One catalog entry with its files.
|-
| [[SimTX API/Packets/CatalogUpload|CatalogUpload]] (22) || [[SimTX API/Packets/CatalogUploadResult|CatalogUploadResult]] (21) || Yes || Publish an entry.
|-
| [[SimTX API/Packets/CatalogDelete|CatalogDelete]] (26) || [[SimTX API/Packets/CatalogDeleteResult|CatalogDeleteResult]] (29) || Yes || Remove an entry.
|}

Unsolicited server packets:
* [[SimTX API/Packets/ControlAck|ControlAck]] (8), once, as soon as the session is accepted.
* [[SimTX API/Packets/Banner|Banner]] (17), on accept if a notice is active, and at any later time when a notice is set, changed or cleared.

Any other packet closes the connection.

== Sequence ==
<syntaxhighlight lang="text">
client server
| -- Handshake (role 4, anonymous) ------------> |
| <----------------------- [30] HandshakeResult |
| <----------------------------- [8] ControlAck |
| <------------------------------- [17] Banner | (only if a notice is active)
| -- [4] ListStations -------------------------> |
| <---------------------------- [9] StationList |
| ... |
| <------------------------------- [17] Banner | (any time)
</syntaxhighlight>

Responses to requests arrive in the order the requests were sent, but a [[SimTX API/Packets/Banner|Banner]] or a [[SimTX API/Packets/MonitorBlock|MonitorBlock]] may arrive between any two of them. Read the session with a loop that dispatches on the packet ID, rather than expecting a particular reply next. A [[SimTX API/Packets/CoverageMapResponse|CoverageMapResponse]] carries the request ID it answers, because coverage predictions may take several seconds.

The session has no idle timeout. A client may keep it open indefinitely and send requests when needed.

== Rate limits ==
Control requests are limited by token buckets shared by '''all control connections from the same IP address''':

{| class="wikitable"
! Bucket !! Sustained !! Burst
|-
| All requests, per IP || 20 per second || 40
|-
| Heavy requests, per IP || 4 per second || 12
|-
| All requests, whole server || 200 per second || 400
|-
| Heavy requests, whole server || 40 per second || 80
|}

A heavy request draws from both its heavy bucket and the general bucket. Exceeding a limit '''closes the control connection''' without a message. Opening more connections does not help, since the per-IP bucket is shared.

In practice: poll the station list every few seconds at most, request the health report rarely, and do not fetch the whole catalog in a tight loop. A client that reconnects after being closed for rate limiting should wait a few seconds first.

== Station list ==
[[SimTX API/Packets/StationList|StationList]] contains every transmitter and receiver on the server, with callsign, frequency, mode, power, position and occupied bandwidth. Client IP addresses are never included on a control session. The list is a snapshot. Clients that need to follow changes poll it.

== Health report ==
[[SimTX API/Packets/ServerHealthReport|ServerHealthReport]] exposes the server's load: CPU, memory, simulation tick timing, worker queues, and per-session statistics for every transmitter and receiver. It is intended for status pages and operators. Client addresses in it are empty unless the account holds <code>monitor.any</code> or <code>moderation.manage</code>.

== Maps ==
* '''Coverage maps''' predict, for a hypothetical transmitter, the power a standard receiving antenna would see across the whole globe. Coverage prediction is optional and is '''disabled by default'''; a server without it answers every request as unavailable. One prediction runs at a time on the whole server, with one more waiting. See [[SimTX API/Packets/CoverageMapRequest|CoverageMapRequest]].
* '''Weather maps''' show the simulated troposphere over a chosen area: duct strength, rain rate, cloud water, surface temperature or lightning rate. They affect VHF and higher propagation. See [[SimTX API/Packets/WeatherMapRequest|WeatherMapRequest]].

== Monitoring a transmitter ==
[[SimTX API/Packets/StartMonitor|StartMonitor]] streams the complex baseband a transmitter is producing, after its modulator and amplifier model but before the antenna and propagation. It is how the official application lets an operator hear their own signal.

Only transmitters belonging to the same account can be monitored, so the control session must be authenticated. Because the account service issues <code>control</code> tickets only to credentials with the <code>catalog.publish</code> permission, monitoring currently requires that permission as well. See [[SimTX API/Game tickets#Roles|Game tickets]].

Monitor blocks share the control session's output queue (64 packets or 8 MiB). A client that does not read them fast enough has its control connection closed.

== See also ==
* [[SimTX API/Extension catalog protocol]]: the catalog requests in detail.
* [[SimTX API/Moderation session]]: the moderator equivalent of this session.

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

← Older revision		Revision as of 16:13, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{SimTX API v24 navigation}}
	A '''control session''' is a request–response channel for everything that is not a radio stream: the list of stations on the server, server-wide notices, health statistics, predicted coverage and tropospheric weather maps, monitoring one's own transmitter, and the [[SimTX API/Extension catalog protocol\|extension catalog]]. Control sessions use role 4 (<code>CONTROL</code>) and accept anonymous connections.		A '''control session''' is a request–response channel for everything that is not a radio stream: the list of stations on the server, server-wide notices, health statistics, predicted coverage and tropospheric weather maps, monitoring one's own transmitter, and the [[SimTX API v24/Extension catalog protocol\|extension catalog]]. Control sessions use role 4 (<code>CONTROL</code>) and accept anonymous connections.

	The official transmitter keeps one control session open for its station list, banners and catalog browser. A station map, a band-activity bot or a status page needs nothing else.		The official transmitter keeps one control session open for its station list, banners and catalog browser. A station map, a band-activity bot or a status page needs nothing else.
Line 8:		Line 8:
	! Request (C2S) !! Response (S2C) !! Heavy !! Purpose		! Request (C2S) !! Response (S2C) !! Heavy !! Purpose
	\|-		\|-
	\| [[SimTX API/Packets/ListStations\|ListStations]] (4) \|\| [[SimTX API/Packets/StationList\|StationList]] (9) \|\| Yes \|\| All stations on the server.		\| [[SimTX API v24/Packets/ListStations\|ListStations]] (4) \|\| [[SimTX API v24/Packets/StationList\|StationList]] (9) \|\| Yes \|\| All stations on the server.
	\|-		\|-
	\| [[SimTX API/Packets/ServerHealthRequest\|ServerHealthRequest]] (10) \|\| [[SimTX API/Packets/ServerHealthReport\|ServerHealthReport]] (16) \|\| Yes \|\| Load and session statistics.		\| [[SimTX API v24/Packets/ServerHealthRequest\|ServerHealthRequest]] (10) \|\| [[SimTX API v24/Packets/ServerHealthReport\|ServerHealthReport]] (16) \|\| Yes \|\| Load and session statistics.
	\|-		\|-
	\| [[SimTX API/Packets/CoverageMapRequest\|CoverageMapRequest]] (24) \|\| [[SimTX API/Packets/CoverageMapResponse\|CoverageMapResponse]] (27) \|\| Yes \|\| Predicted received power for a hypothetical transmitter.		\| [[SimTX API v24/Packets/CoverageMapRequest\|CoverageMapRequest]] (24) \|\| [[SimTX API v24/Packets/CoverageMapResponse\|CoverageMapResponse]] (27) \|\| Yes \|\| Predicted received power for a hypothetical transmitter.
	\|-		\|-
	\| [[SimTX API/Packets/WeatherMapRequest\|WeatherMapRequest]] (8) \|\| [[SimTX API/Packets/WeatherMapResponse\|WeatherMapResponse]] (14) \|\| Yes \|\| Tropospheric weather raster.		\| [[SimTX API v24/Packets/WeatherMapRequest\|WeatherMapRequest]] (8) \|\| [[SimTX API v24/Packets/WeatherMapResponse\|WeatherMapResponse]] (14) \|\| Yes \|\| Tropospheric weather raster.
	\|-		\|-
	\| [[SimTX API/Packets/StartMonitor\|StartMonitor]] (6) \|\| [[SimTX API/Packets/MonitorBlock\|MonitorBlock]] (10) … [[SimTX API/Packets/MonitorEnd\|MonitorEnd]] (11) \|\| No \|\| Stream of one's own transmitted signal.		\| [[SimTX API v24/Packets/StartMonitor\|StartMonitor]] (6) \|\| [[SimTX API v24/Packets/MonitorBlock\|MonitorBlock]] (10) … [[SimTX API v24/Packets/MonitorEnd\|MonitorEnd]] (11) \|\| No \|\| Stream of one's own transmitted signal.
	\|-		\|-
	\| [[SimTX API/Packets/StopMonitor\|StopMonitor]] (7) \|\| None \|\| No \|\| Ends a monitor stream.		\| [[SimTX API v24/Packets/StopMonitor\|StopMonitor]] (7) \|\| None \|\| No \|\| Ends a monitor stream.
	\|-		\|-
	\| [[SimTX API/Packets/CatalogListRequest\|CatalogListRequest]] (20) \|\| [[SimTX API/Packets/CatalogList\|CatalogList]] (24) \|\| Yes \|\| Catalog index.		\| [[SimTX API v24/Packets/CatalogListRequest\|CatalogListRequest]] (20) \|\| [[SimTX API v24/Packets/CatalogList\|CatalogList]] (24) \|\| Yes \|\| Catalog index.
	\|-		\|-
	\| [[SimTX API/Packets/CatalogFetch\|CatalogFetch]] (21) \|\| [[SimTX API/Packets/CatalogEntry\|CatalogEntry]] (25) \|\| Yes \|\| One catalog entry with its files.		\| [[SimTX API v24/Packets/CatalogFetch\|CatalogFetch]] (21) \|\| [[SimTX API v24/Packets/CatalogEntry\|CatalogEntry]] (25) \|\| Yes \|\| One catalog entry with its files.
	\|-		\|-
	\| [[SimTX API/Packets/CatalogUpload\|CatalogUpload]] (22) \|\| [[SimTX API/Packets/CatalogUploadResult\|CatalogUploadResult]] (21) \|\| Yes \|\| Publish an entry.		\| [[SimTX API v24/Packets/CatalogUpload\|CatalogUpload]] (22) \|\| [[SimTX API v24/Packets/CatalogUploadResult\|CatalogUploadResult]] (21) \|\| Yes \|\| Publish an entry.
	\|-		\|-
	\| [[SimTX API/Packets/CatalogDelete\|CatalogDelete]] (26) \|\| [[SimTX API/Packets/CatalogDeleteResult\|CatalogDeleteResult]] (29) \|\| Yes \|\| Remove an entry.		\| [[SimTX API v24/Packets/CatalogDelete\|CatalogDelete]] (26) \|\| [[SimTX API v24/Packets/CatalogDeleteResult\|CatalogDeleteResult]] (29) \|\| Yes \|\| Remove an entry.
	\|}		\|}

	Unsolicited server packets:		Unsolicited server packets:
	* [[SimTX API/Packets/ControlAck\|ControlAck]] (8), once, as soon as the session is accepted.		* [[SimTX API v24/Packets/ControlAck\|ControlAck]] (8), once, as soon as the session is accepted.
	* [[SimTX API/Packets/Banner\|Banner]] (17), on accept if a notice is active, and at any later time when a notice is set, changed or cleared.		* [[SimTX API v24/Packets/Banner\|Banner]] (17), on accept if a notice is active, and at any later time when a notice is set, changed or cleared.

	Any other packet closes the connection.		Any other packet closes the connection.
Line 48:		Line 48:
	</syntaxhighlight>		</syntaxhighlight>

	Responses to requests arrive in the order the requests were sent, but a [[SimTX API/Packets/Banner\|Banner]] or a [[SimTX API/Packets/MonitorBlock\|MonitorBlock]] may arrive between any two of them. Read the session with a loop that dispatches on the packet ID, rather than expecting a particular reply next. A [[SimTX API/Packets/CoverageMapResponse\|CoverageMapResponse]] carries the request ID it answers, because coverage predictions may take several seconds.		Responses to requests arrive in the order the requests were sent, but a [[SimTX API v24/Packets/Banner\|Banner]] or a [[SimTX API v24/Packets/MonitorBlock\|MonitorBlock]] may arrive between any two of them. Read the session with a loop that dispatches on the packet ID, rather than expecting a particular reply next. A [[SimTX API v24/Packets/CoverageMapResponse\|CoverageMapResponse]] carries the request ID it answers, because coverage predictions may take several seconds.

	The session has no idle timeout. A client may keep it open indefinitely and send requests when needed.		The session has no idle timeout. A client may keep it open indefinitely and send requests when needed.
Line 72:		Line 72:

	== Station list ==		== Station list ==
	[[SimTX API/Packets/StationList\|StationList]] contains every transmitter and receiver on the server, with callsign, frequency, mode, power, position and occupied bandwidth. Client IP addresses are never included on a control session. The list is a snapshot. Clients that need to follow changes poll it.		[[SimTX API v24/Packets/StationList\|StationList]] contains every transmitter and receiver on the server, with callsign, frequency, mode, power, position and occupied bandwidth. Client IP addresses are never included on a control session. The list is a snapshot. Clients that need to follow changes poll it.

	== Health report ==		== Health report ==
	[[SimTX API/Packets/ServerHealthReport\|ServerHealthReport]] exposes the server's load: CPU, memory, simulation tick timing, worker queues, and per-session statistics for every transmitter and receiver. It is intended for status pages and operators. Client addresses in it are empty unless the account holds <code>monitor.any</code> or <code>moderation.manage</code>.		[[SimTX API v24/Packets/ServerHealthReport\|ServerHealthReport]] exposes the server's load: CPU, memory, simulation tick timing, worker queues, and per-session statistics for every transmitter and receiver. It is intended for status pages and operators. Client addresses in it are empty unless the account holds <code>monitor.any</code> or <code>moderation.manage</code>.

	== Maps ==		== Maps ==
	* '''Coverage maps''' predict, for a hypothetical transmitter, the power a standard receiving antenna would see across the whole globe. Coverage prediction is optional and is '''disabled by default'''; a server without it answers every request as unavailable. One prediction runs at a time on the whole server, with one more waiting. See [[SimTX API/Packets/CoverageMapRequest\|CoverageMapRequest]].		* '''Coverage maps''' predict, for a hypothetical transmitter, the power a standard receiving antenna would see across the whole globe. Coverage prediction is optional and is '''disabled by default'''; a server without it answers every request as unavailable. One prediction runs at a time on the whole server, with one more waiting. See [[SimTX API v24/Packets/CoverageMapRequest\|CoverageMapRequest]].
	* '''Weather maps''' show the simulated troposphere over a chosen area: duct strength, rain rate, cloud water, surface temperature or lightning rate. They affect VHF and higher propagation. See [[SimTX API/Packets/WeatherMapRequest\|WeatherMapRequest]].		* '''Weather maps''' show the simulated troposphere over a chosen area: duct strength, rain rate, cloud water, surface temperature or lightning rate. They affect VHF and higher propagation. See [[SimTX API v24/Packets/WeatherMapRequest\|WeatherMapRequest]].

	== Monitoring a transmitter ==		== Monitoring a transmitter ==
	[[SimTX API/Packets/StartMonitor\|StartMonitor]] streams the complex baseband a transmitter is producing, after its modulator and amplifier model but before the antenna and propagation. It is how the official application lets an operator hear their own signal.		[[SimTX API v24/Packets/StartMonitor\|StartMonitor]] streams the complex baseband a transmitter is producing, after its modulator and amplifier model but before the antenna and propagation. It is how the official application lets an operator hear their own signal.

	Only transmitters belonging to the same account can be monitored, so the control session must be authenticated. Because the account service issues <code>control</code> tickets only to credentials with the <code>catalog.publish</code> permission, monitoring currently requires that permission as well. See [[SimTX API/Game tickets#Roles\|Game tickets]].		Only transmitters belonging to the same account can be monitored, so the control session must be authenticated. Because the account service issues <code>control</code> tickets only to credentials with the <code>catalog.publish</code> permission, monitoring currently requires that permission as well. See [[SimTX API v24/Game tickets#Roles\|Game tickets]].

	Monitor blocks share the control session's output queue (64 packets or 8 MiB). A client that does not read them fast enough has its control connection closed.		Monitor blocks share the control session's output queue (64 packets or 8 MiB). A client that does not read them fast enough has its control connection closed.

	== See also ==		== See also ==
	* [[SimTX API/Extension catalog protocol]]: the catalog requests in detail.		* [[SimTX API v24/Extension catalog protocol]]: the catalog requests in detail.
	* [[SimTX API/Moderation session]]: the moderator equivalent of this session.		* [[SimTX API v24/Moderation session]]: the moderator equivalent of this session.

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