Editing SimTX API/Receiver session

{{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. 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 ==
{| class="wikitable"
! Direction !! # !! Message !! When
|-
| C2S || 3 || [[SimTX API/Packets/ForwardedClientAddress|ForwardedClientAddress]] || Optional, trusted proxies only, before the start.
|-
| C2S || 10 || [[SimTX API/Packets/ReceiverStart|ReceiverStart]] || Once, right after the hello.
|-
| S2C || 10 || [[SimTX API/Packets/SessionStatus|SessionStatus]] || <code>BOUND</code> or <code>REJECTED</code> after the start; later <code>UPDATED</code> and <code>ENDED</code>.
|-
| S2C || 11 || [[SimTX API/Packets/IqStreamDescriptor|IqStreamDescriptor]] || Once, after <code>BOUND</code>.
|-
| S2C || 12 || [[SimTX API/Packets/IqBlock|IqBlock]] || Continuously.
|-
| C2S || 11 || [[SimTX API/Packets/ReceiverRetune|ReceiverRetune]] || Any time, to change frequency.
|-
| C2S || 16 || [[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]] || Station-bound sessions, to steer the antenna.
|-
| C2S / S2C || 2 || [[SimTX API/Packets/Ping|Ping]] / [[SimTX API/Packets/Pong|Pong]] || Any time.
|-
| S2C || 3 || [[SimTX API/Packets/Error|Error]] || When a retune or pointing request fails, or on a protocol violation.
|}

== Sequence ==
<syntaxhighlight lang="text">
 client                                                  server
   | -- preface, [1] hello (ROLE_RECEIVER) --------------> |
   | <---------------------------- [1] hello_result       |
   | -- [10] receiver_start -----------------------------> |
   | <---------------------------- [10] session_status    |   BOUND
   | <---------------------------- [11] iq_descriptor     |
   | <---------------------------- [12] iq                |   sequence 1
   | <---------------------------- [12] iq                |   sequence 2
   | -- [11] receiver_retune (request_id 7) -------------> |   (optional, any time)
   | <---------------------------- [12] iq                |
   | <---------------------------- [10] session_status    |   UPDATED, RETUNE, request_id 7
   | <---------------------------- [12] iq                |
   |                    ...                               |
</syntaxhighlight>

After the start, a client may send only [[SimTX API/Packets/ReceiverRetune|ReceiverRetune]], [[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]] and [[SimTX API/Packets/Ping|Ping]]. Any other frame is answered with [[SimTX API/Packets/Error|Error]] <code>INVALID_REQUEST</code> and the connection closes.

== Placing the receiver ==
<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.
* '''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]].

A receiver on a satellite hears the uplink: the signals that reach the satellite's antenna in orbit.

== Negotiation ==
The start states what the client would like; the [[SimTX API/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 address, plus a server-wide budget. A start over budget is refused with <code>LIMIT_REACHED</code>.

=== 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 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 ===
The receiver's filter bandwidth is the requested <code>bandwidth_hz</code>, limited to at most the larger of 24,000 Hz and the sample rate, and to at least 50 Hz.

=== Sample format ===
<code>sample_format</code> selects 16-bit (<code>SAMPLE_FORMAT_INT16</code>, 0, the default) or 8-bit (<code>SAMPLE_FORMAT_INT8</code>, 1) samples. The descriptor confirms the format.

=== 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. Typical values are 3 to 8 dB.

== Decoding samples ==
Each [[SimTX API/Packets/IqBlock|IqBlock]] has a per-block floating-point <code>scale</code> and a <code>samples</code> payload of interleaved I and Q integers, '''big-endian''':

<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. 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 strong signal overloads the receiver. 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 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 ==
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 ==
<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 ==
A [[SimTX API/Packets/ReceiverRetune|ReceiverRetune]] moves the centre frequency without reconnecting. The rate, block size, bandwidth and sample format stay the same, and no new descriptor is sent. The change takes effect after a settling time of about 120 ms; retunes received during that time are coalesced and only the latest is applied. Expect a short gap or transient.

With a nonzero <code>request_id</code>, the server confirms the retune with [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>UPDATED</code>, <code>update_reason = UPDATE_REASON_RETUNE</code>, the same <code>request_id</code> and the new <code>frequency_hz</code>, once the stream runs on the new frequency. A retune superseded by a later one before it took effect gets no confirmation of its own.

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

== Tracking and pointing ==
A station-bound receiver can follow a target, usually a satellite, from the start (<code>ReceiverStart.tracking</code>) or later ([[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]]). With <code>doppler_correct</code>, the receiver's tuning is shifted by the target's Doppler, so a satellite's signal stays at the same offset in the passband during a pass. See [[SimTX API/Tracking and pointing]].

== Flow control ==
* 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.
* Read the socket on a dedicated thread and hand blocks to processing through a queue of your own.

== Failure ==
A start that cannot be accepted is answered with [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>REJECTED</code>, an error code and a reason: invalid values (<code>INVALID_REQUEST</code>), a binding that does not match the ticket (<code>FORBIDDEN</code>), a deleted station or a reentered satellite (<code>STATION_INACTIVE</code>), or a server, per-address, account or station limit or the wideband budget (<code>LIMIT_REACHED</code>). A running session that the server stops gets <code>ENDED</code>. See [[SimTX API/Session status]] and [[SimTX API/Limits and errors]].

== Checklist ==
# Connect with TLS to the host and port from the [[SimTX API/Server directory|server directory]]. Set <code>TCP_NODELAY</code>.
# Send the preface <code>53 49 4D 54 00 00 00 19</code> and a <code>hello</code> frame: <code>role = ROLE_RECEIVER</code>; for a station-bound receiver also <code>auth = AUTH_KIND_GAME_TICKET</code> and the ticket.
# Read the <code>hello_result</code>; require <code>HELLO_STATUS_ACCEPTED</code>.
# Send <code>receiver_start</code> with a site, the centre frequency, bandwidth, sample rate and block size.
# Read <code>session_status</code>; stop on <code>REJECTED</code> and show its code and reason. Then read <code>iq_descriptor</code>.
# Loop on <code>iq</code>: decode <code>samples</code> (big-endian integer pairs) with <code>scale</code>, check <code>sequence</code> for gaps, and skip frames you do not handle.
# To retune, send <code>receiver_retune</code>.

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

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