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.
Requests[edit | edit source]
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[edit | edit source]
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. 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[edit | edit source]
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.
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[edit | edit source]
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[edit | edit source]
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[edit | edit source]
- 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[edit | edit source]
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[edit | edit source]
StartMonitor streams the complex baseband a transmitter is producing, after its modulator and amplifier model but before the antenna and propagation.
Only transmitters belonging to the same account can be monitored, so the control session must be authenticated. Monitoring requires catalog.publish: the account service issues control tickets only to credentials with that permission. 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[edit | edit source]
- 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