SimTX API/Packets/TransmitterStart

TransmitterStart

Frame	ClientFrame, field 12
Member	transmitter_start
Direction	Client → server
Session	Transmitter
Roles	ROLE_TX_AUDIO, ROLE_TX_GENERATED. Once, right after the hello.
Permission	game.transmit (checked at the hello), a ticket for the station
Answered by	SessionStatus, then TxQueue and TxAccept
Answers
Defined in	session.proto

TransmitterStart starts a 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 ServerHello.

Definition

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
}

Fields

#	Field	Type	Description
1	site	SessionSite	Where the transmitter is: a StationBinding (normal) or an AdhocStation (only with tx.adhoc or when the server policy allows it). Exactly one member must be set.
3	modulation	string	Modulation name, for example USB.
4	frequency_hz	double	Carrier or dial frequency in Hz, finite and > 0. Values above 3 GHz are reduced to 3 GHz.
5	power_watts	float	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 tx.pa_limit).
6	source_type	string	Source type name, for example AUDIO_STREAM.
7	sample_rate	int32	Rate of the samples the client will send, > 0.
8	audio_gain	float	Gain applied to the client's samples, finite and ≥ 0. Values above 100 are reduced to 100.
9	bandwidth_hz	float	Transmitted bandwidth in Hz, finite and > 0. Values above 10 MHz are reduced to 10 MHz.
10	audio_low_cut_hz	float	Audio high-pass corner in Hz, finite and ≥ 0.
11	tone_hz	float	Tone frequency for CW and tone sources, Hz, ≥ 0. Send 0 when unused.
12	duty_cycle	float	Duty cycle of generated sources, 0 to 1. Send 1 when unused.
13	imperfections	TxImperfections	Transmitter imperfection knobs. Unset knobs take the rig's value, or the generic HF preset without a rig. With a rig, only final_drive_db, audio_compression_db, frequency_offset_hz and am_modulation_index are taken from here.
14	tracking	Tracking	Track a target from the start. See Tracking and pointing.
15	aim	AntennaAim	Where the antenna points when the session starts. Unset: the antenna's stored heading. See Start pointing.

Field number 2 is reserved; do not use it.

Station-bound and ad-hoc

• With site.station, the station dictates the callsign, placement, antenna and, through the bound rig, the PA cap and most imperfection knobs. See What the station dictates.
• With site.adhoc, the start is accepted only for principals holding tx.adhoc (service integrations) or when the server's ad-hoc policy allows it. Otherwise it is refused with ERROR_CODE_STATION_REQUIRED.

Rules

• For ROLE_TX_GENERATED the source type must be WHITE_NOISE.
• The RF processing rate is min(10,000,000, sample_rate), at least 240,000 for WFM. 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 Modulation or Source type names and invalid antenna data are refused with SessionStatus REJECTED INVALID_REQUEST. Values the table says are reduced are accepted and limited.
• The knobs in imperfections 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

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

Examples

Complete frames, including the varint length prefix.

transmitter_start_station_tracking (client to server, 156 bytes):

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

transmitter_start_adhoc_service (client to server, 206 bytes):

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

See also

• SimTX API/Transmitter session
• SimTX API/Stations
• Advanced Transmitter Settings
• Modulation Modes