Editing SimTX API/Schema (section)

== control.proto ==
<syntaxhighlight lang="protobuf">
// SimTX wire protocol v25: control channel (station lists, maps, catalog, satellites).
// Every request carries a nonzero request_id that its response echoes. A request that fails gets
// `Error {code, message, request_id}` (frames.proto) instead of its response; responses describe
// success only.
syntax = "proto3";

package simtx.v25;

import "simtx/v25/common.proto";

message ListStations {
  int64 request_id = 1;
  bool include_sessions = 2;
}

// 0 = UNSPECIFIED: a session whose role the client does not know; show it without a role.
enum SessionRole {
  SESSION_ROLE_UNSPECIFIED = 0;
  SESSION_ROLE_TX = 1;
  SESSION_ROLE_RX = 2;
}

message LiveSession {
  bytes session_id = 1;
  SessionRole role = 2;
  bytes antenna_id = 3;
  string callsign = 4;
  double frequency_hz = 5;
  string modulation = 6;       // string enum (common.proto); empty for receivers
  float power_watts = 7;
  float bandwidth_hz = 8;
  string address = 9;          // moderation sessions only
  GeoPoint location = 10;      // where the session's antenna is right now
}

// A persistent station (with any live sessions), a satellite with nobody attached, or an ad-hoc
// session (core.kind ADHOC, core.station_id empty, exactly one session). For satellites
// core.location is the sub-satellite point at captured_at_ms.
message Station {
  StationCore core = 1;
  repeated LiveSession sessions = 2;
}

message StationList {
  int64 request_id = 1;
  int64 captured_at_ms = 2;
  repeated Station stations = 3;
}

// Own-TX monitor. Success: MonitorAck (active = true), then MonitorBlocks. Failure: Error
// (NOT_FOUND: no live transmitter with that id; FORBIDDEN: not yours).
message StartMonitor { bytes session_id = 1; int64 request_id = 2; }
// Answered by MonitorAck (active = false), also when that monitor was not running.
message StopMonitor { bytes session_id = 1; int64 request_id = 2; }

message MonitorAck {
  int64 request_id = 1;
  bytes session_id = 2;
  bool active = 3;             // true: the monitor runs; false: it is stopped
}

message MonitorBlock {
  bytes session_id = 1;
  int32 sample_rate = 2;
  repeated float iq = 3;       // interleaved I, Q
}

// The server ended a running monitor (the transmitter went off the air).
message MonitorEnd {
  bytes session_id = 1;
  string reason = 2;
}

message WeatherMapRequest {
  int64 request_id = 1;
  double center_latitude_deg = 2;
  double center_longitude_deg = 3;
  double latitude_span_deg = 4;
  double longitude_span_deg = 5;
  int32 width = 6;
  int32 height = 7;
  string type = 8;             // weather type (string enum, common.proto)
}

message WeatherMapResponse {
  int64 request_id = 1;
  int64 valid_time_ms = 2;
  string type = 3;             // weather type (string enum, common.proto)
  double south_latitude_deg = 4;
  double north_latitude_deg = 5;
  double west_longitude_deg = 6;
  double east_longitude_deg = 7;
  int32 width = 8;
  int32 height = 9;
  repeated float values = 10;
  float surface_temperature_celsius = 11;
  float surface_pressure_hpa = 12;
  float surface_relative_humidity_percent = 13;
  float surface_wind_meters_per_second = 14;
  float maximum_rain_rate_millimeters_per_hour = 15;
  float maximum_cloud_water_grams_per_cubic_meter = 16;
  float cape_joules_per_kilogram = 17;
  float lightning_flashes_per_minute = 18;
  string duct_type = 19;       // duct type (string enum, common.proto)
  float duct_base_meters = 20;
  float duct_top_meters = 21;
  float duct_strength_m_units = 22;
  float duct_gradient_m_units_per_kilometer = 23;
}

message ServerHealthRequest { int64 request_id = 1; }

message TransmitterHealth {
  bytes session_id = 1;
  string callsign = 2;
  string address = 3;
  string source_type = 4;      // string enum (common.proto)
  double frequency_hz = 5;
  string modulation = 6;       // string enum (common.proto)
  int32 sample_rate = 7;
  int32 buffer_capacity_samples = 8;
  int32 buffer_retained_samples = 9;
  int64 buffer_sequence = 10;
  int64 wire_components_received = 11;
  int64 processed_blocks = 12;
  int64 total_processing_nanos = 13;
  int64 connected_duration_nanos = 14;
  int64 last_progress_age_nanos = 15;
  int64 recent_processing_nanos = 16;
  int64 max_processing_nanos = 17;
  int64 current_write_stall_nanos = 18;
  int64 recent_write_nanos = 19;
  int64 max_write_nanos = 20;
  int64 total_write_nanos = 21;
}

message ReceiverHealth {
  bytes session_id = 1;
  string callsign = 2;
  string address = 3;
  double center_frequency_hz = 4;
  int32 sample_rate = 5;
  int32 chunk_samples = 6;
  bool wideband = 7;
  int32 shared_group_members = 8;
  int32 queued_frames = 9;
  int32 max_queued_frames = 10;
  int32 queue_capacity = 11;
  int64 frames_written = 12;
  int64 frames_dropped = 13;
  int64 group_processed_chunks = 14;
  int64 total_group_processing_nanos = 15;
  int64 total_group_dsp_nanos = 16;
  int64 connected_duration_nanos = 17;
  int64 group_progress_age_nanos = 18;
  int64 recent_group_processing_nanos = 19;
  int64 max_group_processing_nanos = 20;
  int64 recent_group_dsp_nanos = 21;
  int64 max_group_dsp_nanos = 22;
  int64 current_write_stall_nanos = 23;
  int64 recent_write_nanos = 24;
  int64 max_write_nanos = 25;
  int64 total_write_nanos = 26;
}

message ServerHealthReport {
  int64 request_id = 1;
  int64 captured_at_ms = 2;
  string status = 3;
  int64 uptime_ms = 4;
  int32 available_processors = 5;
  float process_cpu_load = 6;
  float system_cpu_load = 7;
  double system_load_average = 8;
  int64 process_cpu_time_nanos = 9;
  int64 heap_used_bytes = 10;
  int64 heap_committed_bytes = 11;
  int64 heap_max_bytes = 12;
  int64 non_heap_used_bytes = 13;
  int64 physical_memory_used_bytes = 14;
  int64 physical_memory_total_bytes = 15;
  int64 open_file_descriptors = 16;
  int64 max_file_descriptors = 17;
  int32 live_threads = 18;
  int32 peak_threads = 19;
  int32 connected_clients = 20;
  int32 connected_stations = 21;
  int32 active_transmitters = 22;
  int32 receiver_groups = 23;
  bool acceptor_alive = 24;
  int64 world_tick = 25;
  int64 world_tick_duration_nanos = 26;
  int64 world_tick_interval_nanos = 27;
  int64 simulation_time_ms = 28;
  int32 session_tasks_active = 29;
  int32 session_tasks_queued = 30;
  int32 receiver_dsp_active = 31;
  int32 receiver_dsp_queued = 32;
  int32 propagation_jobs_active = 33;
  int32 propagation_jobs_queued = 34;
  int64 streamed_receiver_chunks = 35;
  int64 receiver_overrun_chunks = 36;
  int32 stalled_transmitter_writes = 37;
  int32 stalled_receiver_groups = 38;
  repeated TransmitterHealth transmitters = 39;
  repeated ReceiverHealth receivers = 40;
}

// Failures: Error (UNAVAILABLE: disabled or busy; CANCELLED: superseded by a newer coverage
// request on this connection).
message CoverageMapRequest {
  reserved 3;
  int64 request_id = 1;
  SessionSite site = 2;        // ad-hoc: the callsign is ignored
  string modulation = 4;       // string enum (common.proto)
  double frequency_hz = 5;
  float power_watts = 6;
  float bandwidth_hz = 7;
  int32 width = 8;
  int32 height = 9;
}

message CoverageMapResponse {
  reserved 2, 3;
  int64 request_id = 1;
  int64 sim_time_ms = 4;
  int32 width = 5;
  int32 height = 6;
  repeated float received_power_dbm = 7;
}

message CatalogFile {
  string path = 1;
  string content = 2;
}

message CatalogDependency {
  string id = 1;
  string version_range = 2;
}

message CatalogEntrySummary {
  int32 id = 1;
  string kind = 2;
  string name = 3;
  string description = 4;
  string author = 5;
  int32 size_bytes = 6;
  int32 file_count = 7;
  repeated string types = 8;       // catalog types (string enum, common.proto)
  repeated string categories = 9;
  string package_id = 10;
  string package_version = 11;
  repeated CatalogDependency dependencies = 12;
  int32 revision = 13;
  int64 uploaded_at_ms = 14;
}

message CatalogListRequest { int64 request_id = 1; }
message CatalogList { int64 request_id = 1; repeated CatalogEntrySummary entries = 2; }
// Unknown entry: Error NOT_FOUND.
message CatalogFetch { int64 request_id = 1; int32 entry_id = 2; }
message CatalogEntry {
  reserved 3;
  int64 request_id = 1;
  int32 entry_id = 2;
  string kind = 4;
  string name = 5;
  int32 revision = 6;
  repeated CatalogFile files = 7;
}
message CatalogUpload {
  int64 request_id = 1;
  string kind = 2;
  string name = 3;
  string description = 4;
  repeated string categories = 5;
  repeated CatalogFile files = 6;
}
// Refused uploads and deletes: Error (FORBIDDEN, INVALID_REQUEST, NOT_FOUND, LIMIT_REACHED,
// UNAVAILABLE, INTERNAL) with the reason in message.
message CatalogUploadResult {
  reserved 2, 3;
  int64 request_id = 1;
  int32 entry_id = 4;
  bool updated = 5;            // true: replaced your existing publication of that name
}
message CatalogDelete { int64 request_id = 1; int32 entry_id = 2; }
message CatalogDeleteResult {
  reserved 2, 3;
  int64 request_id = 1;
  int32 entry_id = 4;
}

// 0 = INFO: the safe default; an unknown level is shown as INFO.
enum BannerLevel {
  BANNER_LEVEL_INFO = 0;
  BANNER_LEVEL_BAN_NOTICE = 1;
}

message Banner {
  BannerLevel level = 1;
  string text = 2;
  int64 expires_at_ms = 3;     // 0 = no expiry
}

// Failures (unknown or invisible satellite, bad window, busy): Error with this request_id.
message EphemerisRequest {
  int64 request_id = 1;
  bytes station_id = 2;
  int64 from_ms = 3;
  int64 to_ms = 4;
  int32 step_seconds = 5;      // >= 1; at most 3600 samples
}

message EphemerisSample {
  int64 t_ms = 1;
  double latitude_deg = 2;
  double longitude_deg = 3;
  double altitude_meters = 4;
  double x = 5;                // ECEF metres (6371 km sphere)
  double y = 6;
  double z = 7;
}

message EphemerisResponse {
  reserved 4;
  int64 request_id = 1;
  bytes station_id = 2;
  repeated EphemerisSample samples = 3;
}

// Failures: Error with this request_id, as for EphemerisRequest.
message PassPredictionRequest {
  int64 request_id = 1;
  bytes satellite_id = 2;
  oneof observer_site {
    bytes observer_station_id = 3;
    GeoPoint observer = 4;
  }
  int64 from_ms = 5;
  int64 to_ms = 6;             // at most 7 days after from_ms
  double min_elevation_deg = 7;
  double frequency_hz = 8;     // for max Doppler; 0 = skip
}

message Pass {
  int64 aos_ms = 1;
  int64 tca_ms = 2;
  int64 los_ms = 3;
  double max_elevation_deg = 4;
  double aos_azimuth_deg = 5;
  double los_azimuth_deg = 6;
  double max_doppler_hz = 7;
}

message PassPredictionResponse {
  reserved 4;
  int64 request_id = 1;
  bytes satellite_id = 2;
  repeated Pass passes = 3;
}

// Moderation (role MODERATION). Failures: Error with the request's request_id.
message KickRequest { int64 request_id = 1; string target = 2; string reason = 3; bool by_callsign = 4; }
message KickResult { int64 request_id = 1; int32 sessions_kicked = 2; }
// Required: decoders reject UNSPECIFIED, so an omitted action never bans.
enum IpModerationAction {
  IP_MODERATION_ACTION_UNSPECIFIED = 0;
  IP_MODERATION_ACTION_UNBAN = 1;
  IP_MODERATION_ACTION_BAN = 2;
}
message IpModerationRequest {
  int64 request_id = 1;
  IpModerationAction action = 2;
  string target = 3;
  string reason = 4;
  int64 duration_seconds = 5;
}
message IpModerationResult {
  int64 request_id = 1;
  bool banned = 2;
  repeated string addresses = 3;
  int32 sessions_disconnected = 4;
  int64 expires_at_ms = 5;
}
message BroadcastBanner { int64 request_id = 1; string text = 2; int64 duration_seconds = 3; }
message TransmitterImpact {
  bytes session_id = 1;
  string callsign = 2;
  string address = 3;
  double frequency_hz = 4;
  string modulation = 5;       // string enum (common.proto)
  float power_watts = 6;
  float occupied_bandwidth_hz = 7;
  float impact_score = 8;
  int32 affected_receivers = 9;
  float nearest_receiver_km = 10;
  string reasons = 11;
}
message StationImpactList { int64 request_id = 1; repeated TransmitterImpact impacts = 2; }
</syntaxhighlight>