azaion/gps-denied-onboard
1
0
Fork 0
mirror of https://github.com/azaion/gps-denied-onboard.git synced 2026-06-22 15:21:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

[AZ-228] [AZ-229] Add VIO and satellite sync boundaries

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-03 18:31:04 +03:00
parent 2db50bc124
commit 087f4dba27
13 changed files with 625 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_docs/02_tasks/todo/AZ-228_vio_adapter.md
-90
View File
@@ -1,90 +0,0 @@
# 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.
_docs/02_tasks/todo/AZ-229_satellite_service_sync.md
-87
View File
@@ -1,87 +0,0 @@
# Satellite Service Sync Boundary
**Task**: AZ-229_satellite_service_sync
**Name**: Satellite Service Sync Boundary
**Description**: Import mission cache packages before flight and upload generated-tile packages after flight.
**Complexity**: 3 points
**Dependencies**: AZ-222_runtime_config_errors_telemetry, AZ-225_tile_manager_cache_manifest, AZ-226_generated_tile_orthorectification
**Component**: Satellite Service
**Tracker**: AZ-229
**Epic**: AZ-214
## Problem
The onboard runtime needs a clear boundary for Satellite Service package exchange without allowing mid-flight network calls.
## Outcome
- Pre-flight cache packages can be imported and handed to Tile Manager validation.
- Post-flight generated-tile packages can be uploaded/retried.
- Mid-flight provider or Satellite Service calls are explicitly blocked.
## Scope
### Included
- Pre-flight import behavior.
- Post-flight generated-tile upload behavior.
- Package status and retry/error reporting.
### Excluded
- In-flight retrieval ranking.
- Tile manifest validation and generated tile creation.
## Dependencies
### Document Dependencies
- `_docs/02_document/contracts/shared/runtime_contracts.md`
- `_docs/02_document/contracts/shared/config_errors_telemetry.md`
## Acceptance Criteria
**AC-1: Pre-flight package import succeeds**
Given a valid Satellite Service mission cache package
When import runs before flight
Then the package is available for Tile Manager validation.
**AC-2: Post-flight upload is auditable**
Given a generated-tile package exists after landing
When upload runs
Then success, rejection, or retryable failure is recorded.
**AC-3: Mid-flight network calls are blocked**
Given the runtime is in flight mode
When cache data is missing
Then the component does not call a satellite provider or suite service.
## Non-Functional Requirements
**Reliability**
- Upload failures retain packages for retry.
**Security**
- Signing credentials are never logged.
## Unit Tests
| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Valid import package | Package ready for validation |
| AC-2 | Upload unavailable | Retryable failure recorded |
| AC-3 | Flight-mode missing data | No network call |
## Blackbox Tests
| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-3 | Network disabled in replay | Relocalization missing data | Degraded/no-candidate behavior, no fetch | Security |
## Constraints
- No in-flight Satellite Service or satellite-provider network dependency.
- Package sync is before takeoff or after landing only.
## Risks & Mitigation
**Risk 1: Boundary confusion**
- *Risk*: Retrieval code starts fetching provider data mid-flight.
- *Mitigation*: Flight-mode invariant is acceptance-tested.