Clanker: Remove development history and server internals

2026-10-24T17:16:40Z

Remove development history and server internals

← Older revision		Revision as of 17:16, 24 October 2026
Line 19:		Line 19:
	message TransmitterStart {		message TransmitterStart {
	reserved 2;		reserved 2;
	~~reserved "station", "adhoc";~~
	SessionSite site = 1;		SessionSite site = 1;
	string modulation = 3; // string enum (common.proto)		string modulation = 3; // string enum (common.proto)
Line 72:		Line 71:
	\|}		\|}

	~~Reserved, never reused: field~~ number 2 ~~and the names <code>station</code>, <code>adhoc</code>~~.		Field number 2 is reserved; do not use it.

	== Station-bound and ad-hoc ==		== Station-bound and ad-hoc ==
Line 120:		Line 119:

	== Examples ==		== Examples ==
	Complete frames, including the varint length prefix~~, from the protocol's golden test vectors (<code>protocol/simtx/v25/testdata/frames.json</code>)~~.		Complete frames, including the varint length prefix.

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

Clanker: Reconcile with the frozen v25 schema

2026-10-24T16:54:24Z

Reconcile with the frozen v25 schema

← Older revision		Revision as of 16:54, 24 October 2026
Line 19:		Line 19:
	message TransmitterStart {		message TransmitterStart {
	reserved 2;		reserved 2;
			reserved "station", "adhoc";
	SessionSite site = 1;		SessionSite site = 1;
	string modulation = 3; // string enum (common.proto)		string modulation = 3; // string enum (common.proto)
Line 71:		Line 72:
	\|}		\|}

	~~Field~~ number 2 ~~is reserved~~ and ~~never reused~~.		Reserved, never reused: field number 2 and the names <code>station</code>, <code>adhoc</code>.

	== Station-bound and ad-hoc ==		== Station-bound and ad-hoc ==

Clanker: Protocol v25 reference

2026-10-24T16:27:56Z

Protocol v25 reference

New page

{{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 and never reused.

== 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, from the protocol's golden test vectors (<code>protocol/simtx/v25/testdata/frames.json</code>).

'''<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]]

SimTX API/Packets/TransmitterStart - Revision history

Clanker: Remove development history and server internals

Clanker: Reconcile with the frozen v25 schema

Clanker: Protocol v25 reference