mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 20:41:12 +00:00
[AZ-228] [AZ-229] Add VIO and satellite sync boundaries
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -0,0 +1,90 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user