Editing SimTX API/Schema (section)

== session.proto ==
<syntaxhighlight lang="protobuf">
// SimTX wire protocol v25: receiver and transmitter sessions.
syntax = "proto3";

package simtx.v25;

import "simtx/v25/common.proto";

// 0 = INT16: the default sample format.
enum SampleFormat {
  SAMPLE_FORMAT_INT16 = 0;
  SAMPLE_FORMAT_INT8 = 1;
}

// First message after a RECEIVER hello.
message ReceiverStart {
  reserved 2;
  SessionSite site = 1;
  double center_frequency_hz = 3;
  float bandwidth_hz = 4;
  int32 sample_rate = 5;
  int32 chunk_samples = 6;
  optional float noise_figure_db = 7;   // default: rig value, else 6 dB
  bool timestamped = 8;                 // IqBlocks carry first-sample timestamps
  string solo_transmitter_id = 9;       // moderator monitor feature
  Tracking tracking = 10;
  SampleFormat sample_format = 11;
  AntennaAim aim = 12;                  // start pointing; absent = the antenna's stored heading
}

// Nonzero request_id: once the stream runs on the new frequency the server sends SessionStatus
// UPDATED (UPDATE_REASON_RETUNE) echoing it. A retune superseded by a later one before it took
// effect gets no acknowledgement of its own.
message ReceiverRetune {
  double center_frequency_hz = 1;
  int64 request_id = 2;
}

message IqStreamDescriptor {
  int32 sample_rate = 1;           // complex samples per second
  double center_frequency_hz = 2;
  int32 chunk_samples = 3;         // complex samples per IqBlock
  SampleFormat sample_format = 4;
  bool timestamped = 5;
}

// samples: chunk_samples × (I, Q), big-endian int16 (or int8). x = q × scale / 32767 (or / 127).
// Full scale (|x| = 1) is −12 dBm at the receiver input.
// sequence numbers the blocks of one stream: 1 for the first block, +1 for each block after it,
// across retunes. A step larger than 1 means the server dropped blocks for this stream; 0 = the
// sender does not number blocks.
message IqBlock {
  float scale = 1;
  bytes samples = 2;
  int64 first_sample_epoch_seconds = 3;   // timestamped streams only
  int32 first_sample_nanos = 4;
  fixed64 sequence = 5;
}

// First message after a TX_AUDIO / TX_GENERATED hello. An ad-hoc site is only accepted for
// principals holding tx.adhoc (service integrations) or when the server policy allows it.
message TransmitterStart {
  reserved 2;
  SessionSite site = 1;
  string modulation = 3;        // string enum (common.proto)
  double frequency_hz = 4;
  float power_watts = 5;
  string source_type = 6;       // string enum (common.proto)
  int32 sample_rate = 7;
  float audio_gain = 8;
  float bandwidth_hz = 9;
  float audio_low_cut_hz = 10;
  float tone_hz = 11;
  float duty_cycle = 12;
  // Session knobs. With a rig, only final_drive_db, audio_compression_db, frequency_offset_hz and
  // am_modulation_index are taken from here; the rest come from the rig.
  TxImperfections imperfections = 13;
  Tracking tracking = 14;
  AntennaAim aim = 15;          // start pointing; absent = the antenna's stored heading
}

// Transmit samples. Audio sources: mono float samples. GNU_RADIO_IQ: interleaved I, Q floats, or
// compact big-endian int16 pairs (value = q × scale / 32767).
message SampleBlock {
  message CompactIq {
    float scale = 1;
    bytes samples = 2;
  }
  oneof data {
    PackedFloats audio = 1;
    PackedFloats iq = 2;
    CompactIq compact_iq = 3;
  }
}

message PackedFloats {
  repeated float values = 1;
}

message TxModeInfo {
  string mode_name = 1;
  string description = 2;
  float bandwidth_hz = 3;
}

// 0 = UNSPECIFIED. A TxUpdateAck result whose field is UNSPECIFIED or unknown names a field this
// client does not know; ignore it.
enum TxLiveField {
  TX_LIVE_FIELD_UNSPECIFIED = 0;
  TX_LIVE_FIELD_FREQUENCY = 1;
  TX_LIVE_FIELD_POWER = 2;
  TX_LIVE_FIELD_BANDWIDTH = 3;
  TX_LIVE_FIELD_LOW_CUT = 4;
  TX_LIVE_FIELD_FINAL_DRIVE = 5;
  TX_LIVE_FIELD_PA_HEADROOM = 6;
  TX_LIVE_FIELD_AUDIO_COMPRESSION = 7;
  TX_LIVE_FIELD_AUDIO_GAIN = 8;
}

message TxUpdate {
  int64 request_id = 1;
  optional double frequency_hz = 2;
  optional float power_watts = 3;
  optional float bandwidth_hz = 4;
  optional float audio_low_cut_hz = 5;
  optional float final_drive_db = 6;
  optional float pa_headroom_db = 7;
  optional float audio_compression_db = 8;
  optional float audio_gain = 9;
}

message TxUpdateAck {
  message Result {
    TxLiveField field = 1;
    bool accepted = 2;
    double applied_value = 3;
  }
  int64 request_id = 1;
  repeated Result results = 2;
}

message TxQueue {
  int32 ahead = 1;
  int32 total = 2;
}

// On air: start streaming. Refusals and kicks arrive as SessionStatus REJECTED / ENDED.
message TxAccept {}

message TxTelemetry {
  int64 sequence = 1;
  int64 server_time_ms = 2;
  double actual_frequency_hz = 3;
  float requested_power_watts = 4;
  float forward_power_watts = 5;
  float delivered_power_watts = 6;
  float reflected_power_watts = 7;
  float vswr = 8;
  float mismatch_loss_db = 9;
  float transformer_loss_db = 10;
  float foldback_loss_db = 11;
  float alc_db = 12;
  float buffer_seconds = 13;
  float finals_temperature_c = 14;
  float thermal_foldback_db = 15;
  float pa_compression_db = 16;
  float pa_heat_watts = 17;
  float pa_efficiency_percent = 18;
  bool pa_thermal_fault_active = 19;
}

// Steer a station-bound session's antenna / Doppler tracking without reconnecting.
message AntennaPointingUpdate {
  int64 request_id = 1;
  PointingMode mode = 2;
  float azimuth_deg = 3;
  float elevation_deg = 4;
  Tracking tracking = 5;
}

// The station a session is attached to, as the server resolved it. core.kind is GROUND or
// SATELLITE; core.location is the site (ground) or the sub-satellite point when the status was sent.
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
}

// Required: decoders reject UNSPECIFIED (and values they do not know).
enum SessionState {
  SESSION_STATE_UNSPECIFIED = 0;
  SESSION_STATE_BOUND = 1;      // request accepted; TxQueue/TxAccept or IqStreamDescriptor follow
  SESSION_STATE_REJECTED = 2;   // the connection closes after this
  SESSION_STATE_ENDED = 3;      // ended by the server (kick, station deleted, deorbit); connection closes
  SESSION_STATE_UPDATED = 4;    // the session keeps running with a changed state; see update_reason
}

// Why a session was UPDATED. A status carries the most significant cause; the snapshot fields
// carry everything that changed. 0 = UNSPECIFIED: not an UPDATED status. On an UPDATED status
// UNSPECIFIED or a reason the client does not know means "apply the snapshot fields".
enum UpdateReason {
  UPDATE_REASON_UNSPECIFIED = 0;
  UPDATE_REASON_POINTING = 1;           // this session's AntennaPointingUpdate was applied (request_id)
  UPDATE_REASON_TRACKING = 2;           // the server changed tracking (target gone or deorbited)
  UPDATE_REASON_STATION_EDIT = 3;       // the station, its antenna or its rig was edited (revisions)
  UPDATE_REASON_ORBIT_CHANGE = 4;       // the bound satellite's elements or attitude changed
  UPDATE_REASON_DEORBIT_SCHEDULED = 5;  // the bound satellite will deorbit (station.core.deorbit)
  UPDATE_REASON_RETUNE = 6;             // this session's ReceiverRetune took effect (request_id)
}

// Sent to every RX and TX session: once before the stream starts (BOUND), on every change the
// session survives (UPDATED, protocol revision >= 1 for station changes) and when it stops
// (REJECTED, ENDED). REJECTED and ENDED are the only refusal / kick signal, for RX and TX alike;
// they carry `code` and `reason` and the connection closes after them. BOUND and UPDATED describe
// the session as the server now runs it:
// - station: always set on BOUND of a station-bound session. On UPDATED it is set whenever the
//   station changed (STATION_EDIT, ORBIT_CHANGE, DEORBIT_SCHEDULED) and replaces the client's copy
//   as a whole; unset on UPDATED means unchanged. Statuses arrive in order on one connection.
// - frequency_hz, tracking, pointing: the current values; unset tracking / pointing = none.
// Edits a session cannot follow (station deleted, its antenna or rig removed, access revoked)
// still end it with ENDED.
message SessionStatus {
  SessionState state = 1;
  string reason = 2;
  ErrorCode code = 3;
  bytes session_id = 4;          // per-connection id (the transmission id for TX)
  BoundStation station = 5;      // unset for ad-hoc sessions
  double frequency_hz = 6;
  Tracking tracking = 7;
  AntennaPointing pointing = 8;
  int64 request_id = 9;          // echoes AntennaPointingUpdate / ReceiverRetune request_id
  UpdateReason update_reason = 10;  // UPDATED only
}
</syntaxhighlight>