SimTX API v24/Receiver session

A receiver session delivers a continuous stream of complex baseband (IQ) samples, as received by a virtual antenna at a chosen location and frequency. It is what SDR software sees when it is connected to SimTX. Receiver sessions use role 1 (RECEIVER) or role 6 (TIMESTAMPED_RECEIVER) and work without an account.

Packets

Direction	ID	Packet	When
C2S	11	ForwardedClientAddress	Optional, trusted proxies only, before the request.
C2S	1	ReceiverSessionRequest	Once, right after the handshake.
S2C	1	IqStreamDescriptor	Once, when the stream starts.
S2C	2	IqBlock	Continuously (role 1).
S2C	31	TimedIqBlock	Continuously (role 6).
C2S	13	ReceiverRetune	Any time, to change frequency.

Sequence

 client                                            server
   | -- Handshake (role 1, anonymous) -------------> |
   | <------------------------- [30] HandshakeResult |
   | -- [1] ReceiverSessionRequest ----------------> |
   | <------------------------ [1] IqStreamDescriptor|
   | <------------------------------- [2] IqBlock    |
   | <------------------------------- [2] IqBlock    |
   | -- [13] ReceiverRetune -----------------------> |    (optional, any time)
   | <------------------------------- [2] IqBlock    |
   |                  ...                            |

After the request, the only packet a client may send is ReceiverRetune. Sending anything else closes the connection.

Negotiation

The request states what the client would like; the IqStreamDescriptor states what it gets. Always use the values from the descriptor.

Sample rate

• A requested rate up to 2,400,000 samples per second is narrowband. It is clamped to the range 24,000 to 2,400,000.
• A requested rate above 2,400,000 is wideband. The rate becomes the smaller of the request and 32,000,000, and the block size is fixed at 16,384 samples. Wideband capacity is budgeted at 32 million samples per second per client IP address, plus a server-wide budget. A request over budget is refused by closing the connection.

Block size

Each IQ block carries exactly chunkSamples 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, for example, blocks are 1,920 samples long whatever the client asks for.

Bandwidth

The receiver's filter bandwidth is the requested bandwidthHz, limited to at most the larger of 24,000 Hz and the sample rate, and to at least 50 Hz. A non-finite or non-positive request selects the maximum.

Decoding samples

Servers currently always send 16-bit samples (sampleFormat = 1). Each block has a per-block floating-point scale followed by interleaved I and Q integers:

x = q × blockScale / 32767

(or / 127 for the 8-bit format, which a client should support in case a server uses it). The server chooses blockScale as the peak magnitude of the block, so the integers always use the full range and small signals keep their precision.

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 can overload exactly like a real one. To convert a block's mean power to dBm:

P(dBm) = −12 + 10 × log10( mean(I² + Q²) )

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 requested noise figure. It includes everything a real receiver would hear: every transmitter in range with its propagation path, fading and Doppler, 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.

Retuning

A ReceiverRetune moves the centre frequency without reconnecting. There is no acknowledgement and no new descriptor; the rate and block size stay the same. The change takes effect after a settling time of about 120 ms, and only the most recent retune in that time is applied. Expect a short gap or transient in the stream.

To change the sample rate or bandwidth, open a new connection.

Flow control

• The server queues up to 8 blocks per connection. When the queue is full, the oldest block is discarded without notice.
• If the client does not read for 5 seconds, or the queue stays full 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.

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

Timestamped receivers

Role 6 is identical to role 1, except that every block arrives as a TimedIqBlock carrying the UTC instant of its first sample on the server's simulated RF timeline. Two receivers' timestamps are directly comparable, which makes them suitable for time-difference-of-arrival (TDOA) direction finding, aligning several receivers, or measuring end-to-end latency. Role 6 accepts only anonymous connections.

Failure

Receiver sessions report problems by closing the connection without a message. This includes an invalid request (for example a latitude of 91°), a server or per-IP receiver limit, a wideband budget overrun, and a protocol violation. If the socket closes right after the request, check the request values first, then assume a limit and back off before retrying. See SimTX API/Limits and errors.

Checklist

1. Connect with TLS to the host and port from the server directory. Set TCP_NODELAY.
2. Send a Handshake: magic 0x53494D54, version 24, role 1, authKind 0, empty credential.
3. Read u8 30 and a HandshakeResult; require status 0.
4. Send u8 1 and a ReceiverSessionRequest.
5. Read u8 1 and an IqStreamDescriptor.
6. Loop: read u8 2, i32 length, f32 scale and chunkSamples × (i16 I, i16 Q). Scale and use.
7. To retune, send u8 13 and an f32 frequency.

A complete working program is on Quick start.