ados_protocol/
contracts.rs

1// @generated by ados-capabilities-codegen from contracts.toml. Do not edit by hand.
2//! Generated IPC contract + sidecar version registry.
3//!
4//! One source of truth for every IPC wire-contract version integer
5//! and every state-sidecar version, for Rust, Python, and TS.
6//! Source: contracts.toml; run ados-capabilities-codegen.
7
8/// Version and wire metadata for one IPC contract or state sidecar.
9#[derive(Debug, Clone, Copy, PartialEq, Eq)]
10pub struct ContractMeta {
11    pub id: &'static str,
12    pub version: u16,
13    pub wire: &'static str,
14    pub transport: &'static str,
15    pub status: &'static str,
16    pub description: &'static str,
17}
18
19/// Every versioned inter-process wire contract.
20#[rustfmt::skip]
21pub const CONTRACTS: &[ContractMeta] = &[
22    ContractMeta { id: "plugin.rpc", version: 1, wire: "msgpack", transport: "unix-stream", status: "active", description: "Plugin RPC envelope: msgpack short-key request/response plus a pipe-delimited HMAC-SHA256 capability token." },  // ados_protocol::plugin::PROTOCOL_VERSION
23    ContractMeta { id: "logd.ingest", version: 1, wire: "msgpack", transport: "unix-socket", status: "active", description: "Black-box ingest frames: logs, telemetry, discrete events, and hardware snapshots." },  // ados_protocol::logd::WIRE_VERSION
24    ContractMeta { id: "logd.read", version: 1, wire: "json", transport: "http", status: "active", description: "Black-box read-API request and response envelope." },  // ados_protocol::logd::ENVELOPE_VERSION
25    ContractMeta { id: "framebus.ring", version: 1, wire: "binary", transport: "shared-memory", status: "active", description: "Shared-memory vision frame ring layout: a header plus seqlock-guarded slots." },  // ados_protocol::framebus::RingLayout::VERSION
26    ContractMeta { id: "framebus.descriptor", version: 2, wire: "msgpack", transport: "event-bus", status: "active", description: "The small vision.frame descriptor naming a ring slot and its frame geometry. v2 replaces ts_ms with ts_ns (host monotonic, exposure-mid when known) and adds ts_sensor_ns, exposure_ns, trigger_seq, timebase and the Gray8/Gray16/Bayer formats." },  // ados_protocol::framebus::FRAMEBUS_DESCRIPTOR_VERSION
27    ContractMeta { id: "tap.frame", version: 2, wire: "binary", transport: "unix-stream", status: "active", description: "Vision-tap frame header (ADVT magic) between the video pipeline and the vision engine. v2 adds ts_mono_ns, the host monotonic arrival time of the frame." },  // ados_protocol::tap::TAP_CONTRACT_VERSION
28    ContractMeta { id: "vision.detection", version: 3, wire: "msgpack", transport: "event-bus", status: "active", description: "Self-describing detection/percept batches published on the vision.detection topic (v2 adds optional mask, keypoints, depth, world position, and an optional 2D box; v3 stamps ts_ms from the frame's host monotonic clock, not wall-clock)." },
29    ContractMeta { id: "state.v2", version: 4, wire: "msgpack", transport: "unix-stream", status: "active", description: "Length-prefixed msgpack vehicle-state frame (the current state-socket format). v3 added position_age_ms (how long since the flight controller's last decoded POSITION, read by the swarm beacon's suppression gate). v4 publishes a not-reported reading (battery voltage/current/remaining/temperature, GPS eph/epv, RC rssi) as null instead of the MAVLink sentinel. The runtime extras carry `fc_system_id`/`fc_component_id` once the FC heartbeat is latched." },
30    ContractMeta { id: "frame", version: 0, wire: "binary", transport: "unix-stream", status: "metadata", description: "The 4-byte big-endian length transport primitive shared by plugin.rpc, the MAVLink socket, and state.v2. No version of its own." },
31    ContractMeta { id: "mavlink.socket", version: 2, wire: "binary", transport: "unix-stream", status: "active", description: "MAVLink frame broadcast socket. v2 prefixes every frame the router fans out with an 8-byte little-endian rx_mono_ns (host CLOCK_MONOTONIC when the router read it); frames written by clients carry no header. MAVLink framing itself defers to external MAVLink v1/v2." },  // ados_protocol::mavlink_socket::MAVLINK_SOCKET_VERSION
32    ContractMeta { id: "mavlink.ingest", version: 0, wire: "binary", transport: "unix-stream", status: "metadata", description: "Off-board MAVLink frames into a node's republish fan-out; the opposite direction to mavlink.socket, and versioned by external MAVLink v1/v2 the same way." },
33    ContractMeta { id: "aux.frame", version: 1, wire: "binary", transport: "udp", status: "active", description: "Auxiliary radio lane multiplex header (magic, version, channel, length) letting MAVLink, status, and identity share one datagram pipe." },  // ados_protocol::aux_mux::AUX_VERSION
34    ContractMeta { id: "aux.node_status", version: 2, wire: "msgpack", transport: "udp", status: "active", description: "Compact node status and identity carried on the auxiliary lane's status and identity channels, so a ground station can describe the node it relays." },  // ados_protocol::node_status::NODE_STATUS_VERSION
35    ContractMeta { id: "aux.link_feedback", version: 1, wire: "binary", transport: "udp", status: "active", description: "Ground-measured video-link quality reported back to the transmitting drone, so its adaptive bitrate ladder steps on a real loss sample instead of the sentinel a transmit-only radio can never leave." },  // ados_protocol::link_feedback::LINK_FEEDBACK_VERSION
36    ContractMeta { id: "state.v1", version: 1, wire: "newline-json", transport: "unix-stream", status: "metadata", description: "Legacy newline-terminated JSON vehicle-state frame; superseded by state.v2. No on-wire version integer." },
37    ContractMeta { id: "ws_ticket", version: 1, wire: "string", transport: "websocket-subprotocol", status: "metadata", description: "String-tagged (v2) single-use HMAC-SHA256 WebSocket auth ticket; the version is a string tag, not a wire integer." },  // ados_protocol::ws_ticket::TICKET_KEY_LABEL
38    ContractMeta { id: "cloud-publish", version: 1, wire: "msgpack", transport: "unix-stream", status: "active", description: "Plugin data leaving the node through the cloud relay: the plugin host forwards a gated stream message (QoS 0 broker publish) or keyed JSON record (cloud record upsert) to ados-cloud over a root-only socket, one length-prefixed msgpack request and reply per exchange." },  // ados_protocol::cloud_publish::CLOUD_PUBLISH_VERSION
39    ContractMeta { id: "sensor.v1", version: 1, wire: "msgpack", transport: "unix-stream", status: "active", description: "The sensor bus (seam J): length-prefixed msgpack frames {v, kind, src, origin, payload} brokered by ados-clock on sensors.sock. clock/imu/gnss/trigger payloads are the capture contract ados.capture.v1 protobuf messages, with every t_ns on the host monotonic clock; baro, mag and sync are msgpack; rtcm is raw RTCM3 bytes toward the receivers." },  // ados_sensorbus::SENSOR_BUS_VERSION
40];
41
42/// Every versioned on-disk state sidecar. The file path is carried in
43/// `transport` and the status is `sidecar`.
44#[rustfmt::skip]
45pub const SIDECARS: &[ContractMeta] = &[
46    ContractMeta { id: "cloud-link", version: 1, wire: "json", transport: "/run/ados/cloud-link.json", status: "sidecar", description: "Cloud relay link state: broker session confirmed up, and the outcome of the last agent status POST." },  // ados_protocol::cloud_link::CLOUD_LINK_SIDECAR
47    ContractMeta { id: "offload-link", version: 1, wire: "json", transport: "/run/ados/offload-link.json", status: "sidecar", description: "Drone perception offload-link state: a paired reachable workstation the drone is offloading to, feeding the perception-tier decision." },  // ados_protocol::offload_link::OFFLOAD_LINK_SIDECAR
48    ContractMeta { id: "wfb-stats", version: 2, wire: "json", transport: "/run/ados/wfb-stats.json", status: "sidecar", description: "WFB link statistics: RSSI, packet counters, derived link state, and per-adapter receive counters with the diversity block." },  // ados_protocol::paths::WFB_STATS_JSON
49    ContractMeta { id: "hop-supervisor", version: 1, wire: "json", transport: "/run/ados/hop-supervisor.json", status: "sidecar", description: "FHSS hop-supervisor state." },  // ados_radio::paths::HOP_SUPERVISOR_JSON
50    ContractMeta { id: "peer-presence", version: 1, wire: "json", transport: "/run/ados/peer-presence.json", status: "sidecar", description: "The drone's view of its one ground peer from the presence beacon: the peer's channel and when it was last heard." },  // ados_radio::paths::PEER_PRESENCE_JSON
51    ContractMeta { id: "mgmt-link", version: 1, wire: "json", transport: "/run/ados/mgmt-link.json", status: "sidecar", description: "Management-link guardian state." },
52    ContractMeta { id: "mgmt-failover", version: 1, wire: "json", transport: "/run/ados/mgmt-failover.json", status: "sidecar", description: "Management-link reach-back mode: primary, wifi_heartbeat, or none, with the failover interface and reason." },
53    ContractMeta { id: "usb-rehome", version: 1, wire: "json", transport: "/run/ados/usb-rehome.json", status: "sidecar", description: "USB-rehome self-heal state for a WFB adapter on a slow USB port: the recovery state, attempt count, and last outcome." },
54    ContractMeta { id: "wifi-powersave", version: 1, wire: "json", transport: "/run/ados/wifi-powersave.json", status: "sidecar", description: "WiFi power-save runtime reconciler state per station interface." },
55    ContractMeta { id: "wfb_failover", version: 1, wire: "json", transport: "/run/ados/wfb_failover.json", status: "sidecar", description: "Local-bind to cloud-relay failover state." },
56    ContractMeta { id: "wfb-pair-proof", version: 1, wire: "json", transport: "/var/lib/ados/wfb-pair-proof.json", status: "sidecar", description: "Per-key WFB pair proof: whether a radio key's fingerprint has ever been confirmed to carry a link, plus the bounded auto-pair re-arm budget. Persistent, so the budget survives a reboot." },  // ados_protocol::pair_proof::PAIR_PROOF_SIDECAR_VERSION
57    ContractMeta { id: "bind-state", version: 1, wire: "json", transport: "/run/ados/bind-state.json", status: "sidecar", description: "WFB bind-session sentinel and precheck result." },  // ados_radio::paths::BIND_STATE_SENTINEL
58    ContractMeta { id: "crsf-stats", version: 2, wire: "json", transport: "/run/ados/crsf-stats.json", status: "sidecar", description: "CRSF RC-lane state and link statistics: lane state, RSSI/LQ/SNR, frame rates, and the received-side liveness verdict. v2 adds modules[]: one entry per configured RC module with its role, port, link statistics and reported ELRS domain." },  // ados_crsf::paths::CRSF_STATS_JSON
59    ContractMeta { id: "lora", version: 1, wire: "json", transport: "/run/ados/lora.json", status: "sidecar", description: "LoRa lane state: transport, module band, resolved region and plan, channel and power, the governor's per-rule state (duty, dwell, listen-before-talk, power), TX/RX counters and the Meshtastic bridge." },  // ados_lora_service::paths::LORA_JSON
60    ContractMeta { id: "lora-beacons", version: 1, wire: "json", transport: "/run/ados/lora-beacons.json", status: "sidecar", description: "Beacons heard on the LoRa lane, newest first, capped at 100." },  // ados_lora_service::paths::LORA_BEACONS_JSON
61    ContractMeta { id: "tunnel-config", version: 1, wire: "json", transport: "/run/ados/tunnel-config.json", status: "sidecar", description: "Config-over-radio channel state: role (terminator/injector), enable + write gates, local bearer ports, and received-side frame/request/response/reject/timeout counters." },  // ados_config_tunnel::paths::TUNNEL_CONFIG_STATS_JSON
62    ContractMeta { id: "relayed-status", version: 1, wire: "json", transport: "/run/ados/relayed-status.json", status: "sidecar", description: "Nodes a ground station relays, as they describe themselves over the radio auxiliary lane: identity, a compact status snapshot, and the arrival time of each so a reader can tell fresh from stale." },  // ados_groundlink::aux_peers::AUX_PEERS_SIDECAR_VERSION
63    ContractMeta { id: "linked-peers", version: 1, wire: "json", transport: "/run/ados/linked-peers.json", status: "sidecar", description: "The drones a ground station currently links, one entry per peer with its own last-seen time; each entry carries its own freshness, so the file has no single window." },  // ados_groundlink::paths::LINKED_PEERS_JSON
64    ContractMeta { id: "mesh-state", version: 1, wire: "json", transport: "/run/ados/mesh-state.json", status: "sidecar", description: "Mesh role and membership state." },  // ados_groundlink::paths::MESH_STATE_JSON
65    ContractMeta { id: "wfb-relay", version: 1, wire: "json", transport: "/run/ados/wfb-relay.json", status: "sidecar", description: "Relay-role fragment counters a relay ground station forwards to its receiver." },  // ados_groundlink::paths::WFB_RELAY_JSON
66    ContractMeta { id: "wfb-receiver", version: 1, wire: "json", transport: "/run/ados/wfb-receiver.json", status: "sidecar", description: "Receiver-role per-relay counters and the combined FEC output statistics." },  // ados_groundlink::paths::WFB_RECEIVER_JSON
67    ContractMeta { id: "fleet-hero", version: 1, wire: "json", transport: "/run/ados/fleet-hero.json", status: "sidecar", description: "The fleet hero a ground station shows: the selected drone, stamped on every decision and read back by the video fan-out on a slow poll." },  // ados_groundlink::fleet_hero::FLEET_HERO_JSON
68    ContractMeta { id: "camera-state", version: 2, wire: "json", transport: "/run/ados/camera-state.json", status: "sidecar", description: "Camera discovery readiness AND the streaming pipeline's outcome for that camera, so a detected camera can never read as a streaming one. Keys: version, state, primary_path, primary_name, total_cameras, pipeline_state (unknown|starting|streaming|error|stopped; streaming only once mediamtx holds the encoder's publisher on main, starting while the encoder is spawned but has not published), pipeline_reason (set only on error), encoder (rpicam-vid, or <ffmpeg|gstreamer>-<codec element> e.g. ffmpeg-h264_v4l2m2m / ffmpeg-libx264), encoder_hw, encoder_forced_software (the hardware encoder failed and the next start is pinned to the software encoder), updated_at_unix." },  // ados_video::camera_state::CAMERA_STATE_JSON
69    ContractMeta { id: "cameras-discovered", version: 1, wire: "json", transport: "/run/ados/cameras-discovered.json", status: "sidecar", description: "Every camera the hardware layer discovered, with its device path and capabilities, for the camera-config route." },
70    ContractMeta { id: "video-streams", version: 2, wire: "json", transport: "/run/ados/video-streams.json", status: "sidecar", description: "Per-leg video stream list (id/role/codec/live) the node serves, for the GCS stream switcher." },  // ados_video::video_streams::VIDEO_STREAMS_JSON
71    ContractMeta { id: "video-profile", version: 1, wire: "json", transport: "/run/ados/video-profile.json", status: "sidecar", description: "The active video encoder profile and its leases, stamped on every change and read by the radio and the fan-out." },
72    ContractMeta { id: "camera-usb-recovery", version: 1, wire: "json", transport: "/run/ados/camera-usb-recovery.json", status: "sidecar", description: "Camera USB-recovery reconciler state." },
73    ContractMeta { id: "janitor", version: 1, wire: "json", transport: "/run/ados/janitor.json", status: "sidecar", description: "Disk-janitor state: the agent's footprint per category against its budget, the rung the last pass ran at, the bytes it reclaimed per category, what is still reclaimable, and the free space it left behind." },
74    ContractMeta { id: "pic-state", version: 1, wire: "json", transport: "/run/ados/pic-state.json", status: "sidecar", description: "Pilot-in-command arbiter state." },  // ados_hid::paths::PIC_STATE_JSON
75    ContractMeta { id: "ground-station-input", version: 1, wire: "json", transport: "/etc/ados/ground-station-input.json", status: "sidecar", description: "The ground station's persisted primary input device selection. Persistent, so it lives beside the agent config." },  // ados_hid::sidecar::GS_INPUT_JSON
76    ContractMeta { id: "gpio-output", version: 1, wire: "json", transport: "/run/ados/gpio-output.json", status: "sidecar", description: "Driven GPIO output-line state." },  // ados_gpio::sidecar::GPIO_OUTPUT_PATH
77    ContractMeta { id: "board", version: 1, wire: "json", transport: "/run/ados/board.json", status: "sidecar", description: "Detected board fingerprint." },
78    ContractMeta { id: "config-status", version: 1, wire: "json", transport: "/run/ados/config-status-<service>.json", status: "sidecar", description: "Per-service config-load status: a loud-fail record written when a service's config is malformed." },
79    ContractMeta { id: "fc-identity", version: 1, wire: "json", transport: "/run/ados/fc-identity.json", status: "sidecar", description: "Flight-controller identity reconciler outcome: whether the write is enabled, the last tick's outcome, the wanted and current system id." },  // ados_control::routes::fc_identity::SIDECAR_VERSION
80    ContractMeta { id: "mavlink-router", version: 1, wire: "json", transport: "/run/ados/mavlink-router.json", status: "sidecar", description: "The router's learned routes (sysid, compid, endpoint), per-endpoint rx/tx counters, and sensor_rates_hz (the flight-controller sensor streams currently requested, by sensor-bus stream id), rewritten on change and at least every 5 s." },
81    ContractMeta { id: "link-feedback", version: 1, wire: "json", transport: "/run/ados/link-feedback.json", status: "sidecar", description: "The latest ground-measured video-link quality report the drone received, for its adaptive bitrate ladder." },  // ados_protocol::link_feedback::LINK_FEEDBACK_SIDECAR
82    ContractMeta { id: "plugin-loopback-guard", version: 1, wire: "json", transport: "/run/ados/plugin-loopback-guard.json", status: "sidecar", description: "The loopback ports plugins hold, so the plugin host can refuse a plugin binding a port another one owns." },  // ados_protocol::plugin_loopback_guard::SIDECAR_NAME
83    ContractMeta { id: "plugin-state", version: 1, wire: "json", transport: "/run/ados/plugins/<plugin_id>-state.json", status: "sidecar", description: "A plugin's latest published state per topic, served back by the plugin state route." },
84    ContractMeta { id: "ap-guard", version: 1, wire: "json", transport: "/run/ados/ap-guard.json", status: "sidecar", description: "The setup access-point guard's last decision and the interface it resolved." },
85    ContractMeta { id: "logd-push-request", version: 1, wire: "json", transport: "/run/ados/logd-push-request.json", status: "sidecar", description: "An operator's log-push request for the cloud service to consume: the window selector and a request id." },  // ados_cloud::log_push::PUSH_REQUEST_PATH
86    ContractMeta { id: "logd-push-result", version: 1, wire: "json", transport: "/run/ados/logd-push-result.json", status: "sidecar", description: "The cloud service's outcome for the last log-push request, keyed by its request id." },  // ados_cloud::log_push::PUSH_RESULT_PATH
87    ContractMeta { id: "lcd-latency", version: 1, wire: "json", transport: "/run/ados/lcd-latency.json", status: "sidecar", description: "SEI glass-to-glass latency snapshot the video tap writes at 1 Hz while the latency probe runs." },
88    ContractMeta { id: "lcd-fb-stats", version: 1, wire: "json", transport: "/run/ados/lcd-fb-stats.json", status: "sidecar", description: "The LCD framebuffer writer's counters (writes, drops, skipped duplicates, last write time), written at 1 Hz." },  // ados_display::sidecar::LCD_FB_STATS_PATH
89    ContractMeta { id: "lcd-state", version: 1, wire: "json", transport: "/run/ados/lcd-state.json", status: "sidecar", description: "The LCD's active page id, restored on a display restart." },  // ados_display::sidecar::LCD_STATE_PATH
90    ContractMeta { id: "lcd-page-request", version: 1, wire: "json", transport: "/run/ados/lcd-page-request.json", status: "sidecar", description: "A pending remote LCD page switch; the display reads it then unlinks it." },  // ados_display::sidecar::LCD_PAGE_REQUEST_PATH
91    ContractMeta { id: "lcd-plugin-page", version: 1, wire: "json", transport: "/run/ados/lcd-plugin-page.json", status: "sidecar", description: "Plugin-contributed content for the LCD's reserved plugin page: title, rows, and touch zones." },  // ados_display::sidecar::LCD_PLUGIN_PAGE_PATH
92    ContractMeta { id: "lcd-plugin-tap", version: 1, wire: "json", transport: "/run/ados/lcd-plugin-tap.json", status: "sidecar", description: "A pending plugin display action fired by a touch zone or button, for the plugin host to deliver." },  // ados_display::sidecar::LCD_PLUGIN_TAP_PATH
93    ContractMeta { id: "clock", version: 1, wire: "json", transport: "/run/ados/sensing/clock.json", status: "sidecar", description: "The host timebase and its disciplining sources: the timebase the next capture session uses, the lock verdict, sigma, and per-source offset/skew/sigma (fc, hub, gnss PPS, sim)." },
94    ContractMeta { id: "sensors", version: 1, wire: "json", transport: "/run/ados/sensors.json", status: "sidecar", description: "Every sensor stream seen on the sensor bus: kind, source id, measured rate, last sample time." },
95    ContractMeta { id: "sensorhub", version: 1, wire: "json", transport: "/run/ados/sensorhub.json", status: "sidecar", description: "The sensor hub link: transport, connection, firmware and board from Hello, protocol version, uptime, CRC errors and dropped packets." },
96    ContractMeta { id: "gnss", version: 1, wire: "json", transport: "/run/ados/gnss.json", status: "sidecar", description: "GNSS receivers (fix, satellites, position, RTK, PPS lock), the RTK base state (survey-in, fixed position, RTCM out) and the moving-baseline heading." },
97    ContractMeta { id: "capture-storage", version: 1, wire: "json", transport: "/run/ados/capture-storage/capture-storage.json", status: "sidecar", description: "The capture storage root, its volume, capture usage against the budget and free-space floor, session counts, and the admission state (ok, near_full, full) a new capture session is checked against." },
98];
99
100/// Look up the registered version of an IPC contract by id.
101pub fn contract_version(id: &str) -> Option<u16> {
102    CONTRACTS.iter().find(|c| c.id == id).map(|c| c.version)
103}
104
105/// Look up the registered version of a state sidecar by id.
106pub fn sidecar_version(id: &str) -> Option<u16> {
107    SIDECARS.iter().find(|c| c.id == id).map(|c| c.version)
108}
109
110/// Every agent profile, in canonical order.
111pub const PROFILES: &[&str] = &["drone", "ground_station", "workstation", "compute", "visor"];
ados_protocol/contracts.rs

ados_protocol/
contracts.rs
