mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 07:51:28 +00:00
Revise acceptance criteria and restrictions documentation to clarify recent updates and specifications. Key changes include enhanced definitions for position accuracy, image processing quality, and operational parameters, as well as updates to camera specifications and validation requirements. This revision aims to improve clarity and ensure alignment with project goals.
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,69 @@
|
||||
# MAVLink And GCS Integration
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Subscribe to flight-controller telemetry, emit `GPS_INPUT`, and send downsampled QGroundControl status/failsafe messages.
|
||||
|
||||
**Architectural Pattern**: Protocol adapter.
|
||||
|
||||
**Upstream dependencies**: ArduPilot Plane FC, safety/anchor wrapper.
|
||||
|
||||
**Downstream consumers**: BASALT VIO adapter, safety/anchor wrapper, QGC, FDR.
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
### Interface: `MavlinkGateway`
|
||||
|
||||
| Method | Input | Output | Async | Error Types |
|
||||
|--------|-------|--------|-------|-------------|
|
||||
| `subscribe_telemetry` | `TelemetrySubscriptionRequest` | `TelemetrySample` | Yes | `MavlinkDisconnected` |
|
||||
| `emit_gps_input` | `PositionEstimate` | `EmitResult` | Yes | `MavlinkDisconnected`, `InvalidGpsInput` |
|
||||
| `emit_status` | `GcsStatusMessage` | `EmitResult` | Yes | `MavlinkDisconnected` |
|
||||
|
||||
## 3. Data Access Patterns
|
||||
|
||||
No persistent data ownership; telemetry and emitted packets are mirrored to FDR.
|
||||
|
||||
## 4. Implementation Details
|
||||
|
||||
**State Management**: Maintains MAVLink connection status, source/system IDs, and rate limiters for QGC status.
|
||||
|
||||
**Key Dependencies**:
|
||||
|
||||
| Library | Purpose |
|
||||
|---------|---------|
|
||||
| MAVSDK | Telemetry subscriptions |
|
||||
| pymavlink | Exact `GPS_INPUT` field emission |
|
||||
|
||||
**Error Handling Strategy**:
|
||||
- Invalid `GPS_INPUT` fields are rejected before emission.
|
||||
- Connection loss is surfaced to wrapper/FDR and does not silently drop safety events.
|
||||
|
||||
## 5. Caveats & Edge Cases
|
||||
|
||||
**Known limitations**:
|
||||
- v1 emits `GPS_INPUT` only, not velocity-target navigation commands.
|
||||
- Plane parameter configuration must be validated in SITL before hardware use.
|
||||
|
||||
**Performance bottlenecks**:
|
||||
- Status text must be rate-limited to avoid telemetry noise.
|
||||
|
||||
## 6. Dependency Graph
|
||||
|
||||
**Must be implemented after**: position estimate DTO and MAVLink output contract.
|
||||
|
||||
**Can be implemented in parallel with**: cache lifecycle, camera ingest.
|
||||
|
||||
**Blocks**: SITL integration and production FC output.
|
||||
|
||||
## 7. Logging Strategy
|
||||
|
||||
| Log Level | When | Example |
|
||||
|-----------|------|---------|
|
||||
| ERROR | MAVLink disconnected | `mavlink_disconnected endpoint=...` |
|
||||
| WARN | Invalid output rejected | `gps_input_invalid reason=...` |
|
||||
| INFO | FC link established | `mavlink_connected system_id=...` |
|
||||
|
||||
**Log format**: FDR structured event.
|
||||
|
||||
**Log storage**: FDR segment and optional tlog.
|
||||
@@ -0,0 +1,176 @@
|
||||
# Test Specification — MAVLink And GCS Integration
|
||||
|
||||
## Acceptance Criteria Traceability
|
||||
|
||||
| AC ID | Acceptance Criterion | Test IDs | Coverage |
|
||||
|-------|---------------------|----------|----------|
|
||||
| AC-4.3 | v1 GPS_INPUT only for ArduPilot Plane | IT-01, AT-01 | Covered |
|
||||
| AC-4.4 | Frame-by-frame streaming | PT-01 | Covered |
|
||||
| AC-4.5 | Updated estimates/corrections | IT-02 | Covered |
|
||||
| AC-5.1 | FC state initialization telemetry | IT-03 | Covered |
|
||||
| AC-5.2 | Plane SITL fallback | IT-04 | Covered |
|
||||
| AC-6.1 | QGC status 1-2 Hz | IT-05, PT-02 | Covered |
|
||||
| AC-6.2 | GCS command ingress | IT-06, ST-01 | Covered |
|
||||
| AC-6.3 | WGS84 output | IT-01 | Covered |
|
||||
| AC-NEW-2 | Spoofing promotion <3 s | IT-04 | Covered |
|
||||
| AC-NEW-8 | Blackout/failsafe status | IT-05 | Covered |
|
||||
|
||||
## Blackbox Tests
|
||||
|
||||
### IT-01: GPS_INPUT Field Mapping
|
||||
|
||||
**Summary**: Verify `PositionEstimate` maps to valid MAVLink `GPS_INPUT`.
|
||||
|
||||
**Traces to**: AC-4.3, AC-6.3
|
||||
|
||||
**Input data**: Position estimates across all source labels.
|
||||
|
||||
**Expected result**: v1 emits `GPS_INPUT` only, no `ODOMETRY`; WGS84 lat/lon/alt, fix type, ignore flags, and accuracy fields match contract.
|
||||
|
||||
**Max execution time**: 2 minutes.
|
||||
|
||||
---
|
||||
|
||||
### IT-02: Correction Emission
|
||||
|
||||
**Summary**: Verify updated estimates can be emitted without batching.
|
||||
|
||||
**Traces to**: AC-4.5
|
||||
|
||||
**Input data**: Original VO estimate followed by anchor-corrected estimate.
|
||||
|
||||
**Expected result**: Both estimates are emitted in order with updated accuracy/source label.
|
||||
|
||||
**Max execution time**: 2 minutes.
|
||||
|
||||
---
|
||||
|
||||
### IT-03: FC Telemetry Subscription
|
||||
|
||||
**Summary**: Verify telemetry needed for initialization and VIO is available.
|
||||
|
||||
**Traces to**: AC-5.1
|
||||
|
||||
**Input data**: Plane SITL or MAVLink replay with EKF position, IMU, attitude, airspeed, altitude.
|
||||
|
||||
**Expected result**: Normalized `TelemetrySample` stream includes required fields and timestamps.
|
||||
|
||||
**Max execution time**: 5 minutes.
|
||||
|
||||
---
|
||||
|
||||
### IT-04: Spoofing And Fallback In Plane SITL
|
||||
|
||||
**Summary**: Verify spoofing and no-estimate behavior in ArduPilot Plane SITL.
|
||||
|
||||
**Traces to**: AC-5.2, AC-NEW-2
|
||||
|
||||
**Input data**: Plane SITL production parameter set and spoofing trace.
|
||||
|
||||
**Expected result**: Own estimate promotion occurs within <3 s; fallback/no-estimate behavior matches Plane parameters.
|
||||
|
||||
**Max execution time**: 10 minutes.
|
||||
|
||||
---
|
||||
|
||||
### IT-05: QGC Blackout Status
|
||||
|
||||
**Summary**: Verify degraded-mode messages are visible at required rate.
|
||||
|
||||
**Traces to**: AC-6.1, AC-NEW-8
|
||||
|
||||
**Input data**: Safety wrapper emits blackout and failsafe statuses.
|
||||
|
||||
**Expected result**: QGC observer sees `VISUAL_BLACKOUT_IMU_ONLY` at 1-2 Hz and `VISUAL_BLACKOUT_FAILSAFE` at threshold.
|
||||
|
||||
**Max execution time**: 10 minutes.
|
||||
|
||||
---
|
||||
|
||||
### IT-06: Operator Relocalization Hint
|
||||
|
||||
**Summary**: Verify GCS command ingress can carry approximate relocalization hints.
|
||||
|
||||
**Traces to**: AC-6.2
|
||||
|
||||
**Input data**: STATUSTEXT/NAMED_VALUE_FLOAT/custom dialect hint fixture.
|
||||
|
||||
**Expected result**: Valid hint is parsed and forwarded to retrieval/safety logic; invalid hint is rejected.
|
||||
|
||||
**Max execution time**: 5 minutes.
|
||||
|
||||
## Performance Tests
|
||||
|
||||
### PT-01: Frame-Rate Emission
|
||||
|
||||
**Summary**: Verify output is streamed frame-by-frame and not batched.
|
||||
|
||||
**Traces to**: AC-4.4
|
||||
|
||||
**Load scenario**:
|
||||
- Input estimate rate: target frame rate.
|
||||
- Duration: 30 minutes.
|
||||
|
||||
| Metric | Target | Failure Threshold |
|
||||
|--------|--------|-------------------|
|
||||
| Output delay p95 | <=25 ms after wrapper output | >100 ms |
|
||||
| Missing messages | 0 except upstream dropped frames | Any silent drop |
|
||||
|
||||
---
|
||||
|
||||
### PT-02: QGC Status Rate Limit
|
||||
|
||||
**Summary**: Verify QGC status is downsampled without losing critical transitions.
|
||||
|
||||
**Traces to**: AC-6.1
|
||||
|
||||
| Metric | Target | Failure Threshold |
|
||||
|--------|--------|-------------------|
|
||||
| Status rate | 1-2 Hz while active | <1 Hz or >2 Hz sustained |
|
||||
| Critical transition delay | <=1 s | >2 s |
|
||||
|
||||
## Security Tests
|
||||
|
||||
### ST-01: MAVLink Source And Command Validation
|
||||
|
||||
**Summary**: Verify unauthorized or malformed MAVLink messages are rejected.
|
||||
|
||||
**Traces to**: AC-6.2
|
||||
|
||||
**Attack vector**: Malicious source sends spoofed command or GPS data.
|
||||
|
||||
**Test procedure**:
|
||||
1. Send valid command from allowed source.
|
||||
2. Send same command from disallowed source/system ID.
|
||||
3. Send malformed values.
|
||||
|
||||
**Expected behavior**: Allowed command is accepted; disallowed/malformed messages are rejected and logged.
|
||||
|
||||
**Pass criteria**: 0 unauthorized commands affect localization state.
|
||||
|
||||
## Acceptance Tests
|
||||
|
||||
### AT-01: Plane SITL Output Acceptance
|
||||
|
||||
**Summary**: Verify ArduPilot Plane receives and uses v1 `GPS_INPUT` as configured.
|
||||
|
||||
**Traces to**: AC-4.3
|
||||
|
||||
| Step | Action | Expected Result |
|
||||
|------|--------|-----------------|
|
||||
| 1 | Start Plane SITL with production params | FC accepts external GPS substitute config |
|
||||
| 2 | Emit `GPS_INPUT` estimate | Message is received with expected fields |
|
||||
| 3 | Observe wire | `ODOMETRY` is absent in v1 |
|
||||
|
||||
## Test Data Management
|
||||
|
||||
| Data Set | Description | Source | Size |
|
||||
|----------|-------------|--------|------|
|
||||
| `sitl_spoofing_scenarios` | GPS loss/spoofing traces | Generated SITL | Small |
|
||||
| `mavlink_output_fixtures` | PositionEstimate cases | Generated fixture | Small |
|
||||
|
||||
**Setup procedure**: Start SITL/QGC observer or replay MAVLink log.
|
||||
|
||||
**Teardown procedure**: Stop processes and archive tlogs.
|
||||
|
||||
**Data isolation strategy**: Unique MAVLink ports and run IDs per test.
|
||||
Reference in New Issue
Block a user