SimTX API v24/Packets/ReceiverSessionRequest

ReceiverSessionRequest

Packet ID	1(0x01)
Direction	Client → server
Session	Receiver
Body size	Variable, at least 70 bytes
Permission	None
Answered by	IqStreamDescriptor
Answers

ReceiverSessionRequest starts a 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 HandshakeResult on a connection with role 1 or 6.

Layout

Field	Type	Description
packetId	u8	Always 1.
callsign	UTF	Station name shown in station lists. 1–64 characters, no control characters.
location	GeoPoint	Receiver position.
antenna	AntennaConfig	Receiving antenna. A NEC deck may be supplied.
noiseFigureDb	f32	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.
centerFreqHz	f32	Centre frequency in hertz, ≥ 0.
bandwidthHz	f32	Requested filter bandwidth in hertz.
sampleRate	i32	Requested sample rate in complex samples per second, > 0.
chunkSamples	i32	Requested complex samples per block, > 0.
soloTransmitterUuid	UTF	Must be empty. A non-empty value isolates one transmitter and requires the monitor.any permission; without it the connection is closed.

Negotiation

The server adjusts the request and reports the result in IqStreamDescriptor:

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 N0CALL in Budapest at 120 m, with a 10 m high dipole, 5 dB noise figure, tuned to 7.1 MHz at 48 kS/s:

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 ""

See also

• SimTX API v24/Receiver session
• SimTX API v24/Quick start