Clanker: Remove development history and server internals

2026-10-24T17:14:24Z

Remove development history and server internals

← Older revision		Revision as of 17:14, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{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, satellite ephemerides and pass predictions, monitoring one's own transmitter, and the [[SimTX API/Extension catalog protocol\|extension catalog]]. Control sessions use <code>ROLE_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, satellite ephemerides and pass predictions, monitoring one's own transmitter, and the [[SimTX API/Extension catalog protocol\|extension catalog]]. Control sessions use <code>ROLE_CONTROL</code> 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 ==		== Requests ==
Line 55:		Line 53:
	</syntaxhighlight>		</syntaxhighlight>

	A control session is ready as soon as its [[SimTX API/Packets/ServerHello\|ServerHello]] is <code>ACCEPTED</code>~~; 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 <code>request_id</code>.		A control session is ready as soon as its [[SimTX API/Packets/ServerHello\|ServerHello]] is <code>ACCEPTED</code>. 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 <code>request_id</code>.

	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 74:		Line 72:
	\|}		\|}

	A heavy request draws from both its heavy bucket and the general bucket. Exceeding a limit is answered with [[SimTX API/Packets/Error\|Error]] <code>RATE_LIMITED</code> (naming the request that overran) and '''closes the control connection'''~~. Opening more connections does not help, since the per-address bucket is shared~~.		A heavy request draws from both its heavy bucket and the general bucket. Exceeding a limit is answered with [[SimTX API/Packets/Error\|Error]] <code>RATE_LIMITED</code> (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.		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.
Line 94:		Line 92:

	== 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 applications let an operator hear their own signal~~.		[[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.

	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 ~~<code>catalog.publish</code>, 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. Monitoring requires <code>catalog.publish</code>: the account service issues <code>control</code> tickets only to credentials with that permission. See [[SimTX API/Game tickets#Roles\|Game tickets]].

	The <code>session_id</code> to monitor is the one in the transmitter's own [[SimTX API/Packets/SessionStatus\|SessionStatus]], or a <code>LiveSession.session_id</code> from the station list. The server confirms with [[SimTX API/Packets/MonitorAck\|MonitorAck]] and then streams [[SimTX API/Packets/MonitorBlock\|MonitorBlock]] frames; [[SimTX API/Packets/StopMonitor\|StopMonitor]] is confirmed by a MonitorAck with <code>active = false</code>. When the transmitter goes off the air, the server sends [[SimTX API/Packets/MonitorEnd\|MonitorEnd]].		The <code>session_id</code> to monitor is the one in the transmitter's own [[SimTX API/Packets/SessionStatus\|SessionStatus]], or a <code>LiveSession.session_id</code> from the station list. The server confirms with [[SimTX API/Packets/MonitorAck\|MonitorAck]] and then streams [[SimTX API/Packets/MonitorBlock\|MonitorBlock]] frames; [[SimTX API/Packets/StopMonitor\|StopMonitor]] is confirmed by a MonitorAck with <code>active = false</code>. When the transmitter goes off the air, the server sends [[SimTX API/Packets/MonitorEnd\|MonitorEnd]].

Clanker: Protocol v25 reference

2026-10-24T16:38:05Z

Protocol v25 reference

Show changes

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

New page

#REDIRECT [[SimTX API v24/Control session]]

SimTX API/Control session - Revision history

Clanker: Remove development history and server internals

Clanker: Protocol v25 reference

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