Editing SimTX API v24/Packets/ReceiverSessionRequest

{{SimTX API v24 navigation}}
{{SimTX packet v24
| name = ReceiverSessionRequest
| id = 1
| hex = 0x01
| direction = c2s
| session = [[SimTX API v24/Receiver session|Receiver]]
| size = Variable, at least 70 bytes
| permission = None
| reply = [[SimTX API v24/Packets/IqStreamDescriptor|IqStreamDescriptor]]
| group = receiver
}}
'''ReceiverSessionRequest''' starts a [[SimTX API v24/Receiver session|receiver session]]. It describes the receiving station (callsign, position and antenna), the receiver's noise figure, and the frequency, bandwidth, sample rate and block size the client would like. The client sends it once, immediately after an accepted [[SimTX API v24/Packets/HandshakeResult|HandshakeResult]] on a connection with role 1 or 6.

== Layout ==
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>packetId</code> || <code>u8</code> || Always <code>1</code>.
|-
| <code>callsign</code> || <code>UTF</code> || Station name shown in station lists. 1–64 characters, no control characters.
|-
| <code>location</code> || [[SimTX API v24/Data types#GeoPoint|GeoPoint]] || Receiver position.
|-
| <code>antenna</code> || [[SimTX API v24/Data types#AntennaConfig|AntennaConfig]] || Receiving antenna. A NEC deck may be supplied.
|-
| <code>noiseFigureDb</code> || <code>f32</code> || Receiver front-end noise figure in dB, ≥ 0. Real HF receivers are typically 3–8 dB; HF reception is usually limited by external noise anyway.
|-
| <code>centerFreqHz</code> || <code>f32</code> || Centre frequency in hertz, ≥ 0.
|-
| <code>bandwidthHz</code> || <code>f32</code> || Requested filter bandwidth in hertz.
|-
| <code>sampleRate</code> || <code>i32</code> || Requested sample rate in complex samples per second, > 0.
|-
| <code>chunkSamples</code> || <code>i32</code> || Requested complex samples per block, > 0.
|-
| <code>soloTransmitterUuid</code> || <code>UTF</code> || Must be empty. A non-empty value isolates one transmitter and requires the <code>monitor.any</code> permission; without it the connection is closed.
|}

== Negotiation ==
The server adjusts the request and reports the result in [[SimTX API v24/Packets/IqStreamDescriptor|IqStreamDescriptor]]:

{| class="wikitable"
! Value !! Rule
|-
| Sample rate || Requests up to 2,400,000 are clamped to 24,000–2,400,000 (narrowband). Requests above are wideband: min(request, 32,000,000).
|-
| Block size || Narrowband: clamped to 1,024 … min(1,200,000, rate × ''T''), where ''T'' is 40 ms on the public clustered servers and 0.5 s on a stand-alone server. Wideband: always 16,384.
|-
| Bandwidth || max(50, min(request, max(24,000, rate))). A non-finite or non-positive request selects the maximum.
|}

== Validation ==
Invalid values close the connection '''without a message'''. Typical mistakes are a latitude outside ±90°, a longitude outside ±180°, a negative noise figure or frequency, a non-finite float, an empty callsign, and an unknown antenna type. Server and per-IP receiver limits, and the wideband budget, are also enforced by closing the connection.

== Example ==
A receiver called <code>N0CALL</code> in Budapest at 120 m, with a 10 m high dipole, 5 dB noise figure, tuned to 7.1 MHz at 48 kS/s:

<syntaxhighlight lang="text">
01                                packetId 1
00 06 4E 30 43 41 4C 4C           callsign "N0CALL"
40 47 BF BB 2F EC 56 D6           latitudeDeg   47.4979
40 33 0A 4A 8C 15 4C 98           longitudeDeg  19.0402
40 5E 00 00 00 00 00 00           altitudeMeters 120.0
00 06 44 49 50 4F 4C 45           antenna type "DIPOLE"
41 20 00 00 00 00 00 00           heightMeters 10.0, azimuthDeg 0.0
00 00 00 00 00 00 00 00           feedlineLossDb 0.0, wireLengthMeters 0.0
00 00 00 00                       necDeckLength 0
40 A0 00 00                       noiseFigureDb 5.0
4A D8 AC C0                       centerFreqHz  7100000.0
47 3B 80 00                       bandwidthHz   48000.0
00 00 BB 80                       sampleRate    48000
00 00 07 80                       chunkSamples  1920
00 00                             soloTransmitterUuid ""
</syntaxhighlight>

== See also ==
* [[SimTX API v24/Receiver session]]
* [[SimTX API v24/Quick start]]

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