SimTX API/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, satellite ephemerides and pass predictions, monitoring one's own transmitter, and the extension catalog. Control sessions use ROLE_CONTROL and accept anonymous connections.
The official applications keep one control session open for their station list, banners, maps and catalog browser. A station map, a band-activity bot or a status page needs nothing else.
Requests
Every request carries a nonzero request_id chosen by the client. The response echoes it. A request that fails is answered with Error carrying the same request_id instead of its response; responses describe success only.
| Request (C2S) | Response (S2C) | Heavy | Purpose |
|---|---|---|---|
| ListStations (30) | StationList (30) | Yes | Stations, satellites and live sessions on the server. |
| ServerHealthRequest (34) | ServerHealthReport (34) | Yes | Load and session statistics. |
| CoverageMapRequest (35) | CoverageMapResponse (35) | Yes | Predicted received power for a hypothetical transmitter. |
| WeatherMapRequest (33) | WeatherMapResponse (33) | Yes | Tropospheric weather raster. |
| EphemerisRequest (40) | EphemerisResponse (40) | Yes | Positions of a satellite over a time window. |
| PassPredictionRequest (41) | PassPredictionResponse (41) | Yes | Passes of a satellite over an observer. |
| StartMonitor (31) | MonitorAck (42), then MonitorBlock (31) ... MonitorEnd (32) | No | Stream of one's own transmitted signal. |
| StopMonitor (32) | MonitorAck (42) | No | Ends a monitor stream. |
| CatalogListRequest (36) | CatalogList (36) | Yes | Catalog index. |
| CatalogFetch (37) | CatalogEntry (37) | Yes | One catalog entry with its files. |
| CatalogUpload (38) | CatalogUploadResult (38) | Yes | Publish an entry. |
| CatalogDelete (39) | CatalogDeleteResult (39) | Yes | Remove an entry. |
The numbers are the frame member numbers. Ping is also accepted. Any other frame is answered with Error INVALID_REQUEST and the connection closes.
Unsolicited server frames:
- Banner (4), when the session starts if a notice is active, and at any later time when a notice is set, changed or cleared.
- MonitorBlock and MonitorEnd while a monitor runs.
Sequence
client server
| -- preface, [1] hello (ROLE_CONTROL) ----------> |
| <------------------------ [1] hello_result |
| <------------------------ [4] banner | (only if a notice is active)
| -- [30] list_stations (request_id 1) ----------> |
| <------------------------ [30] station_list | request_id 1
| -- [40] ephemeris (request_id 2) --------------> |
| <------------------------ [3] error | request_id 2, NOT_FOUND
| ... |
| <------------------------ [4] banner | (any time)
A control session is ready as soon as its ServerHello is ACCEPTED; v24's ControlAck is gone. Responses arrive in the order the requests were sent, but a Banner, a MonitorBlock or a Pong may arrive between any two of them, and slow requests (coverage maps, ephemerides, passes) are answered when they finish. Read the session with a loop that dispatches on the frame member and matches responses by request_id.
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 address | 20 per second | 40 |
| Heavy requests, per address | 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 is answered with Error RATE_LIMITED (naming the request that overran) and closes the control connection. Opening more connections does not help, since the per-address 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 lists persistent stations with their live sessions, every visible satellite even when nobody is attached, and ad-hoc sessions as entries of kind ADHOC. UNLISTED stations of other accounts appear only as ad-hoc-style entries with their callsign. Client addresses are never included on a control session. The list is a snapshot; clients that need to follow changes poll it.
For map markers, use LiveSession.location: for a satellite it is the satellite's position, and it moves. Satellites can also be drawn between polls by propagating core.orbit; see SimTX API/Satellites.
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 at a site, the power a reference receiving antenna would see across the whole globe. Servers enable them by default. One prediction runs at a time on the whole server, with one more waiting; a newer request on the same session cancels the previous one, which is answered with Error
CANCELLED. 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.
Ephemerides and passes
EphemerisRequest returns the positions of a satellite at regular steps; PassPredictionRequest returns when a satellite rises above an observer's horizon. They need the server features ephemeris and passes, listed in the ServerHello. The satellite must be PUBLIC or the account's own. Use the server's simulation clock as "now". See SimTX API/Satellites.
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 applications let 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 catalog.publish, monitoring currently requires that permission as well. See Game tickets.
The session_id to monitor is the one in the transmitter's own SessionStatus, or a LiveSession.session_id from the station list. The server confirms with MonitorAck and then streams MonitorBlock frames; StopMonitor is confirmed by a MonitorAck with active = false. When the transmitter goes off the air, the server sends MonitorEnd.
Monitor blocks share the control session's output queue (64 frames 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/Limits and errors