Editing SimTX API/Schema (section)

== common.proto ==
<syntaxhighlight lang="protobuf">
// SimTX wire protocol v25: shared types.
//
// Conventions
// - UUIDs are 16-byte big-endian `bytes` (most significant half first); empty = none.
// - Frequencies are double Hz. `*_ms` fields are Unix milliseconds.
//
// Enum zero values. An omitted enum field reads as 0, so 0 never grants or asserts anything:
// - Most enums start with `*_UNSPECIFIED = 0`. Where the field is required, decoders reject
//   UNSPECIFIED (IpModerationAction, SessionState, Role, and StationKind wherever a persistent
//   station is meant); elsewhere each enum says how 0 is read.
// - A few have a real value at 0, the default, documented on each:
//   AuthKind ANONYMOUS, AntennaMount FIXED, PointingMode FIXED, SpinAxis ORBIT_NORMAL,
//   StationKind ADHOC, StationVisibility UNLISTED, SampleFormat INT16, BannerLevel INFO.
//
// String-valued enums travel as upper-case ASCII names, compared exactly. A peer that does not
// know a name refuses it (Error INVALID_REQUEST naming the value). This list is the reference;
// other comments point here.
//   modulation    AM_DSB_FC AM_DSB_SC USB LSB CW NFM WFM IQ WSPR FT8
//                 (TransmitterStart, CoverageMapRequest, LiveSession, TransmitterHealth,
//                 TransmitterImpact; empty in LiveSession for receivers)
//   source type   AUDIO_STREAM MICROPHONE WHITE_NOISE PIPEWIRE GNU_RADIO_IQ
//                 (TransmitterStart.source_type, TransmitterHealth.source_type)
//   antenna type  DIPOLE VERTICAL YAGI_3EL YAGI_5EL LOOP BEVERAGE LONGWIRE INVERTED_V
//                 EFHW_32M_49_1 MONOPOLE TURNSTILE CROSSED_YAGI HELIX (AntennaConfig.type)
//   weather type  DUCT_STRENGTH RAIN_RATE CLOUD_WATER SURFACE_TEMPERATURE LIGHTNING_RATE
//                 (WeatherMapRequest.type, WeatherMapResponse.type)
//   duct type     NONE SURFACE ELEVATED (WeatherMapResponse.duct_type)
//   catalog type  MODULATION AUDIO_ADDON THEME ACTION LIBRARY PRESET (CatalogEntrySummary.types)
syntax = "proto3";

package simtx.v25;

message GeoPoint {
  double latitude_deg = 1;
  double longitude_deg = 2;
  double altitude_meters = 3;
}

// 0 = FIXED: the safe default, an antenna without a rotator.
enum AntennaMount {
  ANTENNA_MOUNT_FIXED = 0;
  ANTENNA_MOUNT_AZ = 1;
  ANTENNA_MOUNT_AZEL = 2;
}

// 0 = FIXED: hold the given azimuth / elevation; nothing is tracked unless asked for.
enum PointingMode {
  POINTING_MODE_FIXED = 0;
  POINTING_MODE_TRACK = 1;
}

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;
}

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;
}

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;
}

// 0 = ORBIT_NORMAL: the usual spin-stabilised axis and the account service's default.
enum SpinAxis {
  SPIN_AXIS_ORBIT_NORMAL = 0;
  SPIN_AXIS_NADIR = 1;
  SPIN_AXIS_VELOCITY = 2;
}

// No mode set = nadir pointing with yaw 0.
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;
  }
}

// 0 = ADHOC: no persistent station. Only a StationList entry may be ADHOC; decoders reject it
// wherever a persistent station is meant (BoundStation).
enum StationKind {
  STATION_KIND_ADHOC = 0;
  STATION_KIND_GROUND = 1;
  STATION_KIND_SATELLITE = 2;
}

// 0 = UNLISTED: the private default; a station is public only when it says so.
enum StationVisibility {
  STATION_VISIBILITY_UNLISTED = 0;
  STATION_VISIBILITY_PUBLIC = 1;
}

// The fields every view of a persistent station shares. Embedded as `core` by Station (control
// list) and BoundStation (session); each adds only its own fields.
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
}

// Which persistent station (and which of its antennas / rigs) a session uses.
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
}

// Inline station for anonymous / ad-hoc sessions (no account-owned station).
message AdhocStation {
  string callsign = 1;
  GeoPoint location = 2;
  AntennaConfig antenna = 3;
}

// Where a session (or a coverage prediction) sits. Exactly one member; neither is refused.
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)
  }
}

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;
}

// Where a session's antenna points when it starts (ReceiverStart / TransmitterStart `aim`), e.g. to
// reconnect already pointed at a manual heading.
// - Absent: the antenna's stored heading.
// - FIXED mount: ignored; the BOUND status's `pointing` reports the effective pointing.
// - AZ mount: elevation_deg is ignored.
// - With tracking.point_antenna: the rotator's position when the session starts; it slews from there
//   toward the target.
// Checked like AntennaPointingUpdate: finite numbers, elevation -90..90, azimuth normalised to [0, 360).
message AntennaAim {
  float azimuth_deg = 1;
  float elevation_deg = 2;
}

message Deorbit {
  int64 burn_at_ms = 1;
  int64 reentry_at_ms = 2;
  GeoPoint reentry_point = 3;
  double delta_v_mps = 4;
}

message StationLimits {
  int32 max_sessions = 1;
  int32 max_transmitters = 2;
  int32 max_receivers = 3;
}

// The 15 transmitter imperfection knobs. Unset = default (rig value, or the generic HF preset).
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;
}

message RigProfile {
  bytes rig_id = 1;
  int64 revision = 2;
  string name = 3;
  float pa_max_watts = 4;
  float noise_figure_db = 5;
  TxImperfections tx = 6;
}

// The one error model: every failure is `Error {code, message, request_id}` (frames.proto), a
// SessionStatus REJECTED / ENDED with `code` and `reason`, or a non-ACCEPTED ServerHello. 0 =
// UNSPECIFIED: no specific code (an ENDED session that simply ended); clients treat unknown codes
// the same way.
enum ErrorCode {
  ERROR_CODE_UNSPECIFIED = 0;
  ERROR_CODE_INVALID_REQUEST = 1;
  ERROR_CODE_UNAUTHENTICATED = 2;
  ERROR_CODE_FORBIDDEN = 3;
  ERROR_CODE_NOT_FOUND = 4;
  ERROR_CODE_LIMIT_REACHED = 5;
  ERROR_CODE_RATE_LIMITED = 6;
  ERROR_CODE_UNAVAILABLE = 7;
  ERROR_CODE_STATION_INACTIVE = 8;
  ERROR_CODE_STATION_REQUIRED = 9;
  ERROR_CODE_INTERNAL = 10;
  ERROR_CODE_CANCELLED = 11;   // superseded by a newer request of the same kind (coverage maps)
}
</syntaxhighlight>

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