Oleksandr Bezdieniezhnykh
2.9 KiB
BASALT VIO Adapter
Task: AZ-228_basalt_vio_adapter Name: BASALT VIO Adapter Description: Wrap BASALT as a replaceable relative VIO 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: BASALT VIO Adapter Tracker: AZ-228 Epic: AZ-213
Problem
The safety wrapper needs relative VIO state from calibrated frames and FC IMU without inheriting BASALT-specific internals.
Outcome
- BASALT 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
- BASALT 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 is not the safety authority.
- GPL VIO dependencies remain reference-only unless explicitly approved.
Risks & Mitigation
Risk 1: Nadir fixed-wing fit
- Risk: BASALT underperforms on low-parallax terrain.
- Mitigation: Representative replay and reference comparisons gate acceptance.