Editing SimTX API v24/Data types

{{SimTX API v24 navigation}}
This page defines the primitive types and shared structures used in the [[SimTX API v24]] game protocol. Every packet layout in the reference is written in terms of these types.

== Byte order ==
All multi-byte values are '''big-endian''' (network byte order). This matches Java's <code>DataOutputStream</code>, which the reference implementation uses, and Python's <code>struct</code> format prefix <code>&gt;</code>.

== Primitive types ==
{| class="wikitable"
! Type !! Size !! Description !! Python <code>struct</code>
|-
| <code>u8</code> || 1 || Unsigned 8-bit integer. || <code>B</code>
|-
| <code>i8</code> || 1 || Signed 8-bit integer. || <code>b</code>
|-
| <code>bool</code> || 1 || <code>0</code> is false; any other value is read as true. Writers must send <code>0</code> or <code>1</code>. || <code>?</code>
|-
| <code>u16</code> || 2 || Unsigned 16-bit integer. || <code>H</code>
|-
| <code>i16</code> || 2 || Signed 16-bit two's-complement integer. || <code>h</code>
|-
| <code>i32</code> || 4 || Signed 32-bit two's-complement integer. || <code>i</code>
|-
| <code>i64</code> || 8 || Signed 64-bit two's-complement integer. || <code>q</code>
|-
| <code>f32</code> || 4 || IEEE 754 binary32 floating point. || <code>f</code>
|-
| <code>f64</code> || 8 || IEEE 754 binary64 floating point. || <code>d</code>
|}

Unless a field description says otherwise, floating-point values must be finite. A NaN or infinity in a request field usually causes the server to close the connection.

== Strings ==
The protocol has two string encodings. Using the wrong one is the most common cause of a connection that closes for no visible reason.

=== UTF ===
'''<code>UTF</code>''' is Java's ''modified UTF-8'' as written by <code>DataOutputStream.writeUTF</code>:

<syntaxhighlight lang="text">
u16      byteLength      number of bytes that follow (not characters)
u8[...]  bytes           modified UTF-8
</syntaxhighlight>

Modified UTF-8 differs from standard UTF-8 in two ways:
* The character U+0000 is encoded as the two bytes <code>C0 80</code>, never as a single <code>00</code> byte.
* Characters outside the Basic Multilingual Plane (U+10000 and above, which includes most emoji) are encoded as a UTF-16 surrogate pair, each surrogate written as a separate three-byte sequence. A four-byte UTF-8 sequence is invalid.

For text consisting only of characters in U+0001 to U+FFFF, modified UTF-8 is byte-for-byte identical to standard UTF-8. Clients that restrict callsigns and other text to the BMP and reject control characters can use an ordinary UTF-8 encoder. The maximum length is 65,535 bytes; most fields impose a much smaller limit.

=== UTF-8 bytes ===
Fields of the [[SimTX API v24/Packets/TransmitterSessionRequest|TransmitterSessionRequest]] TLV list, and the NEC deck inside [[#AntennaConfig|AntennaConfig]], carry '''standard UTF-8''' with an explicit <code>i32</code> length supplied by the surrounding structure. These are marked <code>UTF-8</code> in layouts.

== Enumerations ==
Enumerated values are sent as strings containing the constant name, for example <code>"USB"</code>. Matching is case-sensitive. An unknown name in a request closes the connection.

=== Modulation ===
{| class="wikitable"
! Name !! Description !! Typical bandwidth
|-
| <code>AM_DSB_FC</code> || AM, double sideband, full carrier || 10 kHz
|-
| <code>AM_DSB_SC</code> || AM, double sideband, suppressed carrier || 6 kHz
|-
| <code>USB</code> || Upper sideband || 2.7 kHz
|-
| <code>LSB</code> || Lower sideband || 2.7 kHz
|-
| <code>CW</code> || Continuous wave (Morse) || 150 Hz
|-
| <code>NFM</code> || Narrow FM || 12.5 kHz
|-
| <code>WFM</code> || Wide FM || 180 kHz
|-
| <code>IQ</code> || External complex baseband supplied by the client || As declared
|-
| <code>WSPR</code> || Weak Signal Propagation Reporter || 6 Hz
|-
| <code>FT8</code> || FT8 || 50 Hz
|}

See [[Modulation Modes]] for how each mode behaves on air.

=== TransmissionSourceType ===
{| class="wikitable"
! Name !! Meaning
|-
| <code>AUDIO_STREAM</code> || Mono audio streamed by the client, for example a file or a network stream.
|-
| <code>MICROPHONE</code> || Mono audio from a microphone. Identical to <code>AUDIO_STREAM</code> on the wire.
|-
| <code>PIPEWIRE</code> || Mono audio from a desktop audio graph. Identical to <code>AUDIO_STREAM</code> on the wire.
|-
| <code>GNU_RADIO_IQ</code> || Complex baseband streamed by the client. Use with modulation <code>IQ</code>.
|-
| <code>WHITE_NOISE</code> || Generated by the server. Only valid for role <code>TX_GENERATED</code>.
|}

The three audio types differ only in how they are labelled. A third-party client normally uses <code>AUDIO_STREAM</code> or <code>GNU_RADIO_IQ</code>.

=== AntennaType ===
<code>DIPOLE</code>, <code>VERTICAL</code>, <code>YAGI_3EL</code>, <code>YAGI_5EL</code>, <code>LOOP</code>, <code>BEVERAGE</code>, <code>LONGWIRE</code>, <code>INVERTED_V</code>, <code>EFHW_32M_49_1</code>. Each is described in [[Antenna System]] and its linked pages.

=== WeatherMapType ===
See [[SimTX API v24/Packets/WeatherMapRequest|WeatherMapRequest]].

=== CatalogType ===
See [[SimTX API v24/Packets/CatalogList|CatalogList]].

== Shared structures ==
=== GeoPoint ===
A position on the WGS 84 ellipsoid. 24 bytes.

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>latitudeDeg</code> || <code>f64</code> || Latitude in degrees, −90 to 90. North is positive.
|-
| <code>longitudeDeg</code> || <code>f64</code> || Longitude in degrees, −180 to 180. East is positive.
|-
| <code>altitudeMeters</code> || <code>f64</code> || Height of the station site in metres. Antenna height is given separately in AntennaConfig.
|}

=== AntennaConfig ===
Describes a station's antenna. Variable length; at least 26 bytes.

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>type</code> || <code>UTF</code> || An [[#AntennaType|AntennaType]] name.
|-
| <code>heightMeters</code> || <code>f32</code> || Height of the antenna above ground, ≥ 0.
|-
| <code>azimuthDeg</code> || <code>f32</code> || Bearing of the main lobe or of the wire, in degrees from true north.
|-
| <code>feedlineLossDb</code> || <code>f32</code> || Feed line loss in dB, ≥ 0.
|-
| <code>wireLengthMeters</code> || <code>f32</code> || Wire or element length in metres, ≥ 0.
|-
| <code>necDeckLength</code> || <code>i32</code> || Length of the following deck in bytes, 0 to 262,144.
|-
| <code>necDeck</code> || <code>u8[necDeckLength]</code> || A NEC-2 card deck in standard UTF-8, or empty.
|}

When <code>necDeck</code> is not empty it replaces the built-in antenna model: the server solves the geometry itself and derives feed-point impedance, SWR and radiation pattern from it. The <code>type</code> field must still contain a valid name. Supported cards and limits are described in [[NEC File Import]]. An invalid deck closes the session. There is no way to upload a precomputed radiation pattern.

Example: a 20 m dipole at 10 m with no deck.

<syntaxhighlight lang="text">
00 06 44 49 50 4F 4C 45     UTF "DIPOLE"
41 20 00 00                 heightMeters      10.0
00 00 00 00                 azimuthDeg         0.0
00 00 00 00                 feedlineLossDb     0.0
41 A0 00 00                 wireLengthMeters  20.0
00 00 00 00                 necDeckLength      0
</syntaxhighlight>

=== Callsign ===
A callsign identifies a station in station lists. It is trimmed of surrounding whitespace and must contain 1 to 64 characters with no control characters. In a transmitter request it is limited to 64 bytes of UTF-8. SimTX does not check callsigns against any licensing database.

=== Station UUID ===
Stations are identified by a UUID in its canonical 36-character text form, for example <code>3f2504e0-4f89-11d3-9a0c-0305e82c3301</code>, carried as <code>UTF</code>. The server assigns it when a session starts.

=== TLV field list ===
Some packets carry a list of tagged fields, so that fields can be added without breaking older clients:

<syntaxhighlight lang="text">
u8   count
count × {
  u8   fieldId
  i32  length          number of payload bytes
  u8[length] payload
}
</syntaxhighlight>

Numeric payloads are a single <code>f32</code> or <code>i32</code> (length 4). String payloads are standard UTF-8 without a further length prefix. A reader skips fields whose ID it does not know. See [[SimTX API v24/Packets/TransmitterSessionRequest|TransmitterSessionRequest]] and [[SimTX API v24/Packets/TxUpdate|TxUpdate]].

== Layout notation ==
Packet pages describe layouts as tables in wire order. Repeated groups are written <code>count × { … }</code>. A field shown as <code>u8[n]</code> is exactly ''n'' raw bytes. Packet bodies never contain padding or alignment bytes.

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