gps-denied-onboard/_docs/02_tasks/todo/AZ-228_vio_adapter.md

VIO Adapter

Task: AZ-228_vio_adapter Name: VIO Adapter Description: Wrap the selected relative VIO backend as a replaceable component with health and error behavior. Complexity: 5 points Dependencies: AZ-221_shared_geometry_time_sync, AZ-222_runtime_config_errors_telemetry, AZ-223_camera_ingest_calibration, AZ-224_mavlink_gcs_gateway Component: VIO Adapter Tracker: AZ-228 Epic: AZ-213

Problem

The safety wrapper needs relative VIO state from calibrated frames and FC IMU without inheriting backend-specific internals.

Outcome

• Backend initialization, processing, and health behavior are exposed through a replaceable adapter.
• Tracking loss and timestamp mismatch are explicit.
• The adapter never emits WGS84 coordinates or safety decisions.

Scope

Included

• Initialization and runtime health.
• Frame + IMU processing behavior.
• Relative pose/velocity/bias output and quality metadata.
• Native bridge boundary.

Excluded

• Absolute anchor fusion and covariance authority.
• Satellite matching fallback implementation.

Dependencies

Document Dependencies

• _docs/02_document/contracts/shared/runtime_contracts.md
• _docs/02_document/contracts/shared/geometry_time_sync.md
• _docs/02_document/contracts/shared/config_errors_telemetry.md

Acceptance Criteria

AC-1: VIO state emitted Given synchronized frame and IMU samples When processing succeeds Then a relative VIO state packet with tracking quality is emitted.

AC-2: Timestamp mismatch is explicit Given frame/IMU timestamps are inconsistent When processing is requested Then the adapter rejects the packet with a timestamp mismatch error.

AC-3: Health is observable Given initialization or tracking quality changes When health is requested Then the adapter reports current VIO readiness and degradation state.

Non-Functional Requirements

Performance

• Adapter processing must be profiled against Jetson latency/memory limits.

Reliability

• Backend failures are surfaced, not hidden.

Unit Tests

AC Ref	What to Test	Required Outcome
AC-1	Valid synchronized packet	VIO state emitted
AC-2	Bad timestamp window	Explicit error
AC-3	Tracking loss	Health reports degraded

Blackbox Tests

AC Ref	Initial Data/Conditions	What to Test	Expected Behavior	NFR References
AC-1	Derkachi/public replay	Relative VIO path	Continuous estimates where data supports it	Performance

Constraints

• BASALT remains the current selected backend, but package and folder names must stay backend-neutral.
• The VIO adapter is not the safety authority.
• GPL VIO dependencies remain reference-only unless explicitly approved.

Risks & Mitigation

Risk 1: Nadir fixed-wing fit

• Risk: The selected VIO backend underperforms on low-parallax terrain.
• Mitigation: Representative replay and reference comparisons gate acceptance.