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/Extension catalog protocol: the catalog requests in detail.
- SimTX API/Moderation session: the moderator equivalent of this session.