Skip to content

Integration Contract#

This document defines the production integration surfaces between ArgusAiTR and the rest of the kill-chain. The 48-hour PoC ships stub implementations behind these surfaces so the post-award implementation drops in without rewriting the core. Every stub raises NotImplementedError with a clear "post-award" message.

Surface 1 — RWS video tap (VideoSource / RTSPSource)#

PoC: FileSource reads a recorded UAS clip from disk.

Production: RTSPSource (stub today) connects to the CROWS HD-SDI output via a commercial bridge (e.g., AJA / Magewell HD-SDI-to-IP) and exposes an RTSP / MJPEG stream. The pipeline does not know the difference — same VideoSource ABC.

class VideoSource(ABC):
    def open(self) -> None: ...
    def next_frame(self) -> Frame | None: ...
    def close(self) -> None: ...
    @property
    def intrinsics(self) -> dict[str, Any]: ...
    @property
    def is_open(self) -> bool: ...

Frame contract: - image: np.ndarray BGR (OpenCV convention). - timestamp_ns: wall-clock ns at frame arrival. - meta: at minimum focal_length_px. Recommended additions for production: width_px, height_px, sensor_type, source_fps, intrinsics_K (3×3 K matrix if calibrated), gimbal_az_rad, gimbal_el_rad.

Wiring (production):

CROWS daylight TV ─► HD-SDI ─► commercial bridge ─► RTSP ─► RTSPSource ─► ArgusAiTR

Surface 2 — Thermal channel (ThermalSource)#

PoC: Stub. The PoC supports EO only.

Production: Cooled MWIR sensor (FLIR Boson+ / Tau 2 class) plus optional LWIR for low-cost overcoming-darkness coverage. The thermal channel is a second VideoSource feeding a fused detector (post-award upgrade to the detector stage). Time-synchronization is via the shared wall-clock; spatial alignment via factory calibration of the dual-sensor boresight on the CROWS turret.

Surface 3 — RWS control (CROWSAdapter)#

PoC: MockCROWSAdapter writes every slew command to audit/crows_commands.jsonl.

Production: GVAAdapter (stub today) talks to the CROWS control box over the Generic Vehicle Architecture (GVA) Ethernet bus per STANAG 4754.

class CROWSAdapter(ABC):
    def send_slew_command(self, az_rad: float, el_rad: float, rate_rad_s: float = 0.0) -> None: ...
    def read_telemetry(self) -> dict[str, Any]: ...
    def report_health(self) -> dict[str, Any]: ...

Command semantics (production): - Azimuth / elevation in gimbal frame (turret-relative), radians. - Rate in radians per second (max angular rate cap). - HITL hard gate: no command leaves ArgusAiTR without an operator- attributed OperatorAction upstream. The audit log makes this property externally verifiable.

Telemetry semantics (production):

The read_telemetry() payload includes at minimum the current turret pose (az / el / rate), arming state, and any RWS-side health bits the operator console needs. ArgusAiTR uses this to compute lead and to inform the threat heuristic.

Surface 4 — Telemetry out (TelemetrySink / TAK / DDS)#

PoC: JSONFileSink writes the audit and event stream as JSONL.

Production: Multiple sinks composed:

Sink What it carries
JSONFileSink Local audit log on the host. Identical to PoC.
TAKTelemetrySink Cursor on Target (CoT) tracks for operator TAK clients (post-award stub).
DDSSink (new) DDS topic for the broader fire-control network (post-award).
MQTTSink (optional) Network bridge per Part 4 telemetry network architecture (post-award).

The AuditLogger already fans events to multiple sinks; adding new ones requires no changes to the rest of the system.

Surface 5 — Operator HMI#

PoC: Browser-based operator console served by the Argus host.

Production: Two delivery options, configurable per deployment:

  • Co-located web console: the operator runs a browser on a panel PC in the vehicle. Same surface as the PoC.
  • Embedded operator panel: Argus packages the HMI as a Qt panel that hosts the same JSON / MJPEG streams under the hood. The TestClient-compatible REST contract makes both delivery options consistent.

In either case, every HMI action is recorded in the audit log via POST /op/{action} → AuditLogger.operator_action(...).

Surface 6 — Edge-network bridge (Part 4 alignment)#

Argus Part 1 stays out of the Part 4 network design, but the integration contract anticipates it:

  • All outbound telemetry is structured JSON or CoT — encryption / transport agnostic.
  • Per-sink configuration allows post-quantum encryption + tiered decryption keys to be applied at the sink boundary without changes to the orchestrator.
  • TAK compatibility is the immediate stretch target.

Surface 7 — Time sync#

PoC: Host wall-clock (time.time_ns()).

Production: PTP (IEEE 1588) sync on the vehicle bus is standard; ArgusAiTR consumes whatever the GVA bus provides via the bridge. Internally the pipeline uses monotonic deltas for velocity computation and absolute wall-clock for audit timestamps — the two roles are kept separate in the code so a clock-discipline change does not affect tracker behavior.

Failure modes documented to the integrator#

  • Loss of source: Pipeline emits aitr_status=degraded; HMI banner flips. Operator continues with raw video (in the production overlay posture, raw video continues to be served by the bridge).
  • Adapter rejected command: Adapter send_slew_command should raise RuntimeError; ArgusAiTR audits the failure and surfaces it via the operator console without retrying autonomously.
  • AuditLogger sink fails: Caught and logged; pipeline continues.

Document scope#

This contract is normative for ArgusAiTR development through the post-award prototype. It is not a final ICD — that will be drafted jointly with the integrating party (Kongsberg US / NSWC / Army C5ISR) during Month 1.