Clanker: Remove development history and server internals

2026-10-24T17:14:22Z

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 '''receiver session''' delivers a continuous stream of complex baseband (IQ) samples, as received by a virtual antenna at a chosen place and frequency~~. It is what SDR software sees when it is connected to SimTX~~. Receiver sessions use <code>ROLE_RECEIVER</code>. An ad-hoc receiver works without an account; a receiver bound to a persistent station needs a game ticket for it.		A '''receiver session''' delivers a continuous stream of complex baseband (IQ) samples, as received by a virtual antenna at a chosen place and frequency. Receiver sessions use <code>ROLE_RECEIVER</code>. An ad-hoc receiver works without an account; a receiver bound to a persistent station needs a game ticket for it.

	== Frames ==		== Frames ==
Line 46:		Line 46:
	== Placing the receiver ==		== Placing the receiver ==
	<code>ReceiverStart.site</code> is a [[SimTX API/Data types#SessionSite\|SessionSite]] with exactly one member:		<code>ReceiverStart.site</code> is a [[SimTX API/Data types#SessionSite\|SessionSite]] with exactly one member:
	* '''Ad hoc''' (<code>adhoc</code>): the client gives a callsign, a [[SimTX API/Data types#GeoPoint\|position]] and an [[SimTX API/Data types#AntennaConfig\|antenna]]. Works anonymously~~. This is the simplest way to receive~~.		* '''Ad hoc''' (<code>adhoc</code>): the client gives a callsign, a [[SimTX API/Data types#GeoPoint\|position]] and an [[SimTX API/Data types#AntennaConfig\|antenna]]. Works anonymously.
	* '''Station-bound''' (<code>station</code>): the receiver uses one of the account's persistent stations, or any PUBLIC station of another account, including satellites. The station dictates the callsign, placement and antenna. The connection must present a <code>receiver</code> [[SimTX API/Game tickets\|game ticket]] minted for that station, and the [[SimTX API/Data types#StationBinding\|StationBinding]] must match it. See [[SimTX API/Stations]].		* '''Station-bound''' (<code>station</code>): the receiver uses one of the account's persistent stations, or any PUBLIC station of another account, including satellites. The station dictates the callsign, placement and antenna. The connection must present a <code>receiver</code> [[SimTX API/Game tickets\|game ticket]] minted for that station, and the [[SimTX API/Data types#StationBinding\|StationBinding]] must match it. See [[SimTX API/Stations]].

Line 59:		Line 59:

	=== Block size ===		=== Block size ===
	Each IQ block carries exactly <code>chunk_samples</code> complex samples. The requested value is clamped to at least 1,024 and at most the smaller of 1,200,000 and the number of samples in a fixed duration at the negotiated rate. That duration is '''40 ms''' on ~~the clustered public deployment and~~ 0.5 s ~~on a stand-alone server~~. At 48,000 samples per second on ~~the public server~~, blocks are 1,920 samples long whatever the client asks for.		Each IQ block carries exactly <code>chunk_samples</code> complex samples. The requested value is clamped to at least 1,024 and at most the smaller of 1,200,000 and the number of samples in a fixed duration at the negotiated rate. That duration is a server setting: '''40 ms''' on <code>argon.simtx.net</code>, 0.5 s by default. At 48,000 samples per second on <code>argon.simtx.net</code>, blocks are 1,920 samples long whatever the client asks for.

	=== Bandwidth ===		=== Bandwidth ===
Line 68:		Line 68:

	=== Noise figure ===		=== Noise figure ===
	<code>noise_figure_db</code> is the receiver's front-end noise figure. Unset, it is the bound rig's noise figure, or 6 dB. ~~Real HF receivers~~ are ~~typically~~ 3 to 8 dB~~; HF reception is usually limited by external noise anyway~~.		<code>noise_figure_db</code> is the receiver's front-end noise figure. Unset, it is the bound rig's noise figure, or 6 dB. Typical values are 3 to 8 dB.

	== Decoding samples ==		== Decoding samples ==
Line 75:		Line 75:
	<code>x = q × scale / 32767</code> (INT16) or <code>x = q × scale / 127</code> (INT8)		<code>x = q × scale / 32767</code> (INT16) or <code>x = q × scale / 127</code> (INT8)

	The server chooses <code>scale</code> as the peak magnitude of the block~~, so the integers always use the full range and small signals keep their precision~~. Check that <code>samples</code> is exactly <code>chunk_samples × 2 × bytesPerComponent</code> bytes long and reject anything else.		The server chooses <code>scale</code> as the peak magnitude of the block. Check that <code>samples</code> is exactly <code>chunk_samples × 2 × bytesPerComponent</code> bytes long and reject anything else.

	A sample with magnitude 1.0 corresponds to '''−12 dBm''' at the receiver input. The server clips each component to ±1.0 before quantising, so ~~a receiver next to~~ a strong ~~transmitter~~ overloads ~~exactly like a real one~~. To convert a block's mean power to dBm:		A sample with magnitude 1.0 corresponds to '''−12 dBm''' at the receiver input. The server clips each component to ±1.0 before quantising, so a strong signal overloads the receiver. To convert a block's mean power to dBm:

	<code>P(dBm) = −12 + 10 × log10( mean(I² + Q²) )</code>		<code>P(dBm) = −12 + 10 × log10( mean(I² + Q²) )</code>

	=== What the samples contain ===		=== What the samples contain ===
	The IQ stream is the signal at the output of the receiving antenna, after the antenna's pattern, the feed line loss and the noise figure. It includes everything a real receiver would hear: every transmitter in range with its propagation path, fading and Doppler shift, plus atmospheric, galactic and man-made noise. It does not include receiver hardware imperfections such as tuner roll-off, local-oscillator phase noise or image responses~~. Software that wants to imitate a particular radio adds those itself~~.		The IQ stream is the signal at the output of the receiving antenna, after the antenna's pattern, the feed line loss and the noise figure. It includes everything a real receiver would hear: every transmitter in range with its propagation path, fading and Doppler shift, plus atmospheric, galactic and man-made noise. It does not include receiver hardware imperfections such as tuner roll-off, local-oscillator phase noise or image responses.

	== Timestamps ==		== Timestamps ==
	With <code>timestamped</code> set in the start, every block carries the UTC instant of its first sample on the server's simulated RF timeline (<code>first_sample_epoch_seconds</code> and <code>first_sample_nanos</code>). Timestamps of different receivers are directly comparable~~, which makes them suitable for time-difference-of-arrival (TDOA) direction finding, aligning several receivers, or measuring end-to-end latency~~. Timestamps work with or without an account~~. The v24 role <code>TIMESTAMPED_RECEIVER</code> is gone~~.		With <code>timestamped</code> set in the start, every block carries the UTC instant of its first sample on the server's simulated RF timeline (<code>first_sample_epoch_seconds</code> and <code>first_sample_nanos</code>). Timestamps of different receivers are directly comparable. Timestamps work with or without an account.

	== Sequence numbers ==		== Sequence numbers ==
	<code>IqBlock.sequence</code> numbers the blocks of a stream: 1 for the first block, one more for each block after it, across retunes ~~and moves between server nodes~~. A step larger than 1 means that the server dropped blocks for this stream~~, because of backpressure, a retune or a move~~. 0 means the sender does not number blocks.		<code>IqBlock.sequence</code> numbers the blocks of a stream: 1 for the first block, one more for each block after it, across retunes. A step larger than 1 means that the server dropped blocks for this stream. 0 means the sender does not number blocks.

	== Retuning ==		== Retuning ==
Line 103:		Line 103:
	* The server queues up to 8 blocks per connection. When the queue is full, the '''oldest''' block is discarded, and the gap shows in <code>sequence</code>.		* The server queues up to 8 blocks per connection. When the queue is full, the '''oldest''' block is discarded, and the gap shows in <code>sequence</code>.
	* If the client does not read for 5 seconds, the server closes the connection.		* If the client does not read for 5 seconds, the server closes the connection.
	* Read the socket on a dedicated thread and hand blocks to processing through a queue of your own~~, so that slow processing does not stall reading.~~		* Read the socket on a dedicated thread and hand blocks to processing through a queue of your own.

	~~Through the public gateway, a receiver may be moved from one server node to another. The client sees a short gap, but the connection and the stream continue~~.

	== Failure ==		== Failure ==

Clanker: Protocol v25 reference

2026-10-24T16:36:20Z

Protocol v25 reference

Show changes

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

2026-10-24T16:20:23Z

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

New page

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

SimTX API/Receiver session - Revision history

Clanker: Remove development history and server internals

Clanker: Protocol v25 reference

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