SimTX API v24/Packets/TransmitterSessionRequest

TransmitterSessionRequest

Frame	{{{frame}}}, field {{{field}}}
Member	{{{member}}}
Direction	Client → server
Session	Transmitter
Roles
Permission	game.transmit (checked at the handshake)
Answered by	TxQueue, TxAccept or TxReject
Answers
Defined in

TransmitterSessionRequest starts a transmitter session. It describes the station, its antenna, the signal (modulation, frequency, power, source and sample rate) and, optionally, the imperfections of the simulated transmitter. The client sends it once, immediately after an accepted HandshakeResult on a connection with role 2 or 3.

Unlike most packets, the body is a TLV field list, so that fields can be added in later revisions without breaking existing clients.

Layout

Field	Type	Description
packetId	u8	Always 2.
fieldCount	u8	Number of fields that follow.
fields	fieldCount × { u8 fieldId, i32 length, u8[length] payload }	Fields in any order. See Fields.

Fields

Numeric payloads are a single big-endian f32 or i32 with length = 4. String payloads (callsign, modulation, source type) are standard UTF-8 without any further length prefix. GeoPoint and AntennaConfig payloads use their usual encoding, with length giving their total size.

The Live column marks fields that can later be changed with TxUpdate.

ID	Field	Payload	Required	Valid range	Default	Live
1	callsign	UTF-8	Yes	1–64 printable characters, ≤ 64 bytes	—
2	location	GeoPoint (24 bytes)	Yes	Valid coordinates	—
3	antenna	AntennaConfig	Yes	See Data types	—
4	modulation	UTF-8	Yes	A Modulation name, ≤ 64 bytes	—
5	frequencyHz	f32	Yes	> 0; values above 3 GHz are reduced to 3 GHz	—	Yes
6	powerWatts	f32	Yes	≥ 0; reduced to at most 1,000,000 and then to the account's tx.pa_limit	—	Yes
7	sourceType	UTF-8	Yes	A TransmissionSourceType name	—
8	sampleRate	i32	Yes	> 0	—
9	audioGain	f32	Yes	≥ 0; values above 100 are reduced to 100	—
10	txBandwidthHz	f32	Yes	> 0; values above 10 MHz are reduced to 10 MHz	—	Yes
11	audioLowCutHz	f32	Yes	≥ 0	—	Yes
12	toneHz	f32	Yes	≥ 0	—
13	dutyCycle	f32	Yes	0–1	—
14	finalDriveDb	f32	No	−40 to 40	0	Yes
15	paHeadroomDb	f32	No	0.1 to 40	12	Yes
16	audioCompressionDb	f32	No	0 to 30	1.5	Yes
17	paSoftness	f32	No	0.5 to 10	2.8
18	paAmPmDeg	f32	No	0 to 45	6
19	carrierLeakDb	f32	No	0 to 120 (dB below carrier)	60
20	oppositeSidebandSuppressionDb	f32	No	0 to 120	60
21	frequencyOffsetHz	f32	No	−10,000 to 10,000	0
22	mainsHumDb	f32	No	0 to 120 (dB down)	120
23	mainsHumHz	f32	No	0 to 400	0
24	amModulationIndex	f32	No	0 to 1.2	0.85
25	paSupplySagDb	f32	No	0 to 30	0
26	txNoiseFloorDb	f32	No	0 to 160	120
27	oscillatorPhaseNoiseDb	f32	No	0 to 160	120
28	cwKeyRiseMs	f32	No	0 to 50	5

Fields 14 to 28 model the transmitter's own imperfections: amplifier compression and AM-to-PM conversion, carrier leakage, unwanted sideband, frequency error, mains hum, supply sag, broadband noise and phase noise. They are rendered in-band, around the carrier; harmonics and far-out spurious emissions are not simulated. Advanced Transmitter Settings explains what each one sounds like. A client that does not care may omit them all.

toneHz and dutyCycle are required for historical reasons. Clients that do not use them send 0 and 1.

Rules

• All 13 required fields must be present, otherwise the connection is closed without a reply.
• Unknown field IDs are skipped. If a field appears twice, the last occurrence wins.
• A single field may not exceed 263,168 bytes, and the field payloads together may not exceed 263,168 bytes.
• Values outside the ranges above, unknown enumeration names and invalid antenna data close the connection without a reply. Values that the table says are reduced are accepted and silently limited.
• For role 3 (TX_GENERATED) the source type must be WHITE_NOISE; any other source closes the connection. On role 2, WHITE_NOISE produces nothing and the session ends after the 15-second input stall timeout.
• Sample rate rules: the server processes the signal at min(10,000,000, max(sampleRate, 240,000 for WFM)). Raw IQ above 10,000,000 samples per second is rejected with a TxReject, as is audio that would need to be resampled by more than 128×.

Example

The minimal request from Quick start, built in Python:

def field(field_id, payload):
    return struct.pack(">Bi", field_id, len(payload)) + payload

def f32(value):
    return struct.pack(">f", value)

antenna = struct.pack(">H", 6) + b"DIPOLE" + struct.pack(">ffffi", 10.0, 0.0, 0.0, 20.0, 0)
fields = [
    field(1, b"N0CALL"),
    field(2, struct.pack(">ddd", 47.4979, 19.0402, 120.0)),
    field(3, antenna),
    field(4, b"USB"),
    field(5, f32(14_230_000.0)),
    field(6, f32(100.0)),
    field(7, b"AUDIO_STREAM"),
    field(8, struct.pack(">i", 48_000)),
    field(9, f32(1.0)),
    field(10, f32(2_700.0)),
    field(11, f32(300.0)),
    field(12, f32(0.0)),
    field(13, f32(1.0)),
]
packet = b"\x02" + struct.pack(">B", len(fields)) + b"".join(fields)

See also

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