Editing SimTX API/Packets/TransmitterStart

{{SimTX API navigation}}
{{SimTX packet
| name = TransmitterStart
| frame = ClientFrame
| field = 12
| member = transmitter_start
| direction = c2s
| session = [[SimTX API/Transmitter session|Transmitter]]
| roles = <code>ROLE_TX_AUDIO</code>, <code>ROLE_TX_GENERATED</code>. Once, right after the hello.
| permission = <code>game.transmit</code> (checked at the hello), a ticket for the station
| reply = [[SimTX API/Packets/SessionStatus|SessionStatus]], then [[SimTX API/Packets/TxQueue|TxQueue]] and [[SimTX API/Packets/TxAccept|TxAccept]]
| group = transmitter
| file = session.proto
}}
'''TransmitterStart''' starts a [[SimTX API/Transmitter session|transmitter session]]. It places the transmitter, normally at one of the account's own stations, and describes the signal: modulation, frequency, power, source, sample rate, gain, bandwidth and, optionally, the transmitter's imperfections. The client sends it once, immediately after an accepted [[SimTX API/Packets/ServerHello|ServerHello]].

== Definition ==
<syntaxhighlight lang="protobuf">
message TransmitterStart {
  reserved 2;
  SessionSite site = 1;
  string modulation = 3;        // string enum (common.proto)
  double frequency_hz = 4;
  float power_watts = 5;
  string source_type = 6;       // string enum (common.proto)
  int32 sample_rate = 7;
  float audio_gain = 8;
  float bandwidth_hz = 9;
  float audio_low_cut_hz = 10;
  float tone_hz = 11;
  float duty_cycle = 12;
  // Session knobs. With a rig, only final_drive_db, audio_compression_db, frequency_offset_hz and
  // am_modulation_index are taken from here; the rest come from the rig.
  TxImperfections imperfections = 13;
  Tracking tracking = 14;
  AntennaAim aim = 15;          // 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 transmitter is: a [[SimTX API/Data types#StationBinding|StationBinding]] (normal) or an [[SimTX API/Data types#AdhocStation|AdhocStation]] (only with <code>tx.adhoc</code> or when the server policy allows it). Exactly one member must be set.
|-
| 3 || <code>modulation</code> || <code>string</code> || [[SimTX API/Data types#Modulation|Modulation]] name, for example <code>USB</code>.
|-
| 4 || <code>frequency_hz</code> || <code>double</code> || Carrier or dial frequency in Hz, finite and > 0. Values above 3 GHz are reduced to 3 GHz.
|-
| 5 || <code>power_watts</code> || <code>float</code> || Transmitter power in watts, finite and ≥ 0. Reduced to at most 1,000,000 W and then to the PA cap (the bound rig's cap, else the account's <code>tx.pa_limit</code>).
|-
| 6 || <code>source_type</code> || <code>string</code> || [[SimTX API/Data types#Source type|Source type]] name, for example <code>AUDIO_STREAM</code>.
|-
| 7 || <code>sample_rate</code> || <code>int32</code> || Rate of the samples the client will send, > 0.
|-
| 8 || <code>audio_gain</code> || <code>float</code> || Gain applied to the client's samples, finite and ≥ 0. Values above 100 are reduced to 100.
|-
| 9 || <code>bandwidth_hz</code> || <code>float</code> || Transmitted bandwidth in Hz, finite and > 0. Values above 10 MHz are reduced to 10 MHz.
|-
| 10 || <code>audio_low_cut_hz</code> || <code>float</code> || Audio high-pass corner in Hz, finite and ≥ 0.
|-
| 11 || <code>tone_hz</code> || <code>float</code> || Tone frequency for CW and tone sources, Hz, ≥ 0. Send 0 when unused.
|-
| 12 || <code>duty_cycle</code> || <code>float</code> || Duty cycle of generated sources, 0 to 1. Send 1 when unused.
|-
| 13 || <code>imperfections</code> || [[SimTX API/Data types#TxImperfections|TxImperfections]] || Transmitter imperfection knobs. Unset knobs take the rig's value, or the generic HF preset without a rig. With a rig, only <code>final_drive_db</code>, <code>audio_compression_db</code>, <code>frequency_offset_hz</code> and <code>am_modulation_index</code> are taken from here.
|-
| 14 || <code>tracking</code> || [[SimTX API/Data types#Tracking|Tracking]] || Track a target from the start. See [[SimTX API/Tracking and pointing|Tracking and pointing]].
|-
| 15 || <code>aim</code> || [[SimTX API/Data types#AntennaAim|AntennaAim]] || Where the antenna points when the session starts. 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.

== Station-bound and ad-hoc ==
* With <code>site.station</code>, the station dictates the callsign, placement, antenna and, through the bound rig, the PA cap and most imperfection knobs. See [[SimTX API/Stations#What the station dictates|What the station dictates]].
* With <code>site.adhoc</code>, the start is accepted only for principals holding <code>tx.adhoc</code> (service integrations) or when the server's ad-hoc policy allows it. Otherwise it is refused with <code>ERROR_CODE_STATION_REQUIRED</code>.

== Rules ==
* For <code>ROLE_TX_GENERATED</code> the source type must be <code>WHITE_NOISE</code>.
* The RF processing rate is min(10,000,000, <code>sample_rate</code>), at least 240,000 for <code>WFM</code>. Audio is resampled by at most 128×; raw IQ above 10,000,000 samples per second is refused.
* Values outside the ranges in the field table, unknown [[SimTX API/Data types#Modulation|Modulation]] or [[SimTX API/Data types#Source type|Source type]] names and invalid antenna data are refused with [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>REJECTED</code> <code>INVALID_REQUEST</code>. Values the table says are ''reduced'' are accepted and limited.
* The knobs in <code>imperfections</code> are rendered in-band, around the carrier; harmonics and far-out spurious emissions are not simulated. [[Advanced Transmitter Settings]] explains what each one does.

== Imperfections ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>final_drive_db</code> || <code>optional float</code> || Drive level into the final amplifier, dB. −40 to 40; generic default 0.
|-
| 2 || <code>pa_headroom_db</code> || <code>optional float</code> || Amplifier headroom above the nominal output, dB. 0.1 to 40; default 12.
|-
| 3 || <code>audio_compression_db</code> || <code>optional float</code> || Audio compression, dB. 0 to 30; default 1.5.
|-
| 4 || <code>pa_softness</code> || <code>optional float</code> || Softness of the amplifier's saturation curve. 0.5 to 10; default 2.8.
|-
| 5 || <code>pa_am_pm_deg</code> || <code>optional float</code> || AM-to-PM conversion at saturation, degrees. 0 to 45; default 6.
|-
| 6 || <code>carrier_leak_db</code> || <code>optional float</code> || Carrier suppression, dB below the carrier. 0 to 120; default 60.
|-
| 7 || <code>opposite_sideband_suppression_db</code> || <code>optional float</code> || Suppression of the unwanted sideband, dB. 0 to 120; default 60.
|-
| 8 || <code>frequency_offset_hz</code> || <code>optional float</code> || Frequency error, Hz; the RF frequency is <code>frequency_hz</code> + offset. −10,000 to 10,000; default 0.
|-
| 9 || <code>mains_hum_db</code> || <code>optional float</code> || Mains hum level, dB down. 0 to 120; default 120.
|-
| 10 || <code>mains_hum_hz</code> || <code>optional float</code> || Mains hum frequency, Hz. 0 to 400; default 0.
|-
| 11 || <code>am_modulation_index</code> || <code>optional float</code> || AM modulation index. 0 to 1.2; default 0.85.
|-
| 12 || <code>pa_supply_sag_db</code> || <code>optional float</code> || Supply sag under load, dB. 0 to 30; default 0.
|-
| 13 || <code>tx_noise_floor_db</code> || <code>optional float</code> || Broadband transmitter noise, dB down. 0 to 160; default 120.
|-
| 14 || <code>oscillator_phase_noise_db</code> || <code>optional float</code> || Oscillator phase noise, dB down. 0 to 160; default 120.
|-
| 15 || <code>cw_key_rise_ms</code> || <code>optional float</code> || CW keying rise time, ms. 0 to 50; default 5.
|}

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

'''<code>transmitter_start_station_tracking</code>''' (client to server, 156 bytes):

<syntaxhighlight lang="text">
9A 01                                        frame length 154
62 97 01                                     transmitter_start (TransmitterStart), 151 bytes
  0A 38                                      site (SessionSite), 56 bytes
    0A 36                                    station (StationBinding), 54 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
      1A 10 11 11 11 11 …                    rig_id = 11111111-2222-4333-8444-777777777777
  1A 03 55 53 42                             modulation = "USB"
  21 00 00 00 81 76 61 A1 41                 frequency_hz = 145800000.5
  2D 00 00 C8 41                             power_watts = 25
  32 0C 41 55 44 49 4F 5F 53 54 52 45 41 4D  source_type = "AUDIO_STREAM"
  38 80 F7 02                                sample_rate = 48000
  45 00 00 80 3F                             audio_gain = 1
  4D 00 C0 28 45                             bandwidth_hz = 2700
  55 00 00 96 43                             audio_low_cut_hz = 300
  65 00 00 80 3F                             duty_cycle = 1
  6A 0A                                      imperfections (TxImperfections), 10 bytes
    0D 00 00 40 C0                           final_drive_db = -3
    1D 00 00 C0 40                           audio_compression_db = 6
  72 16                                      tracking (Tracking), 22 bytes
    0A 10 99 99 99 99 …                      target_station_id = 99999999-8888-4777-8666-555555555555
    10 01                                    point_antenna = true
    18 01                                    doppler_correct = true
</syntaxhighlight>

'''<code>transmitter_start_adhoc_service</code>''' (client to server, 206 bytes):

<syntaxhighlight lang="text">
CC 01                                     frame length 204
62 C9 01                                  transmitter_start (TransmitterStart), 201 bytes
  0A 44                                   site (SessionSite), 68 bytes
    12 42                                 adhoc (AdhocStation), 66 bytes
      0A 05 53 43 43 2D 31                callsign = "SCC-1"
      12 1B                               location (GeoPoint), 27 bytes
        09 00 00 00 00 00 C0 49 40        latitude_deg = 51.5
        11 B8 1E 85 EB 51 B8 BE BF        longitude_deg = -0.12
        19 00 00 00 00 00 00 3E 40        altitude_meters = 30.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
  1A 02 43 57                             modulation = "CW"
  21 00 00 00 00 D0 12 63 41              frequency_hz = 10000000.0
  2D 00 00 A0 40                          power_watts = 5
  32 0B 57 48 49 54 45 5F 4E 4F 49 53 45  source_type = "WHITE_NOISE"
  38 C0 3E                                sample_rate = 8000
  45 00 00 80 3F                          audio_gain = 1
  4D 00 00 FA 43                          bandwidth_hz = 500
  5D 00 00 2F 44                          tone_hz = 700
  65 00 00 00 3F                          duty_cycle = 0.5
  6A 4B                                   imperfections (TxImperfections), 75 bytes
    0D 00 00 00 00                        final_drive_db = 0
    15 00 00 40 41                        pa_headroom_db = 12
    1D 00 00 C0 3F                        audio_compression_db = 1.5
    25 33 33 33 40                        pa_softness = 2.8
    2D 00 00 C0 40                        pa_am_pm_deg = 6
    35 00 00 70 42                        carrier_leak_db = 60
    3D 00 00 70 42                        opposite_sideband_suppression_db = 60
    45 00 00 00 00                        frequency_offset_hz = 0
    4D 00 00 F0 42                        mains_hum_db = 120
    55 00 00 00 00                        mains_hum_hz = 0
    5D 9A 99 59 3F                        am_modulation_index = 0.85
    65 00 00 00 00                        pa_supply_sag_db = 0
    6D 00 00 F0 42                        tx_noise_floor_db = 120
    75 00 00 F0 42                        oscillator_phase_noise_db = 120
    7D 00 00 A0 40                        cw_key_rise_ms = 5
</syntaxhighlight>

== See also ==
* [[SimTX API/Transmitter session]]
* [[SimTX API/Stations]]
* [[Advanced Transmitter Settings]]
* [[Modulation Modes]]

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