Editing SimTX API v24/Packets/TransmitterSessionRequest

{{SimTX API v24 navigation}}
{{SimTX packet v24
| name = TransmitterSessionRequest
| id = 2
| hex = 0x02
| direction = c2s
| session = [[SimTX API v24/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 v24/Packets/TxQueue|TxQueue]], [[SimTX API v24/Packets/TxAccept|TxAccept]] or [[SimTX API v24/Packets/TxReject|TxReject]]
| group = transmitter
}}
'''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 v24/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 v24/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 v24/Data types#GeoPoint|GeoPoint]] (24 bytes) || Yes || Valid coordinates || — ||
|-
| 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 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
|-
| 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 v24/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 v24/Packets/TxReject|TxReject]], as is audio that would need to be resampled by more than 128×.

== Example ==
The minimal request from [[SimTX API v24/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 v24/Transmitter session]]
* [[Advanced Transmitter Settings]]
* [[Modulation Modes]]

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