Editing SimTX API/Data types

{{SimTX API navigation}}
This page defines the types used by the [[SimTX API]] game protocol, version 25: how protobuf scalars appear on the wire, the conventions for ids, times and units, every enumeration, and the messages shared by several frames. Messages that belong to a single frame are described on that frame's page.

The authoritative definitions are the [[SimTX API/Schema|.proto files]]. Where this page and the files disagree, the files win.

== Scalar types ==
Messages use standard protobuf 3 encoding. A field is a ''tag'' (a varint holding <code>field number × 8 + wire type</code>) followed by its value:

{| class="wikitable"
! Proto type !! Wire type !! Encoding !! Python <code>struct</code> !! Used for
|-
| <code>bool</code> || 0 (varint) || 0 or 1 || || Flags
|-
| <code>int32</code>, <code>int64</code> || 0 (varint) || Two's complement as a varint. Negative values take 10 bytes. || || Counts, ids, Unix times
|-
| enum || 0 (varint) || The value's number || || Enumerations
|-
| <code>fixed64</code> || 1 (64-bit) || 8 bytes, little-endian, unsigned || <code>&lt;Q</code> || <code>IqBlock.sequence</code>
|-
| <code>double</code> || 1 (64-bit) || IEEE 754 binary64, little-endian || <code>&lt;d</code> || Positions, frequencies
|-
| <code>float</code> || 5 (32-bit) || IEEE 754 binary32, little-endian || <code>&lt;f</code> || Levels, bandwidths, angles of antennas
|-
| <code>string</code> || 2 (length-delimited) || Varint length, then UTF-8 || || Names, callsigns, string enumerations
|-
| <code>bytes</code> || 2 (length-delimited) || Varint length, then raw bytes || || UUIDs, sample payloads
|-
| message || 2 (length-delimited) || Varint length, then the encoded message || || Nested messages
|-
| <code>repeated float</code> || 2 (length-delimited) || Packed: varint length, then the values back to back || <code>&lt;nf</code> || Sample blocks, rasters
|}

* '''Zero values are omitted.''' In proto3 a field holding its default (0, false, empty) is not written, and a missing field reads as its default. A decoder cannot tell an absent field from an explicit default: an absent <code>state</code> reads as 0, <code>SESSION_STATE_UNSPECIFIED</code>.
* '''Presence.''' Fields marked <code>optional</code> (for example <code>ReceiverStart.noise_figure_db</code>, the [[#TxImperfections|TxImperfections]] knobs, every [[SimTX API/Packets/TxUpdate|TxUpdate]] value) do record whether they were set. Unset means "use the default", which is not the same as 0.
* '''Floats must be finite.''' Unless a field says otherwise, NaN and infinity in a request are refused.

== Conventions ==
{| class="wikitable"
! What !! Convention
|-
| UUIDs || 16 bytes in a <code>bytes</code> field, big-endian, most significant half first: the 16 bytes of the canonical form <code>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</code> in order. Empty means "none". Station, antenna, rig, session, account and satellite ids all use this form. In Python, <code>uuid.UUID(bytes=value)</code>.
|-
| Times || Fields ending in <code>_ms</code> are Unix milliseconds (UTC). <code>*_epoch_seconds</code> and <code>*_nanos</code> pairs give nanosecond precision. Durations end in <code>_seconds</code>, <code>_ms</code> or <code>_nanos</code>.
|-
| Frequencies || Hz. Carrier and centre frequencies are <code>double</code>; bandwidths and audio frequencies are <code>float</code>.
|-
| Angles || Degrees. Azimuth from true north through east.
|-
| Positions || Latitude −90 to 90 (north positive), longitude −180 to 180 (east positive). Heights in metres.
|-
| Units || Every other quantity carries its unit in the field name: <code>_db</code>, <code>_watts</code>, <code>_meters</code>, <code>_km</code>, <code>_mps</code>, <code>_rpm</code> and so on.
|-
| Sample bytes || The IQ samples inside <code>IqBlock.samples</code> and <code>SampleBlock.compact_iq.samples</code> are big-endian <code>int16</code> or <code>int8</code>, unlike protobuf's own little-endian scalars.
|-
| Request ids || Requests carry an <code>int64 request_id</code> chosen by the client, echoed in the response or in an [[SimTX API/Packets/Error|Error]]. Use nonzero values; 0 in an Error means the whole connection.
|-
| Callsigns || Trimmed of surrounding whitespace; 1 to 64 printable characters. SimTX does not check callsigns against any licensing database.
|}

== Enumerations ==
Proto enums travel as their number. An omitted enum field reads as 0, and the value 0 never grants or asserts anything:
* Most enums start with an <code>*_UNSPECIFIED = 0</code> value. Where the field is required (<code>Role</code>, <code>SessionState</code>, <code>IpModerationAction</code>, and <code>StationKind</code> wherever a persistent station is meant), decoders refuse 0.
* A few have a real value at 0, the default: <code>AuthKind</code> ANONYMOUS, <code>AntennaMount</code> FIXED, <code>PointingMode</code> FIXED, <code>SpinAxis</code> ORBIT_NORMAL, <code>StationKind</code> ADHOC, <code>StationVisibility</code> UNLISTED, <code>SampleFormat</code> INT16, <code>BannerLevel</code> INFO.
* A reader that receives a value it does not know keeps the number and treats it as unknown, as each table below says.

=== Role ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>ROLE_UNSPECIFIED</code> || Refused.
|-
| 1 || <code>ROLE_RECEIVER</code> || [[SimTX API/Receiver session|Receiver]]: an IQ stream. Anonymous for ad-hoc sites; a <code>receiver</code> ticket for station-bound ones.
|-
| 2 || <code>ROLE_TX_AUDIO</code> || [[SimTX API/Transmitter session|Transmitter]] whose samples the client streams. Ticket <code>tx-audio</code>, permission <code>game.transmit</code>.
|-
| 3 || <code>ROLE_TX_GENERATED</code> || Transmitter whose source the server generates. Ticket <code>tx-generated</code>, permission <code>game.transmit</code>.
|-
| 4 || <code>ROLE_CONTROL</code> || [[SimTX API/Control session|Control]]: station list, maps, health, catalog, ephemeris, passes, own-transmitter monitor. Anonymous, or ticket <code>control</code>.
|-
| 5 || <code>ROLE_MODERATION</code> || [[SimTX API/Moderation session|Moderation]]. Ticket <code>moderation</code>, permission <code>moderation.manage</code>.
|}

=== AuthKind ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>AUTH_KIND_ANONYMOUS</code> || No credential. An anonymous hello that carries a credential is refused.
|-
| 1 || <code>AUTH_KIND_GAME_TICKET</code> || <code>credential</code> holds a game ticket.
|}

=== HelloStatus ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>HELLO_STATUS_UNSPECIFIED</code> || Not sent by servers. Treat it, and unknown values, as <code>SERVER_UNAVAILABLE</code>.
|-
| 1 || <code>HELLO_STATUS_ACCEPTED</code> || The session may begin.
|-
| 2 || <code>HELLO_STATUS_VERSION_UNSUPPORTED</code> || The preface version is not 25.
|-
| 3 || <code>HELLO_STATUS_AUTHENTICATION_REQUIRED</code> || The role needs a ticket and none was sent. Typical message: <i>This role requires a SimTX account</i>.
|-
| 4 || <code>HELLO_STATUS_CREDENTIAL_INVALID</code> || The ticket is unknown, expired, used, or minted for another server or role. Typical message: <i>Game ticket is invalid or expired</i>.
|-
| 5 || <code>HELLO_STATUS_ACCOUNT_RESTRICTED</code> || The account is restricted.
|-
| 6 || <code>HELLO_STATUS_ROLE_FORBIDDEN</code> || The account lacks the permission the role needs. Typical message: <i>Account is not permitted to transmit</i>.
|-
| 7 || <code>HELLO_STATUS_SERVER_UNAVAILABLE</code> || The server cannot verify the ticket or take the connection now. The only status worth retrying unchanged.
|-
| 8 || <code>HELLO_STATUS_IP_BANNED</code> || The client address is banned. The message gives the reason.
|}

=== ErrorCode ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>ERROR_CODE_UNSPECIFIED</code> || No specific code: an <code>ENDED</code> session that simply ended. Also how to treat unknown codes.
|-
| 1 || <code>ERROR_CODE_INVALID_REQUEST</code> || Malformed or out-of-range request, or a frame not allowed in this session.
|-
| 2 || <code>ERROR_CODE_UNAUTHENTICATED</code> || Needs an account or a valid ticket.
|-
| 3 || <code>ERROR_CODE_FORBIDDEN</code> || Not allowed, or the ticket's station binding does not match the request.
|-
| 4 || <code>ERROR_CODE_NOT_FOUND</code> || Unknown station, satellite, session or catalog entry.
|-
| 5 || <code>ERROR_CODE_LIMIT_REACHED</code> || Server, address, account or station capacity reached.
|-
| 6 || <code>ERROR_CODE_RATE_LIMITED</code> || Too many requests.
|-
| 7 || <code>ERROR_CODE_UNAVAILABLE</code> || Transient condition: disabled, busy or not reachable.
|-
| 8 || <code>ERROR_CODE_STATION_INACTIVE</code> || The station is deleted or deorbited, or the satellite has reentered.
|-
| 9 || <code>ERROR_CODE_STATION_REQUIRED</code> || Ad-hoc transmitter refused; bind one of your stations.
|-
| 10 || <code>ERROR_CODE_INTERNAL</code> || Server fault.
|-
| 11 || <code>ERROR_CODE_CANCELLED</code> || Superseded by a newer request of the same kind (coverage maps).
|}

=== SessionState ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>SESSION_STATE_UNSPECIFIED</code> || Never sent. Decoders refuse it.
|-
| 1 || <code>SESSION_STATE_BOUND</code> || Start accepted. <code>TxQueue</code> / <code>TxAccept</code> or <code>IqStreamDescriptor</code> follow.
|-
| 2 || <code>SESSION_STATE_REJECTED</code> || Start refused. <code>code</code> and <code>reason</code> say why; the connection closes.
|-
| 3 || <code>SESSION_STATE_ENDED</code> || Ended by the server: kick, ban, station deleted, reentry, access revoked. The connection closes.
|-
| 4 || <code>SESSION_STATE_UPDATED</code> || The session keeps running with a changed state; see <code>update_reason</code>.
|}

=== UpdateReason ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>UPDATE_REASON_UNSPECIFIED</code> || Not an <code>UPDATED</code> status. On an <code>UPDATED</code> status: apply the snapshot fields.
|-
| 1 || <code>UPDATE_REASON_POINTING</code> || This session's [[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]] was applied (<code>request_id</code>).
|-
| 2 || <code>UPDATE_REASON_TRACKING</code> || The server changed tracking, for example because the target was deleted or reentered.
|-
| 3 || <code>UPDATE_REASON_STATION_EDIT</code> || The station, its antenna or its rig was edited; revisions are bumped.
|-
| 4 || <code>UPDATE_REASON_ORBIT_CHANGE</code> || The bound satellite's elements or attitude changed.
|-
| 5 || <code>UPDATE_REASON_DEORBIT_SCHEDULED</code> || The bound satellite fired its deorbit burn; <code>station.core.deorbit</code> says when it reenters.
|-
| 6 || <code>UPDATE_REASON_RETUNE</code> || This session's [[SimTX API/Packets/ReceiverRetune|ReceiverRetune]] took effect (<code>request_id</code>).
|}

=== SampleFormat ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>SAMPLE_FORMAT_INT16</code> || Big-endian <code>int16</code> components; divide by 32767. The default.
|-
| 1 || <code>SAMPLE_FORMAT_INT8</code> || <code>int8</code> components; divide by 127.
|}

=== TxLiveField ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>TX_LIVE_FIELD_UNSPECIFIED</code> || In a TxUpdateAck result, like an unknown value: a field this client does not know. Ignore that result.
|-
| 1 || <code>TX_LIVE_FIELD_FREQUENCY</code> || <code>frequency_hz</code>
|-
| 2 || <code>TX_LIVE_FIELD_POWER</code> || <code>power_watts</code>
|-
| 3 || <code>TX_LIVE_FIELD_BANDWIDTH</code> || <code>bandwidth_hz</code>
|-
| 4 || <code>TX_LIVE_FIELD_LOW_CUT</code> || <code>audio_low_cut_hz</code>
|-
| 5 || <code>TX_LIVE_FIELD_FINAL_DRIVE</code> || <code>final_drive_db</code>
|-
| 6 || <code>TX_LIVE_FIELD_PA_HEADROOM</code> || <code>pa_headroom_db</code>
|-
| 7 || <code>TX_LIVE_FIELD_AUDIO_COMPRESSION</code> || <code>audio_compression_db</code>
|-
| 8 || <code>TX_LIVE_FIELD_AUDIO_GAIN</code> || <code>audio_gain</code>
|}

=== AntennaMount ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>ANTENNA_MOUNT_FIXED</code> || No rotator. The default.
|-
| 1 || <code>ANTENNA_MOUNT_AZ</code> || Azimuth rotator. Elevation stays at the pointing's elevation.
|-
| 2 || <code>ANTENNA_MOUNT_AZEL</code> || Azimuth and elevation rotator.
|}

=== PointingMode ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>POINTING_MODE_FIXED</code> || Hold the given azimuth and elevation. The default.
|-
| 1 || <code>POINTING_MODE_TRACK</code> || Follow a target station.
|}

=== SpinAxis ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>SPIN_AXIS_ORBIT_NORMAL</code> || Spin about the orbit normal. The default.
|-
| 1 || <code>SPIN_AXIS_NADIR</code> || Spin about the nadir direction.
|-
| 2 || <code>SPIN_AXIS_VELOCITY</code> || Spin about the along-track direction.
|}

=== StationKind ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>STATION_KIND_ADHOC</code> || No persistent station. Only in [[SimTX API/Packets/StationList|StationList]] entries; refused wherever a persistent station is meant.
|-
| 1 || <code>STATION_KIND_GROUND</code> || Ground station.
|-
| 2 || <code>STATION_KIND_SATELLITE</code> || User-launched satellite.
|}

=== StationVisibility ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>STATION_VISIBILITY_UNLISTED</code> || Private. Other accounts see only the callsign, as an ad-hoc-style entry. The default.
|-
| 1 || <code>STATION_VISIBILITY_PUBLIC</code> || Listed with id and placement; any signed-in account may receive through it.
|}

=== SessionRole ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>SESSION_ROLE_UNSPECIFIED</code> || Unknown role; show the session without one.
|-
| 1 || <code>SESSION_ROLE_TX</code> || Transmitter.
|-
| 2 || <code>SESSION_ROLE_RX</code> || Receiver.
|}

=== BannerLevel ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>BANNER_LEVEL_INFO</code> || Information. The default; also how to show unknown levels.
|-
| 1 || <code>BANNER_LEVEL_BAN_NOTICE</code> || Sent to control sessions of an address that has just been banned. The text explains the ban.
|}

=== IpModerationAction ===
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>IP_MODERATION_ACTION_UNSPECIFIED</code> || Refused, so an omitted action never bans.
|-
| 1 || <code>IP_MODERATION_ACTION_UNBAN</code> || Lift a ban.
|-
| 2 || <code>IP_MODERATION_ACTION_BAN</code> || Ban an address.
|}

== String enumerations ==
Modulations, sources, antenna types, weather layers, duct types and catalog types travel as upper-case ASCII names in <code>string</code> fields and are compared exactly. Servers may add names without a schema change. A server that does not know a name refuses the request with [[SimTX API/Packets/Error|Error]] or [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>INVALID_REQUEST</code> naming the value. Clients accept names they do not know in server messages and display them as they are.

=== Modulation ===
Used by <code>TransmitterStart.modulation</code>, <code>CoverageMapRequest.modulation</code>, <code>LiveSession.modulation</code> (empty for receivers), <code>TransmitterHealth.modulation</code> and <code>TransmitterImpact.modulation</code>.

{| 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.

=== Source type ===
Used by <code>TransmitterStart.source_type</code> and <code>TransmitterHealth.source_type</code>.

{| 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>WHITE_NOISE</code> || Generated by the server. Only valid for <code>ROLE_TX_GENERATED</code>.
|-
| <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>.
|}

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>.

=== Antenna types ===
Used by <code>AntennaConfig.type</code>.

{| class="wikitable"
! Name !! Antenna !! Notes
|-
| <code>DIPOLE</code> || Half-wave dipole || See [[Dipole Antenna]].
|-
| <code>VERTICAL</code> || Vertical monopole over ground || See [[Vertical Antenna]].
|-
| <code>YAGI_3EL</code> || Three-element Yagi || See [[Yagi Antenna]].
|-
| <code>YAGI_5EL</code> || Five-element Yagi || See [[Yagi Antenna]].
|-
| <code>LOOP</code> || Full-wave loop || See [[Full-Wave Loop Antenna]].
|-
| <code>BEVERAGE</code> || Beverage receiving antenna || See [[Beverage Antenna]].
|-
| <code>LONGWIRE</code> || Long wire || See [[Longwire Antenna]].
|-
| <code>INVERTED_V</code> || Inverted-V dipole || See [[Inverted-V Antenna]].
|-
| <code>EFHW_32M_49_1</code> || End-fed half-wave, 32 m, 49:1 transformer || See [[End-Fed Half-Wave Antenna]].
|-
| <code>MONOPOLE</code> || Monopole || Satellite type; free space.
|-
| <code>TURNSTILE</code> || Turnstile (crossed dipoles), circular polarisation || Satellite and ground station type.
|-
| <code>CROSSED_YAGI</code> || Crossed Yagi, circular polarisation || Steerable ground station type.
|-
| <code>HELIX</code> || Axial-mode helix, circular polarisation || Steerable ground station and satellite type.
|}

Satellite antennas are modelled in free space. A NEC deck in <code>nec_deck</code> replaces any template.

=== Weather type ===
Used by <code>WeatherMapRequest.type</code> and <code>WeatherMapResponse.type</code>.

{| class="wikitable"
! Name !! Quantity !! Unit
|-
| <code>DUCT_STRENGTH</code> || Strength of the strongest tropospheric duct; 0 where there is none || M-units
|-
| <code>RAIN_RATE</code> || Rain rate || mm/h
|-
| <code>CLOUD_WATER</code> || Cloud liquid water content || g/m³
|-
| <code>SURFACE_TEMPERATURE</code> || Air temperature at the surface || °C
|-
| <code>LIGHTNING_RATE</code> || Lightning flash rate || flashes/min
|}

=== Duct type ===
Used by <code>WeatherMapResponse.duct_type</code>.

{| class="wikitable"
! Name !! Meaning
|-
| <code>NONE</code> || No duct.
|-
| <code>SURFACE</code> || Surface duct.
|-
| <code>ELEVATED</code> || Elevated duct.
|}

=== Catalog type ===
Used by <code>CatalogEntrySummary.types</code>.

{| class="wikitable"
! Name !! Display name
|-
| <code>MODULATION</code> || Modulation
|-
| <code>AUDIO_ADDON</code> || Audio add-on
|-
| <code>THEME</code> || Theme
|-
| <code>ACTION</code> || Tool / action
|-
| <code>LIBRARY</code> || Library
|-
| <code>PRESET</code> || Preset
|}

== Shared messages ==
=== GeoPoint ===
A geographic position.

<syntaxhighlight lang="protobuf">
message GeoPoint {
  double latitude_deg = 1;
  double longitude_deg = 2;
  double altitude_meters = 3;
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>latitude_deg</code> || <code>double</code> || Latitude in degrees, −90 to 90. North is positive.
|-
| 2 || <code>longitude_deg</code> || <code>double</code> || Longitude in degrees, −180 to 180. East is positive.
|-
| 3 || <code>altitude_meters</code> || <code>double</code> || Height in metres. For a ground site, the height of the ground at the site; the antenna height is separate (<code>AntennaConfig.height_meters</code>). For a sub-satellite point or an ephemeris sample, the height above the 6,371 km reference sphere.
|}

=== AntennaConfig ===
An antenna: a built-in type or a NEC-2 deck, with its height, bearing, feed line loss and, for steerable antennas, its pointing.

<syntaxhighlight lang="protobuf">
message AntennaConfig {
  string type = 1;              // antenna type (string enum, see the top of this file)
  float height_meters = 2;
  float azimuth_deg = 3;
  float feedline_loss_db = 4;
  float wire_length_meters = 5;
  // NEC-2 card deck (UTF-8, <= 262144 bytes). Empty = built-in template for `type`.
  string nec_deck = 6;
  AntennaPointing pointing = 7;
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>type</code> || <code>string</code> || [[#Antenna types|Antenna type]] name, for example <code>DIPOLE</code>. Required, also when <code>nec_deck</code> is set.
|-
| 2 || <code>height_meters</code> || <code>float</code> || Height of the antenna above ground in metres, ≥ 0. Satellite antennas use 0.
|-
| 3 || <code>azimuth_deg</code> || <code>float</code> || Bearing of the main lobe, or of the wire, in degrees from true north.
|-
| 4 || <code>feedline_loss_db</code> || <code>float</code> || Feed line loss in dB, ≥ 0.
|-
| 5 || <code>wire_length_meters</code> || <code>float</code> || Wire or element length in metres, ≥ 0. 0 sizes the built-in template for the operating frequency.
|-
| 6 || <code>nec_deck</code> || <code>string</code> || NEC-2 card deck in UTF-8, at most 262,144 bytes. Empty selects the built-in template for <code>type</code>. A deck replaces the template: the server solves the geometry itself. Satellite antennas are in free space, so their decks must not contain a <code>GN</code> card. See [[NEC File Import]].
|-
| 7 || <code>pointing</code> || [[#AntennaPointing|AntennaPointing]] || Pointing of a steerable antenna. In a [[#BoundStation|BoundStation]], the antenna's stored default pointing. Unset for a <code>FIXED</code> mount.
|}

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

=== AntennaPointing ===
The pointing of a steerable antenna. See [[SimTX API/Tracking and pointing]].

<syntaxhighlight lang="protobuf">
message AntennaPointing {
  AntennaMount mount = 1;
  PointingMode mode = 2;
  float azimuth_deg = 3;
  float elevation_deg = 4;
  bytes target_station_id = 5;
  float azimuth_rate_deg_per_sec = 6;
  float elevation_rate_deg_per_sec = 7;
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>mount</code> || [[#AntennaMount|AntennaMount]] || Rotator fitted to the antenna. A <code>FIXED</code> mount has no pointing; the other fields are then unused.
|-
| 2 || <code>mode</code> || [[#PointingMode|PointingMode]] || <code>FIXED</code>: hold <code>azimuth_deg</code> / <code>elevation_deg</code>. <code>TRACK</code>: follow <code>target_station_id</code>.
|-
| 3 || <code>azimuth_deg</code> || <code>float</code> || Azimuth in degrees from true north through east. In <code>TRACK</code> mode, the park position the rotator starts from.
|-
| 4 || <code>elevation_deg</code> || <code>float</code> || Elevation above the horizon in degrees. An <code>AZ</code> mount keeps this elevation in every mode.
|-
| 5 || <code>target_station_id</code> || <code>bytes</code> || <code>TRACK</code> mode: 16-byte UUID of the station to follow, usually a satellite. Empty in <code>FIXED</code> mode.
|-
| 6 || <code>azimuth_rate_deg_per_sec</code> || <code>float</code> || Rotator slew rate in azimuth, °/s. 0 selects the default: 6 °/s on an <code>AZEL</code> mount, 3 °/s on an <code>AZ</code> mount.
|-
| 7 || <code>elevation_rate_deg_per_sec</code> || <code>float</code> || Rotator slew rate in elevation, °/s. 0 selects the default of 4 °/s.
|}

=== AntennaAim ===
Where a session's antenna points when the session starts: <code>ReceiverStart.aim</code> and <code>TransmitterStart.aim</code>. Unset means the antenna's stored heading. A <code>FIXED</code> mount ignores it, and an <code>AZ</code> mount ignores the elevation; the <code>pointing</code> of [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>BOUND</code> reports the pointing in effect. With <code>tracking.point_antenna</code> set, the aim is the rotator's position when the session starts, and it slews from there towards the target.

<syntaxhighlight lang="protobuf">
message AntennaAim {
  float azimuth_deg = 1;
  float elevation_deg = 2;
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>azimuth_deg</code> || <code>float</code> || Azimuth in degrees from true north through east. Finite; normalised to 0 to 360.
|-
| 2 || <code>elevation_deg</code> || <code>float</code> || Elevation in degrees, −90 to 90. Ignored by an <code>AZ</code> mount.
|}

=== SessionSite ===
Where a session, or a coverage prediction, sits: one of the account's persistent stations, or an inline ad-hoc site. Used by [[SimTX API/Packets/ReceiverStart|ReceiverStart]], [[SimTX API/Packets/TransmitterStart|TransmitterStart]] and [[SimTX API/Packets/CoverageMapRequest|CoverageMapRequest]]. Exactly one member must be set; a site with neither is refused.

<syntaxhighlight lang="protobuf">
message SessionSite {
  oneof site {
    StationBinding station = 1;   // one of your persistent stations; needs a game ticket
    AdhocStation adhoc = 2;       // inline site; anonymous OK (TX: see the ad-hoc policy)
  }
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>station</code> || [[#StationBinding|StationBinding]] || Member of <code>oneof site</code>. One of your persistent stations, or a PUBLIC station of another account for a receiver. Needs a game ticket minted for it.
|-
| 2 || <code>adhoc</code> || [[#AdhocStation|AdhocStation]] || Member of <code>oneof site</code>. An inline site. Receivers may use it anonymously; transmitters only under the [[SimTX API/Stations#Ad-hoc transmitters|ad-hoc policy]].
|}

=== StationBinding ===
Which persistent station, antenna and rig a session uses. The binding must match the [[SimTX API/Game tickets|game ticket]] of the connection. See [[SimTX API/Stations#Binding a session|Binding a session]].

<syntaxhighlight lang="protobuf">
message StationBinding {
  bytes station_id = 1;
  bytes antenna_id = 2;   // empty = the station's first antenna
  bytes rig_id = 3;       // empty = the station's first rig (by ordinal); rig-less only when it has no rig
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>station_id</code> || <code>bytes</code> || 16-byte UUID of the station. Must be the station the game ticket was minted for.
|-
| 2 || <code>antenna_id</code> || <code>bytes</code> || 16-byte UUID of the antenna. Empty: the station's first antenna, or the antenna the ticket was minted for if its request named one.
|-
| 3 || <code>rig_id</code> || <code>bytes</code> || 16-byte UUID of the rig. Empty: the station's first rig by ordinal, or the rig the ticket was minted for if its request named one. The session is rig-less only when the station has no rig.
|}

=== AdhocStation ===
An inline station for anonymous and ad-hoc sessions.

<syntaxhighlight lang="protobuf">
message AdhocStation {
  string callsign = 1;
  GeoPoint location = 2;
  AntennaConfig antenna = 3;
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>callsign</code> || <code>string</code> || Callsign shown in station lists. Trimmed; 1 to 64 printable characters.
|-
| 2 || <code>location</code> || [[#GeoPoint|GeoPoint]] || Site of the station. Required.
|-
| 3 || <code>antenna</code> || [[#AntennaConfig|AntennaConfig]] || Antenna. Required.
|}

=== Tracking ===
Follow a target station, usually a satellite, with the antenna and with Doppler correction. See [[SimTX API/Tracking and pointing]].

<syntaxhighlight lang="protobuf">
message Tracking {
  bytes target_station_id = 1;
  bool point_antenna = 2;     // drive the antenna's rotator toward the target
  bool doppler_correct = 3;   // RX: shift tuning by the target's Doppler; TX: pre-correct so it arrives on frequency
  // Simulation time at which the rotator began slewing toward this target (point_antenna only; both 0 =
  // not known). Servers set it in SessionStatus; with the antenna's slew rate it gives the rotator position.
  // Ignored in a client's start or AntennaPointingUpdate.
  int64 since_epoch_seconds = 4;
  int32 since_nanos = 5;
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>target_station_id</code> || <code>bytes</code> || 16-byte UUID of the station to track, usually a satellite.
|-
| 2 || <code>point_antenna</code> || <code>bool</code> || Drive the antenna's rotator towards the target. Needs an <code>AZ</code> or <code>AZEL</code> mount.
|-
| 3 || <code>doppler_correct</code> || <code>bool</code> || Receiver: shift the tuning by the target's Doppler. Transmitter: pre-correct the carrier so that the signal arrives on frequency at the target.
|-
| 4 || <code>since_epoch_seconds</code> || <code>int64</code> || Simulation time at which the rotator began slewing towards this target, Unix seconds (<code>point_antenna</code> only). Set by servers in [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>BOUND</code> and <code>UPDATED</code>; with the antenna's slew rates it gives the rotator's position for display. Clients leave it unset; servers ignore it in a client's start or [[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]]. 0 together with <code>since_nanos</code> 0: not known.
|-
| 5 || <code>since_nanos</code> || <code>int32</code> || Nanoseconds added to <code>since_epoch_seconds</code>.
|}

=== StationCore ===
The fields every view of a persistent station shares. Embedded as <code>core</code> by [[#BoundStation|BoundStation]] (in session status) and by <code>Station</code> (in the [[SimTX API/Packets/StationList|station list]]).

<syntaxhighlight lang="protobuf">
message StationCore {
  bytes station_id = 1;          // empty only for ad-hoc StationList entries
  int64 revision = 2;            // bumped on every edit of the station
  StationKind kind = 3;
  string name = 4;
  string callsign = 5;
  string owner_handle = 6;
  StationVisibility visibility = 7;
  GeoPoint location = 8;         // ground: the site; satellite: the sub-satellite point (see the embedding message)
  OrbitalElements orbit = 9;     // satellites
  Attitude attitude = 10;        // satellites
  Deorbit deorbit = 11;          // satellites with a deorbit burn scheduled or done
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>station_id</code> || <code>bytes</code> || 16-byte station UUID. Empty only for the ad-hoc entries of a [[SimTX API/Packets/StationList|StationList]].
|-
| 2 || <code>revision</code> || <code>int64</code> || Station revision. Bumped on every edit of the station.
|-
| 3 || <code>kind</code> || [[#StationKind|StationKind]] || <code>GROUND</code> or <code>SATELLITE</code>; <code>ADHOC</code> only in a StationList.
|-
| 4 || <code>name</code> || <code>string</code> || Station name, 1 to 64 characters.
|-
| 5 || <code>callsign</code> || <code>string</code> || Callsign, 1 to 64 characters.
|-
| 6 || <code>owner_handle</code> || <code>string</code> || Handle of the account that owns the station. Empty for ad-hoc entries.
|-
| 7 || <code>visibility</code> || [[#StationVisibility|StationVisibility]] || <code>PUBLIC</code> or <code>UNLISTED</code>.
|-
| 8 || <code>location</code> || [[#GeoPoint|GeoPoint]] || Ground: the station site. Satellite: the sub-satellite point at the time the containing message was captured.
|-
| 9 || <code>orbit</code> || [[#OrbitalElements|OrbitalElements]] || Satellites: the current element set. After a deorbit burn, the post-burn elements.
|-
| 10 || <code>attitude</code> || [[#Attitude|Attitude]] || Satellites: the attitude law.
|-
| 11 || <code>deorbit</code> || [[#Deorbit|Deorbit]] || Satellites whose deorbit burn has fired. Unset otherwise.
|}

=== BoundStation ===
The station a session is attached to, as the server resolved it. Sent in [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>BOUND</code>, and in <code>UPDATED</code> when the station changed. <code>core.kind</code> is <code>GROUND</code> or <code>SATELLITE</code>. <code>core.location</code> is the site of a ground station, or the sub-satellite point when the status was sent.

<syntaxhighlight lang="protobuf">
message BoundStation {
  StationCore core = 1;
  bytes antenna_id = 2;
  int64 antenna_revision = 3;
  bytes rig_id = 4;                // empty = rig-less (the station has no rig)
  int64 rig_revision = 5;
  float pa_cap_watts = 6;          // effective PA cap; 0 = uncapped
  AntennaConfig antenna = 7;       // pointing = the antenna's default pointing
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>core</code> || [[#StationCore|StationCore]] || The station: id, revision, kind, name, callsign, owner, visibility, placement and deorbit state. <code>kind</code> is <code>GROUND</code> or <code>SATELLITE</code>; decoders refuse <code>ADHOC</code> here.
|-
| 2 || <code>antenna_id</code> || <code>bytes</code> || 16-byte UUID of the bound antenna.
|-
| 3 || <code>antenna_revision</code> || <code>int64</code> || Revision of the bound antenna.
|-
| 4 || <code>rig_id</code> || <code>bytes</code> || 16-byte UUID of the bound rig. Empty: no rig.
|-
| 5 || <code>rig_revision</code> || <code>int64</code> || Revision of the bound rig; 0 without a rig.
|-
| 6 || <code>pa_cap_watts</code> || <code>float</code> || Effective PA cap in watts: the smaller of the rig's cap and the account's <code>tx.pa_limit</code>. 0 = uncapped.
|-
| 7 || <code>antenna</code> || [[#AntennaConfig|AntennaConfig]] || The bound antenna as the server models it. <code>pointing</code> is the antenna's stored default.
|}

=== OrbitalElements ===
The mean orbital elements of a satellite in the <code>simtx-j2-v1</code> model. See [[SimTX API/Satellites#Orbit model|Orbit model]].

<syntaxhighlight lang="protobuf">
message OrbitalElements {
  string model = 1;            // "simtx-j2-v1"
  int64 epoch_seconds = 2;     // Unix seconds of the element epoch
  int32 epoch_nanos = 3;
  double semi_major_axis_km = 4;
  double eccentricity = 5;
  double inclination_deg = 6;
  double raan_deg = 7;
  double argument_of_perigee_deg = 8;
  double mean_anomaly_deg = 9;
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>model</code> || <code>string</code> || Orbit model. Always <code>simtx-j2-v1</code>; see [[SimTX API/Satellites#Orbit model|Orbit model]].
|-
| 2 || <code>epoch_seconds</code> || <code>int64</code> || Element epoch, Unix seconds. Set by the account service to the launch instant, or to the burn time after a deorbit burn.
|-
| 3 || <code>epoch_nanos</code> || <code>int32</code> || Nanoseconds added to <code>epoch_seconds</code>, 0 to 999,999,999.
|-
| 4 || <code>semi_major_axis_km</code> || <code>double</code> || Mean semi-major axis <i>a</i> in km.
|-
| 5 || <code>eccentricity</code> || <code>double</code> || Mean eccentricity <i>e</i>, 0 ≤ <i>e</i> < 1.
|-
| 6 || <code>inclination_deg</code> || <code>double</code> || Mean inclination <i>i</i> in degrees, 0 to 180.
|-
| 7 || <code>raan_deg</code> || <code>double</code> || Right ascension of the ascending node Ω at the epoch, degrees.
|-
| 8 || <code>argument_of_perigee_deg</code> || <code>double</code> || Argument of perigee ω at the epoch, degrees.
|-
| 9 || <code>mean_anomaly_deg</code> || <code>double</code> || Mean anomaly <i>M</i><sub>0</sub> at the epoch, degrees.
|}

=== Attitude ===
How a satellite's body is oriented. No mode set means nadir pointing with yaw 0. The frames are defined on [[SimTX API/Satellites#Attitude|Satellites]].

<syntaxhighlight lang="protobuf">
message Attitude {
  message Nadir { double yaw_deg = 1; }
  message Inertial { double right_ascension_deg = 1; double declination_deg = 2; double roll_deg = 3; }
  message Spin { SpinAxis axis = 1; double rate_rpm = 2; double phase_deg = 3; }
  oneof mode {
    Nadir nadir = 1;
    Inertial inertial = 2;
    Spin spin = 3;
  }
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>nadir</code> || [[#Attitude|Nadir]] || Member of <code>oneof mode</code>. Nadir pointing with a yaw angle.
|-
| 2 || <code>inertial</code> || [[#Attitude|Inertial]] || Member of <code>oneof mode</code>. The body z axis held fixed in the inertial frame.
|-
| 3 || <code>spin</code> || [[#Attitude|Spin]] || Member of <code>oneof mode</code>. Spin about an axis of the orbiting frame.
|}

'''Nadir'''

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>yaw_deg</code> || <code>double</code> || Rotation about the body z axis (nadir), degrees.
|}

'''Inertial'''

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>right_ascension_deg</code> || <code>double</code> || Right ascension α of the body z axis, degrees.
|-
| 2 || <code>declination_deg</code> || <code>double</code> || Declination δ of the body z axis, degrees, −90 to 90.
|-
| 3 || <code>roll_deg</code> || <code>double</code> || Rotation about the body z axis, degrees. At 0 the body x axis points towards increasing right ascension.
|}

'''Spin'''

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>axis</code> || [[#SpinAxis|SpinAxis]] || Spin axis in the orbiting frame. 0 = <code>ORBIT_NORMAL</code>.
|-
| 2 || <code>rate_rpm</code> || <code>double</code> || Spin rate in revolutions per minute, 0 to 60, relative to the orbiting frame.
|-
| 3 || <code>phase_deg</code> || <code>double</code> || Spin phase φ<sub>0</sub> at the orbit epoch, degrees.
|}

=== Deorbit ===
The deorbit burn of a satellite, once it has fired. See [[SimTX API/Satellites#Deorbit|Deorbit]].

<syntaxhighlight lang="protobuf">
message Deorbit {
  int64 burn_at_ms = 1;
  int64 reentry_at_ms = 2;
  GeoPoint reentry_point = 3;
  double delta_v_mps = 4;
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>burn_at_ms</code> || <code>int64</code> || When the retrograde burn fired, Unix ms.
|-
| 2 || <code>reentry_at_ms</code> || <code>int64</code> || When the satellite reaches 80 km and burns up, Unix ms. Its sessions end at this time.
|-
| 3 || <code>reentry_point</code> || [[#GeoPoint|GeoPoint]] || Sub-satellite point at <code>reentry_at_ms</code>; <code>altitude_meters</code> is 80,000.
|-
| 4 || <code>delta_v_mps</code> || <code>double</code> || Velocity change of the burn, m/s.
|}

=== TxImperfections ===
The fifteen transmitter imperfection knobs of [[SimTX API/Packets/TransmitterStart|TransmitterStart]]. Every knob is <code>optional</code>; an unset knob takes the bound rig's value, or the generic HF preset without a rig. They are rendered in-band, around the carrier. [[Advanced Transmitter Settings]] explains what each one does.

<syntaxhighlight lang="protobuf">
message TxImperfections {
  optional float final_drive_db = 1;
  optional float pa_headroom_db = 2;
  optional float audio_compression_db = 3;
  optional float pa_softness = 4;
  optional float pa_am_pm_deg = 5;
  optional float carrier_leak_db = 6;
  optional float opposite_sideband_suppression_db = 7;
  optional float frequency_offset_hz = 8;
  optional float mains_hum_db = 9;
  optional float mains_hum_hz = 10;
  optional float am_modulation_index = 11;
  optional float pa_supply_sag_db = 12;
  optional float tx_noise_floor_db = 13;
  optional float oscillator_phase_noise_db = 14;
  optional float cw_key_rise_ms = 15;
}
</syntaxhighlight>

{| 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.
|}

=== CatalogFile ===
One file of an [[SimTX API/Extension catalog protocol|extension catalog]] entry. Used by [[SimTX API/Packets/CatalogEntry|CatalogEntry]] and [[SimTX API/Packets/CatalogUpload|CatalogUpload]].

<syntaxhighlight lang="protobuf">
message CatalogFile {
  string path = 1;
  string content = 2;
}
</syntaxhighlight>

{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>path</code> || <code>string</code> || Relative path, at most 128 characters, <code>/</code> separators, no empty, <code>.</code> or <code>..</code> segments.
|-
| 2 || <code>content</code> || <code>string</code> || Full text of the file, at most 60,000 bytes of UTF-8.
|}

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