Editing SimTX API v24/Receiver session

{{SimTX API v24 navigation}}
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 (<code>RECEIVER</code>) or role 6 (<code>TIMESTAMPED_RECEIVER</code>) and work without an account.

== Packets ==
{| class="wikitable"
! Direction !! ID !! Packet !! When
|-
| C2S || 11 || [[SimTX API v24/Packets/ForwardedClientAddress|ForwardedClientAddress]] || Optional, trusted proxies only, before the request.
|-
| C2S || 1 || [[SimTX API v24/Packets/ReceiverSessionRequest|ReceiverSessionRequest]] || Once, right after the handshake.
|-
| S2C || 1 || [[SimTX API v24/Packets/IqStreamDescriptor|IqStreamDescriptor]] || Once, when the stream starts.
|-
| S2C || 2 || [[SimTX API v24/Packets/IqBlock|IqBlock]] || Continuously (role 1).
|-
| S2C || 31 || [[SimTX API v24/Packets/TimedIqBlock|TimedIqBlock]] || Continuously (role 6).
|-
| C2S || 13 || [[SimTX API v24/Packets/ReceiverRetune|ReceiverRetune]] || Any time, to change frequency.
|}

== Sequence ==
<syntaxhighlight lang="text">
 client                                            server
   | -- Handshake (role 1, anonymous) -------------> |
   | <------------------------- [30] HandshakeResult |
   | -- [1] ReceiverSessionRequest ----------------> |
   | <------------------------ [1] IqStreamDescriptor|
   | <------------------------------- [2] IqBlock    |
   | <------------------------------- [2] IqBlock    |
   | -- [13] ReceiverRetune -----------------------> |    (optional, any time)
   | <------------------------------- [2] IqBlock    |
   |                  ...                            |
</syntaxhighlight>

After the request, the only packet a client may send is [[SimTX API v24/Packets/ReceiverRetune|ReceiverRetune]]. Sending anything else closes the connection.

== Negotiation ==
The request states what the client would like; the [[SimTX API v24/Packets/IqStreamDescriptor|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 <code>chunkSamples</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, for example, blocks are 1,920 samples long whatever the client asks for.

=== Bandwidth ===
The receiver's filter bandwidth is the requested <code>bandwidthHz</code>, 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 (<code>sampleFormat = 1</code>). Each block has a per-block floating-point scale followed by interleaved I and Q integers:

<code>x = q × blockScale / 32767</code>

(or <code>/ 127</code> for the 8-bit format, which a client should support in case a server uses it). The server chooses <code>blockScale</code> 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:

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

=== 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 [[SimTX API v24/Packets/ReceiverRetune|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 [[SimTX API v24/Packets/TimedIqBlock|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 v24/Limits and errors]].

== Checklist ==
# Connect with TLS to the host and port from the [[SimTX API v24/Server directory|server directory]]. Set <code>TCP_NODELAY</code>.
# Send a [[SimTX API v24/Packets/Handshake|Handshake]]: magic <code>0x53494D54</code>, version 24, role 1, authKind 0, empty credential.
# Read <code>u8</code> 30 and a [[SimTX API v24/Packets/HandshakeResult|HandshakeResult]]; require status 0.
# Send <code>u8</code> 1 and a [[SimTX API v24/Packets/ReceiverSessionRequest|ReceiverSessionRequest]].
# Read <code>u8</code> 1 and an [[SimTX API v24/Packets/IqStreamDescriptor|IqStreamDescriptor]].
# Loop: read <code>u8</code> 2, <code>i32</code> length, <code>f32</code> scale and <code>chunkSamples</code> × (<code>i16</code> I, <code>i16</code> Q). Scale and use.
# To retune, send <code>u8</code> 13 and an <code>f32</code> frequency.

A complete working program is on [[SimTX API v24/Quick start|Quick start]].

{{SimTX API v24 navbox}}
[[Category:SimTX API v24]]
[[Category:SimTX API v24 sessions]]