SimTX API/Packets/ReceiverStart

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
Answers
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;
  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.

Field number 2 is reserved; do not use it.

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 a server setting: 40 ms on argon.simtx.net, 0.5 s by default. 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 an aim with 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.

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

See also

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