SimTX API v24/Packets/TransmitterSessionRequest - Revision history

Clanker: Archive the v24 protocol reference: use the v24 templates, links and categories

2026-10-24T16:18:19Z

Archive the v24 protocol reference: use the v24 templates, links and categories

← Older revision		Revision as of 16:18, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{SimTX API v24 navigation}}
	{{SimTX packet		{{SimTX packet v24
	\| name = TransmitterSessionRequest		\| name = TransmitterSessionRequest
	\| id = 2		\| id = 2
	\| hex = 0x02		\| hex = 0x02
	\| direction = c2s		\| direction = c2s
	\| session = [[SimTX API/Transmitter session\|Transmitter]]		\| session = [[SimTX API v24/Transmitter session\|Transmitter]]
	\| size = Variable, at most 263,168 bytes of field payload		\| size = Variable, at most 263,168 bytes of field payload
	\| permission = <code>game.transmit</code> (checked at the handshake)		\| permission = <code>game.transmit</code> (checked at the handshake)
	\| reply = [[SimTX API/Packets/TxQueue\|TxQueue]], [[SimTX API/Packets/TxAccept\|TxAccept]] or [[SimTX API/Packets/TxReject\|TxReject]]		\| reply = [[SimTX API v24/Packets/TxQueue\|TxQueue]], [[SimTX API v24/Packets/TxAccept\|TxAccept]] or [[SimTX API v24/Packets/TxReject\|TxReject]]
	\| group = transmitter		\| group = transmitter
	}}		}}
	'''TransmitterSessionRequest''' starts a [[SimTX API/Transmitter session\|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 [[SimTX API/Packets/HandshakeResult\|HandshakeResult]] on a connection with role 2 or 3.		'''TransmitterSessionRequest''' starts a [[SimTX API v24/Transmitter session\|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 [[SimTX API v24/Packets/HandshakeResult\|HandshakeResult]] on a connection with role 2 or 3.

	Unlike most packets, the body is a [[SimTX API/Data types#TLV field list\|TLV field list]], so that fields can be added in later revisions without breaking existing clients.		Unlike most packets, the body is a [[SimTX API v24/Data types#TLV field list\|TLV field list]], so that fields can be added in later revisions without breaking existing clients.

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

	The ''Live'' column marks fields that can later be changed with [[SimTX API/Packets/TxUpdate\|TxUpdate]].		The ''Live'' column marks fields that can later be changed with [[SimTX API v24/Packets/TxUpdate\|TxUpdate]].

	{\| class="wikitable sortable"		{\| class="wikitable sortable"
Line 36:		Line 36:
	\| 1 \|\| <code>callsign</code> \|\| UTF-8 \|\| Yes \|\| 1–64 printable characters, ≤ 64 bytes \|\| — \|\|		\| 1 \|\| <code>callsign</code> \|\| UTF-8 \|\| Yes \|\| 1–64 printable characters, ≤ 64 bytes \|\| — \|\|
	\|-		\|-
	\| 2 \|\| <code>location</code> \|\| [[SimTX API/Data types#GeoPoint\|GeoPoint]] (24 bytes) \|\| Yes \|\| Valid coordinates \|\| — \|\|		\| 2 \|\| <code>location</code> \|\| [[SimTX API v24/Data types#GeoPoint\|GeoPoint]] (24 bytes) \|\| Yes \|\| Valid coordinates \|\| — \|\|
	\|-		\|-
	\| 3 \|\| <code>antenna</code> \|\| [[SimTX API/Data types#AntennaConfig\|AntennaConfig]] \|\| Yes \|\| See Data types \|\| — \|\|		\| 3 \|\| <code>antenna</code> \|\| [[SimTX API v24/Data types#AntennaConfig\|AntennaConfig]] \|\| Yes \|\| See Data types \|\| — \|\|
	\|-		\|-
	\| 4 \|\| <code>modulation</code> \|\| UTF-8 \|\| Yes \|\| A [[SimTX API/Data types#Modulation\|Modulation]] name, ≤ 64 bytes \|\| — \|\|		\| 4 \|\| <code>modulation</code> \|\| UTF-8 \|\| Yes \|\| A [[SimTX API v24/Data types#Modulation\|Modulation]] name, ≤ 64 bytes \|\| — \|\|
	\|-		\|-
	\| 5 \|\| <code>frequencyHz</code> \|\| f32 \|\| Yes \|\| > 0; values above 3 GHz are reduced to 3 GHz \|\| — \|\| Yes		\| 5 \|\| <code>frequencyHz</code> \|\| f32 \|\| Yes \|\| > 0; values above 3 GHz are reduced to 3 GHz \|\| — \|\| Yes
Line 46:		Line 46:
	\| 6 \|\| <code>powerWatts</code> \|\| f32 \|\| Yes \|\| ≥ 0; reduced to at most 1,000,000 and then to the account's <code>tx.pa_limit</code> \|\| — \|\| Yes		\| 6 \|\| <code>powerWatts</code> \|\| f32 \|\| Yes \|\| ≥ 0; reduced to at most 1,000,000 and then to the account's <code>tx.pa_limit</code> \|\| — \|\| Yes
	\|-		\|-
	\| 7 \|\| <code>sourceType</code> \|\| UTF-8 \|\| Yes \|\| A [[SimTX API/Data types#TransmissionSourceType\|TransmissionSourceType]] name \|\| — \|\|		\| 7 \|\| <code>sourceType</code> \|\| UTF-8 \|\| Yes \|\| A [[SimTX API v24/Data types#TransmissionSourceType\|TransmissionSourceType]] name \|\| — \|\|
	\|-		\|-
	\| 8 \|\| <code>sampleRate</code> \|\| i32 \|\| Yes \|\| > 0 \|\| — \|\|		\| 8 \|\| <code>sampleRate</code> \|\| i32 \|\| Yes \|\| > 0 \|\| — \|\|
Line 101:		Line 101:
	* 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.		* 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 (<code>TX_GENERATED</code>) the source type must be <code>WHITE_NOISE</code>; any other source closes the connection. On role 2, <code>WHITE_NOISE</code> produces nothing and the session ends after the 15-second input stall timeout.		* For role 3 (<code>TX_GENERATED</code>) the source type must be <code>WHITE_NOISE</code>; any other source closes the connection. On role 2, <code>WHITE_NOISE</code> 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 [[SimTX API/Packets/TxReject\|TxReject]], as is audio that would need to be resampled by more than 128×.		* 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 [[SimTX API v24/Packets/TxReject\|TxReject]], as is audio that would need to be resampled by more than 128×.

	== Example ==		== Example ==
	The minimal request from [[SimTX API/Quick start\|Quick start]], built in Python:		The minimal request from [[SimTX API v24/Quick start\|Quick start]], built in Python:

	<syntaxhighlight lang="python">		<syntaxhighlight lang="python">
Line 133:		Line 133:

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

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

Clanker: Clanker moved page SimTX API/Packets/TransmitterSessionRequest to SimTX API v24/Packets/TransmitterSessionRequest: Archive the v24 protocol reference

2026-10-24T16:18:16Z

Clanker moved page SimTX API/Packets/TransmitterSessionRequest to SimTX API v24/Packets/TransmitterSessionRequest: Archive the v24 protocol reference

← Older revision	Revision as of 16:18, 24 October 2026
(No difference)

Clanker: SimTX API documentation

2026-10-24T09:59:03Z

SimTX API documentation

New page

{{SimTX API navigation}}
{{SimTX packet
| name = TransmitterSessionRequest
| id = 2
| hex = 0x02
| direction = c2s
| session = [[SimTX API/Transmitter session|Transmitter]]
| size = Variable, at most 263,168 bytes of field payload
| permission = <code>game.transmit</code> (checked at the handshake)
| reply = [[SimTX API/Packets/TxQueue|TxQueue]], [[SimTX API/Packets/TxAccept|TxAccept]] or [[SimTX API/Packets/TxReject|TxReject]]
| group = transmitter
}}
'''TransmitterSessionRequest''' starts a [[SimTX API/Transmitter session|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 [[SimTX API/Packets/HandshakeResult|HandshakeResult]] on a connection with role 2 or 3.

Unlike most packets, the body is a [[SimTX API/Data types#TLV field list|TLV field list]], so that fields can be added in later revisions without breaking existing clients.

== Layout ==
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>packetId</code> || <code>u8</code> || Always <code>2</code>.
|-
| <code>fieldCount</code> || <code>u8</code> || Number of fields that follow.
|-
| <code>fields</code> || <code>fieldCount × { u8 fieldId, i32 length, u8[length] payload }</code> || Fields in any order. See [[#Fields|Fields]].
|}

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

The ''Live'' column marks fields that can later be changed with [[SimTX API/Packets/TxUpdate|TxUpdate]].

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

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

== 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 (<code>TX_GENERATED</code>) the source type must be <code>WHITE_NOISE</code>; any other source closes the connection. On role 2, <code>WHITE_NOISE</code> 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 [[SimTX API/Packets/TxReject|TxReject]], as is audio that would need to be resampled by more than 128×.

== Example ==
The minimal request from [[SimTX API/Quick start|Quick start]], built in Python:

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

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

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