SimTX API/Packets/ReceiverStart
| Frame | ClientFrame, field 10
|
|---|---|
| Member | receiver_start
|
| Direction | Client → server |
| Session | Receiver |
| Roles | ROLE_RECEIVER. Once, right after the hello.
|
| Permission | None for an ad-hoc site. A station-bound site needs a receiver ticket for that station.
|
| Answered by | SessionStatus, then IqStreamDescriptor |
| Defined in | session.proto
|
ReceiverStart starts a receiver session. It places the receiver, either at one of the account's persistent stations or at an inline ad-hoc site, and states the frequency, bandwidth, sample rate, block size and sample format the client would like. The client sends it once, immediately after an accepted ServerHello.
Definition
message ReceiverStart {
reserved 2;
reserved "station", "adhoc";
SessionSite site = 1;
double center_frequency_hz = 3;
float bandwidth_hz = 4;
int32 sample_rate = 5;
int32 chunk_samples = 6;
optional float noise_figure_db = 7; // default: rig value, else 6 dB
bool timestamped = 8; // IqBlocks carry first-sample timestamps
string solo_transmitter_id = 9; // moderator monitor feature
Tracking tracking = 10;
SampleFormat sample_format = 11;
AntennaAim aim = 12; // start pointing; absent = the antenna's stored heading
}
Fields
| # | Field | Type | Description |
|---|---|---|---|
| 1 | site |
SessionSite | Where the receiver is: a StationBinding or an AdhocStation. Exactly one member must be set. |
| 3 | center_frequency_hz |
double |
Centre frequency in Hz. Finite and ≥ 0. |
| 4 | bandwidth_hz |
float |
Requested filter bandwidth in Hz. Finite and > 0. Effective value: max(50, min(request, max(24,000, sample rate))). |
| 5 | sample_rate |
int32 |
Requested sample rate in complex samples per second, > 0. See Negotiation. |
| 6 | chunk_samples |
int32 |
Requested complex samples per IqBlock, > 0. The server decides; see Negotiation. |
| 7 | noise_figure_db |
optional float |
Receiver noise figure in dB, finite and ≥ 0. Unset: the bound rig's noise figure, otherwise 6 dB. 3 to 8 dB is typical. |
| 8 | timestamped |
bool |
True: every IqBlock carries the UTC instant of its first sample. Works with or without an account. |
| 9 | solo_transmitter_id |
string |
Moderator feature. Leave empty. A non-empty value needs monitor.any.
|
| 10 | tracking |
Tracking | Track a target from the start. See Tracking and pointing. |
| 11 | sample_format |
SampleFormat | SAMPLE_FORMAT_INT16 (0, default) or SAMPLE_FORMAT_INT8 (1).
|
| 12 | aim |
AntennaAim | Where the antenna points when the session starts, for example to reconnect already pointed at a manual heading. Unset: the antenna's stored heading. See Start pointing. |
Reserved, never reused: field number 2 and the names station, adhoc.
Negotiation
The server adjusts the request and reports the result in IqStreamDescriptor:
| Value | Rule |
|---|---|
| Sample rate | Requests up to 2,400,000 are narrowband and clamped to 24,000 to 2,400,000. Requests above are wideband: min(request, 32,000,000). |
| Block size | Narrowband: clamped to 1,024 to min(1,200,000, rate × T), where T is 40 ms on the public clustered deployment and 0.5 s on a stand-alone server. Wideband: always 16,384. |
| Bandwidth | max(50, min(request, max(24,000, rate))). |
Validation
A start that cannot be accepted is answered with SessionStatus REJECTED, a ErrorCode and a reason, and the connection closes:
INVALID_REQUEST: no site, a latitude outside ±90°, a longitude outside ±180°, a negative or non-finite frequency or noise figure, a non-positive bandwidth, sample rate or block size, an empty callsign, an unknown antenna type, an invalid NEC deck, or anaimwith a non-finite angle or an elevation outside ±90°.FORBIDDEN: a station-bound start without a ticket for that station, a binding that does not match the ticket, or a ticket bound to a station used with an ad-hoc site.STATION_INACTIVE: the station was deleted, or the satellite has reentered.LIMIT_REACHED: server, per-address, account or station receiver limits, or the wideband budget.
Examples
Complete frames, including the varint length prefix, from the protocol's golden test vectors (protocol/simtx/v25/testdata/frames.json).
receiver_start_adhoc (client to server, 100 bytes):
63 frame length 99
52 61 receiver_start (ReceiverStart), 97 bytes
0A 45 site (SessionSite), 69 bytes
12 43 adhoc (AdhocStation), 67 bytes
0A 06 4E 30 43 41 4C 4C callsign = "N0CALL"
12 1B location (GeoPoint), 27 bytes
09 00 00 00 00 00 C0 47 40 latitude_deg = 47.5
11 00 00 00 00 00 00 33 40 longitude_deg = 19.0
19 00 00 00 00 00 00 5E 40 altitude_meters = 120.0
1A 1C antenna (AntennaConfig), 28 bytes
0A 06 44 49 50 4F 4C 45 type = "DIPOLE"
15 00 00 20 41 height_meters = 10
1D 00 00 34 42 azimuth_deg = 45
25 00 00 80 3F feedline_loss_db = 1
2D 9A 99 21 41 wire_length_meters = 10.1
19 00 00 00 00 34 FC 5A 41 center_frequency_hz = 7074000.0
25 00 80 3B 46 bandwidth_hz = 12000
28 80 F7 02 sample_rate = 48000
30 80 20 chunk_samples = 4096
3D 00 00 D0 40 noise_figure_db = 6.5
receiver_start_station_timestamped (client to server, 88 bytes):
57 frame length 87
52 55 receiver_start (ReceiverStart), 85 bytes
0A 26 site (SessionSite), 38 bytes
0A 24 station (StationBinding), 36 bytes
0A 10 11 11 11 11 … station_id = 11111111-2222-4333-8444-555555555555
12 10 11 11 11 11 … antenna_id = 11111111-2222-4333-8444-666666666666
19 00 00 00 08 12 D8 6A 41 center_frequency_hz = 14074000.25
25 00 80 BB 46 bandwidth_hz = 24000
28 80 EE 05 sample_rate = 96000
30 80 40 chunk_samples = 8192
40 01 timestamped = true
52 14 tracking (Tracking), 20 bytes
0A 10 99 99 99 99 … target_station_id = 99999999-8888-4777-8666-555555555555
18 01 doppler_correct = true