Editing SimTX API/Packets/ReceiverStart

{{SimTX API navigation}}
{{SimTX packet
| name = ReceiverStart
| frame = ClientFrame
| field = 10
| member = receiver_start
| direction = c2s
| session = [[SimTX API/Receiver session|Receiver]]
| roles = <code>ROLE_RECEIVER</code>. Once, right after the hello.
| permission = None for an ad-hoc site. A station-bound site needs a <code>receiver</code> ticket for that station.
| reply = [[SimTX API/Packets/SessionStatus|SessionStatus]], then [[SimTX API/Packets/IqStreamDescriptor|IqStreamDescriptor]]
| group = receiver
| file = session.proto
}}
'''ReceiverStart''' starts a [[SimTX API/Receiver session|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 [[SimTX API/Packets/ServerHello|ServerHello]].

== Definition ==
<syntaxhighlight lang="protobuf">
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
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>site</code> || [[SimTX API/Data types#SessionSite|SessionSite]] || Where the receiver is: a [[SimTX API/Data types#StationBinding|StationBinding]] or an [[SimTX API/Data types#AdhocStation|AdhocStation]]. Exactly one member must be set.
|-
| 3 || <code>center_frequency_hz</code> || <code>double</code> || Centre frequency in Hz. Finite and ≥ 0.
|-
| 4 || <code>bandwidth_hz</code> || <code>float</code> || Requested filter bandwidth in Hz. Finite and > 0. Effective value: max(50, min(request, max(24,000, sample rate))).
|-
| 5 || <code>sample_rate</code> || <code>int32</code> || Requested sample rate in complex samples per second, > 0. See [[SimTX API/Receiver session#Negotiation|Negotiation]].
|-
| 6 || <code>chunk_samples</code> || <code>int32</code> || Requested complex samples per [[SimTX API/Packets/IqBlock|IqBlock]], > 0. The server decides; see [[SimTX API/Receiver session#Negotiation|Negotiation]].
|-
| 7 || <code>noise_figure_db</code> || <code>optional float</code> || 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 || <code>timestamped</code> || <code>bool</code> || True: every [[SimTX API/Packets/IqBlock|IqBlock]] carries the UTC instant of its first sample. Works with or without an account.
|-
| 9 || <code>solo_transmitter_id</code> || <code>string</code> || Moderator feature. Leave empty. A non-empty value needs <code>monitor.any</code>.
|-
| 10 || <code>tracking</code> || [[SimTX API/Data types#Tracking|Tracking]] || Track a target from the start. See [[SimTX API/Tracking and pointing|Tracking and pointing]].
|-
| 11 || <code>sample_format</code> || [[SimTX API/Data types#SampleFormat|SampleFormat]] || <code>SAMPLE_FORMAT_INT16</code> (0, default) or <code>SAMPLE_FORMAT_INT8</code> (1).
|-
| 12 || <code>aim</code> || [[SimTX API/Data types#AntennaAim|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 [[SimTX API/Tracking and pointing#Start pointing|Start pointing]].
|}

Field number 2 is reserved; do not use it.

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

{| class="wikitable"
! 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 <code>argon.simtx.net</code>, 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 [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>REJECTED</code>, a [[SimTX API/Data types#ErrorCode|ErrorCode]] and a reason, and the connection closes:
* <code>INVALID_REQUEST</code>: 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 <code>aim</code> with a non-finite angle or an elevation outside ±90°.
* <code>FORBIDDEN</code>: 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.
* <code>STATION_INACTIVE</code>: the station was deleted, or the satellite has reentered.
* <code>LIMIT_REACHED</code>: server, per-address, account or station receiver limits, or the wideband budget.

== Examples ==
Complete frames, including the varint length prefix.

'''<code>receiver_start_adhoc</code>''' (client to server, 100 bytes):

<syntaxhighlight lang="text">
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
</syntaxhighlight>

'''<code>receiver_start_station_timestamped</code>''' (client to server, 88 bytes):

<syntaxhighlight lang="text">
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
</syntaxhighlight>

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

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