SimTX API v24/Control session

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 extension catalog. Control sessions use role 4 (CONTROL) 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

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

Unsolicited server packets:

• ControlAck (8), once, as soon as the session is accepted.
• 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

 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)

Responses to requests arrive in the order the requests were sent, but a Banner or a 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 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:

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

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

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 monitor.any or moderation.manage.

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 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 WeatherMapRequest.

Monitoring a transmitter

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 control tickets only to credentials with the catalog.publish permission, monitoring currently requires that permission as well. See 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 v24/Extension catalog protocol: the catalog requests in detail.
• SimTX API v24/Moderation session: the moderator equivalent of this session.