mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-21 10:21:13 +00:00
remove docs, new start once again
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -1,659 +0,0 @@
|
||||
# GPS-Denied Onboard System - System Flows
|
||||
|
||||
## Flow Inventory
|
||||
|
||||
| # | Flow Name | Trigger | Primary Components | Criticality |
|
||||
|---|-----------|---------|--------------------|-------------|
|
||||
| F1 | Airframe Provisioning & FC Bootstrap | Client setup or airframe maintenance | C-12, C-6, FC, Jetson UI | High |
|
||||
| F2 | Pre-Flight Mission Setup & Tile Fetch | Operator prepares mission on Jetson UI | Jetson UI, C-1, C-2, Suite Satellite Service | High |
|
||||
| F3 | In-Flight VO-First Localization | Nav-cam frame arrives | C-4, C-2, C-3, C-5, C-6, C-10, C-11 | High |
|
||||
| F4 | Re-Localization Recovery | Cold start, VO loss, sharp turn, disconnected segment, or sigma_xy > 50 m | C-2, C-3, C-5, C-7 | High |
|
||||
| F5 | In-Flight Tile Generation & Local Write | Eligible satellite-anchored frame | C-1b, C-1, C-10 | Medium |
|
||||
| F6 | Post-Flight Candidate Tile Upload | Aircraft lands and network is available | C-1, Suite Satellite Service | Medium |
|
||||
| F7 | Cold Start, Spoofing Promotion & Failsafe | Boot, GPS-denial signal, or output gap | C-6, C-7, FC, QGC | High |
|
||||
| F8 | AI-Camera Object Localization | AI detection system requests object coordinates | C-8, C-5, MAVROS/FC telemetry | Medium |
|
||||
|
||||
## Flow Dependencies
|
||||
|
||||
| Flow | Depends On | Shares Data With |
|
||||
|------|------------|------------------|
|
||||
| F1 | Physical wiring and FC access | F2 and F3 via signed airframe manifest and FC parameter pins |
|
||||
| F2 | F1 for manifest and signing; Suite Service connectivity | F3/F4/F5 via tile cache, mission YAML, VPR index |
|
||||
| F3 | F2 for sufficient local cache; F1 for FC integration | F4 via re-loc triggers; F5 via satellite-anchored pose; F7 via output health |
|
||||
| F4 | F2 cache and descriptors; F3 trigger context | F3 via recovered anchor fix; F7 via failure state |
|
||||
| F5 | F3 satellite-anchored pose and tile cache | F6 via candidate tiles; C-10 via tile-generation events |
|
||||
| F6 | F5 candidate tiles and post-flight network | Future F2 through Suite Service trusted-basemap refresh |
|
||||
| F7 | F1 signing and FC params; F3 output health | F3 via source mode; QGC via status messages |
|
||||
| F8 | F3 current pose and FC altitude/attitude | FDR via object-localization audit records |
|
||||
|
||||
---
|
||||
|
||||
## Flow F1: Airframe Provisioning & FC Bootstrap
|
||||
|
||||
### Description
|
||||
|
||||
At client setup, the operator or field engineer uses the Jetson UI and Provisioning Tool to make one airframe safe and repeatable for GPS-Denied operation. The output is a signed airframe manifest and a verified FC link.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- Jetson, FC, nav camera, and harness are physically installed.
|
||||
- FC is reachable over the intended companion link.
|
||||
- The operator can perform manual physical wiring checks and standard QGC compass/accelerometer calibration.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Operator
|
||||
participant JetsonUI as Jetson UI
|
||||
participant Provisioner as C-12 Provisioning Tool
|
||||
participant FC as ArduPilot FC
|
||||
participant Manifest as Airframe Manifest
|
||||
|
||||
Operator->>JetsonUI: Start airframe provisioning
|
||||
JetsonUI->>Provisioner: Launch provision-fc.py
|
||||
Provisioner->>FC: Detect FC and read firmware/sysid
|
||||
FC-->>Provisioner: FC identity and current parameters
|
||||
Provisioner->>FC: Pin SERIAL2_BAUD/SERIAL2_PROTOCOL
|
||||
Provisioner->>FC: Pin GPS1_TYPE=14 and EK3_SRC1_*
|
||||
Provisioner->>FC: Bootstrap MAVLink2 signing key
|
||||
Provisioner->>FC: Smoke-test RAW_IMU rate and GPS_INPUT round-trip
|
||||
Provisioner->>JetsonUI: Request checkerboard intrinsics calibration
|
||||
Operator->>JetsonUI: Complete guided calibration
|
||||
Provisioner->>Manifest: Write signed airframe manifest
|
||||
JetsonUI-->>Operator: Provisioning complete
|
||||
```
|
||||
|
||||
### Flowchart
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
start([Start provisioning]) --> detectFc[Detect FC]
|
||||
detectFc --> fcReachable{FC reachable?}
|
||||
fcReachable -->|No| stopRepair[Stop for wiring/link repair]
|
||||
fcReachable -->|Yes| pinParams[Pin serial, GPS_INPUT, EK3 params]
|
||||
pinParams --> signing[Install MAVLink2 signing key]
|
||||
signing --> smoke[RAW_IMU + GPS_INPUT smoke test]
|
||||
smoke --> smokeOk{Smoke test passes?}
|
||||
smokeOk -->|No| stopDebug[Stop with failed check]
|
||||
smokeOk -->|Yes| calibrate[Guided nav-cam intrinsics calibration]
|
||||
calibrate --> manifest[Write signed airframe manifest]
|
||||
manifest --> done([Airframe ready])
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
| Step | From | To | Data | Format |
|
||||
|------|------|----|------|--------|
|
||||
| 1 | FC | Provisioning Tool | Firmware, sysid, current params | MAVLink |
|
||||
| 2 | Provisioning Tool | FC | Serial/GPS/EKF params, signing key | MAVLink commands |
|
||||
| 3 | Jetson UI | Provisioning Tool | Camera calibration observations | Guided calibration payload |
|
||||
| 4 | Provisioning Tool | Runtime | Airframe manifest | Signed file |
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| FC not detected | FC link check | No heartbeat | Stop and repair wiring/link settings. |
|
||||
| Signing bootstrap fails | Signing setup | FC rejects command or verification | Stop; do not run flight stack unsigned. |
|
||||
| GPS_INPUT round-trip fails | Smoke test | FC does not receive/accept test frame | Stop and debug params/sysids/signing. |
|
||||
| Intrinsics calibration incomplete | Jetson UI | Missing calibration artifact | Keep airframe unprovisioned. |
|
||||
|
||||
### Performance Expectations
|
||||
|
||||
| Metric | Target | Notes |
|
||||
|--------|--------|-------|
|
||||
| Provisioning duration | Human-paced | Safety and correctness matter more than speed. |
|
||||
| Smoke-test result | Deterministic pass/fail | Must run before production flight. |
|
||||
|
||||
---
|
||||
|
||||
## Flow F2: Pre-Flight Mission Setup & Tile Fetch
|
||||
|
||||
### Description
|
||||
|
||||
Before takeoff, the operator connects to the Jetson UI, defines the route and sector, requests tiles from the Suite Satellite Service, and writes mission YAML next to the local tile cache. This is the only time the aircraft needs Service connectivity for the upcoming mission.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- Airframe provisioning is complete.
|
||||
- Jetson has pre-flight internet.
|
||||
- Suite Satellite Service is reachable and authorized.
|
||||
- The operator knows the intended operational area and sector classes.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Operator
|
||||
participant JetsonUI as Jetson UI
|
||||
participant Service as Suite Satellite Service
|
||||
participant Cache as C-1 Tile Cache
|
||||
participant VPR as C-2 VPR Index
|
||||
|
||||
Operator->>JetsonUI: Draw route, sector, and transit corridor
|
||||
JetsonUI->>JetsonUI: Classify sectors and write mission YAML draft
|
||||
JetsonUI->>Service: Request z=19 tiles for operational area
|
||||
Service-->>JetsonUI: Tile package and metadata
|
||||
JetsonUI->>Cache: Store MBTiles and sidecar metadata
|
||||
Cache->>VPR: Build/update chunk descriptors and FAISS index
|
||||
VPR-->>JetsonUI: Index ready
|
||||
JetsonUI-->>Operator: Mission cache ready for flight
|
||||
```
|
||||
|
||||
### Flowchart
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
start([Operator opens Jetson UI]) --> draw[Draw route + sector]
|
||||
draw --> classify[Set active-conflict/stable sector classes]
|
||||
classify --> fetch[Request tiles from Suite Service]
|
||||
fetch --> enoughTiles{Tiles meet coverage, freshness, resolution?}
|
||||
enoughTiles -->|No| block[Block flight cache-ready status]
|
||||
enoughTiles -->|Yes| store[Store z=19 MBTiles + sidecars]
|
||||
store --> index[Build VPR chunks and descriptors]
|
||||
index --> yaml[Write mission YAML]
|
||||
yaml --> ready([Mission ready])
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
| Step | From | To | Data | Format |
|
||||
|------|------|----|------|--------|
|
||||
| 1 | Operator | Jetson UI | Route, sector polygon, mission ID | UI form |
|
||||
| 2 | Jetson UI | Suite Service | Tile fetch request | HTTPS/API |
|
||||
| 3 | Suite Service | Tile Cache | Tiles and metadata | MBTiles/package contract |
|
||||
| 4 | Tile Cache | VPR Index | Chunks and descriptors | Local files / FAISS index |
|
||||
| 5 | Jetson UI | Runtime | Mission configuration | YAML |
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Service unavailable | Tile fetch | Request fails | Retry pre-flight; do not assume in-flight fetch. |
|
||||
| Tile freshness invalid | Cache validation | Capture date violates sector budget | Reject or mark down-confidence per AC-NEW-6. |
|
||||
| Cache incomplete | Coverage validation | Operational area gap | Block mission-ready status until resolved. |
|
||||
| Descriptor build fails | VPR index | Index missing or corrupt | Rebuild; block flight if unresolved. |
|
||||
|
||||
### Performance Expectations
|
||||
|
||||
| Metric | Target | Notes |
|
||||
|--------|--------|-------|
|
||||
| Initial preload size | About 700 MB for 400 km2 at z=19 | Throughput-sensitive but pre-flight only. |
|
||||
| Runtime dependency | Zero Service calls in flight | All needed data must be local before takeoff. |
|
||||
|
||||
---
|
||||
|
||||
## Flow F3: In-Flight VO-First Localization
|
||||
|
||||
### Description
|
||||
|
||||
For each nav-camera frame, the runtime uses the cheap C-4 motion bridge to propagate pose from the last satellite anchor. Satellite retrieval and matching are not run on every frame; they are invoked on anchor cadence, covariance growth, VO-health triggers, sharp turns, cold start, or disconnected-segment recovery.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- Mission YAML and tile cache are loaded.
|
||||
- Airframe manifest is valid.
|
||||
- Camera stream and FC telemetry are live.
|
||||
- TensorRT engines and descriptor indexes are warmed.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Cam as Nav Camera
|
||||
participant FC as ArduPilot FC
|
||||
participant VO as C-4 Nadir Motion Bridge
|
||||
participant VPR as C-2 VPR
|
||||
participant Matcher as C-3 Matcher/PnP
|
||||
participant Output as C-5/C-11 Output Stage
|
||||
participant Mav as C-6 MAVLink Injector
|
||||
participant FDR as C-10 FDR
|
||||
|
||||
Cam->>VO: Frame
|
||||
FC-->>VO: IMU, attitude, altitude
|
||||
VO-->>Output: Relative motion + covariance
|
||||
Output->>Output: Check anchor age, sigma_xy, drift budget, VO health
|
||||
alt Anchor cadence or re-localization trigger
|
||||
Output->>VPR: Request candidate chunks
|
||||
VPR-->>Matcher: Top-K chunks
|
||||
Cam->>Matcher: Current frame
|
||||
Matcher-->>Output: Absolute pose + covariance + inliers
|
||||
end
|
||||
Output->>Output: Mahalanobis gate and covariance calibration
|
||||
Output->>Mav: GPS_INPUT payload
|
||||
Mav->>FC: Signed GPS_INPUT
|
||||
Output->>FDR: Source label, gates, covariance, decision
|
||||
```
|
||||
|
||||
### Flowchart
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
frame([Frame arrives]) --> vo[Update nadir motion bridge]
|
||||
vo --> trigger{Anchor cadence or re-loc trigger?}
|
||||
trigger -->|No| extrapolate[Produce vo_extrapolated candidate]
|
||||
trigger -->|Yes| retrieve[VPR top-K candidate chunks]
|
||||
retrieve --> match[Cross-view match + PnP]
|
||||
match --> gate[Mahalanobis gate]
|
||||
extrapolate --> gate
|
||||
gate --> valid{Valid confidence?}
|
||||
valid -->|Yes| emit[Emit signed GPS_INPUT]
|
||||
valid -->|No| dead[Mark dead_reckoned/no fix]
|
||||
emit --> record[FDR decision record]
|
||||
dead --> record
|
||||
record --> next([Next frame])
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
| Step | From | To | Data | Format |
|
||||
|------|------|----|------|--------|
|
||||
| 1 | Nav camera | Motion bridge / matcher | Current frame | ROS 2 image |
|
||||
| 2 | FC | Motion bridge / output | IMU, attitude, altitude, GPS health | MAVLink -> ROS 2 |
|
||||
| 3 | Tile cache | VPR / matcher | Candidate chunks and descriptors | Local cache/index |
|
||||
| 4 | Matcher / VO | Output stage | Pose hypotheses and covariance | ROS 2 messages |
|
||||
| 5 | Output stage | FC | WGS84 fix and accuracy | MAVLink GPS_INPUT |
|
||||
| 6 | Output stage | FDR | Decisions and gates | FlatBuffers record |
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Frame dropped under load | Camera/runtime | Queue overflow or skip policy | Drop up to allowed budget; keep latest-frame processing. |
|
||||
| VO unhealthy | Motion bridge | Low overlap, blur, weak features, inconsistent IMU/attitude, or covariance growth | Trigger F4 re-localization. |
|
||||
| Matcher outlier | Output gate | Mahalanobis distance exceeds threshold | Reject, do not down-weight into a false anchor. |
|
||||
| GPS_INPUT rejected | FC | Missing acceptance/round-trip evidence | Raise health alert and F7 failsafe path. |
|
||||
|
||||
### Performance Expectations
|
||||
|
||||
| Metric | Target | Notes |
|
||||
|--------|--------|-------|
|
||||
| Camera-to-FC output | <400 ms p95 | Steady-state path is VO-first; satellite matching is cadence/triggered correction, not every-frame work. |
|
||||
| Frame rate | 3 fps input; up to about 10% drops allowed under load | Output must not batch. |
|
||||
| Memory | <8 GB shared | Includes TensorRT engines and ROS 2 overhead. |
|
||||
|
||||
---
|
||||
|
||||
## Flow F4: Re-Localization Recovery
|
||||
|
||||
### Description
|
||||
|
||||
When the system lacks a trustworthy recent anchor, it expands retrieval and matching to recover an absolute pose. This path handles cold start, sharp turns, disconnected segments, sigma_xy growth, and VO failure.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- Tile cache and VPR index cover the current operational area.
|
||||
- The runtime has an initial or predicted position from FC/VO/dead reckoning.
|
||||
- LiteSAM and inline matcher engines are installed and warmed according to deployment mode.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Output as C-5 Output Stage
|
||||
participant VPR as C-2 VPR
|
||||
participant Matcher as C-3 Inline Matcher
|
||||
participant LiteSAM as LiteSAM Fallback
|
||||
participant FDR as C-10 FDR
|
||||
|
||||
Output->>VPR: Re-loc request with predicted position and sector class
|
||||
VPR-->>Output: Top-K chunks based on sector and sigma_xy
|
||||
Output->>Matcher: Try SP+LG/GIM-LG over candidates
|
||||
alt Inline match succeeds
|
||||
Matcher-->>Output: Absolute pose + covariance
|
||||
else Inline match fails and fallback allowed
|
||||
Output->>LiteSAM: Rare fallback match request
|
||||
LiteSAM-->>Output: Absolute pose candidate
|
||||
end
|
||||
Output->>Output: Gate against VO/dead-reckoned prior
|
||||
Output->>FDR: Re-loc attempt and result
|
||||
```
|
||||
|
||||
### Flowchart
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
trigger([Re-loc trigger]) --> chooseK[Choose K by sector and sigma_xy]
|
||||
chooseK --> vpr[VPR retrieval]
|
||||
vpr --> inline[Run inline matcher over candidates]
|
||||
inline --> inlineOk{Good inliers and MRE?}
|
||||
inlineOk -->|Yes| pnp[PnP absolute pose]
|
||||
inlineOk -->|No| fallbackAllowed{LiteSAM fallback allowed?}
|
||||
fallbackAllowed -->|Yes| litesam[Run LiteSAM rare fallback]
|
||||
fallbackAllowed -->|No| noFix[No anchor this frame]
|
||||
litesam --> pnp
|
||||
pnp --> gate[Mahalanobis gate]
|
||||
gate --> recovered{Gate passes?}
|
||||
recovered -->|Yes| anchor[Emit satellite_anchored fix]
|
||||
recovered -->|No| noFix
|
||||
noFix --> escalate[Continue VO/dead reckoning and update failure counters]
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
| Step | From | To | Data | Format |
|
||||
|------|------|----|------|--------|
|
||||
| 1 | Output stage | VPR | Predicted position, sector type, sigma_xy | Re-loc request |
|
||||
| 2 | VPR | Matcher | Candidate chunks | Chunk list |
|
||||
| 3 | Matcher/LiteSAM | Output stage | Correspondences, pose, covariance | Pose candidate |
|
||||
| 4 | Output stage | FDR | Attempt metadata | FlatBuffers record |
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| No candidate chunk | VPR | Empty result | Expand window to K=50; if still empty, no anchor. |
|
||||
| Stale tile match | Matcher/output | Tile freshness metadata invalid | Reject or downgrade; never emit `satellite_anchored` from stale tile. |
|
||||
| LiteSAM too slow | Fallback | Exceeds rare-path budget | Record timeout; continue dead reckoning/failsafe logic. |
|
||||
|
||||
### Performance Expectations
|
||||
|
||||
| Metric | Target | Notes |
|
||||
|--------|--------|-------|
|
||||
| Inline re-loc pair latency | <=200 ms per candidate path target | Bench-off decides exact settings. |
|
||||
| LiteSAM fallback | <=2 s rare-path budget | Not part of steady-state p95. |
|
||||
| Cold-start TTFF | <30 s p95 | F7 includes full boot budget. |
|
||||
|
||||
---
|
||||
|
||||
## Flow F5: In-Flight Tile Generation & Local Write
|
||||
|
||||
### Description
|
||||
|
||||
When a frame has a high-confidence satellite-anchored pose, the system may orthorectify it into the z=19 basemap projection and write a candidate tile into the local cache with sidecar metadata.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- Current source label is `satellite_anchored`.
|
||||
- Parent pose sigma_xy <=5 m for hard write eligibility.
|
||||
- Terrain class is flat or moderate, not rugged.
|
||||
- DEM and camera intrinsics are available.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Output as C-5 Output Stage
|
||||
participant Ortho as C-1b Ortho Generator
|
||||
participant Cache as C-1 Tile Cache
|
||||
participant FDR as C-10 FDR
|
||||
|
||||
Output->>Ortho: Eligible frame + pose + covariance
|
||||
Ortho->>Ortho: Orthorectify with Orthority + DEM
|
||||
Ortho->>Ortho: Score quality and deduplicate
|
||||
Ortho->>Cache: Transactional candidate/soft tile write
|
||||
Cache-->>Ortho: Write result
|
||||
Ortho->>FDR: Tile-generation event and sidecar metadata
|
||||
```
|
||||
|
||||
### Flowchart
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
candidate([Frame candidate]) --> eligible{source=satellite_anchored and sigma<=5m?}
|
||||
eligible -->|No| skip[Skip tile generation]
|
||||
eligible -->|Yes| terrain{Terrain allowed?}
|
||||
terrain -->|No| skip
|
||||
terrain -->|Yes| ortho[Orthorectify with DEM + camera model]
|
||||
ortho --> quality{Quality and dedup pass?}
|
||||
quality -->|No| thumb[Record failure thumbnail <=0.1 Hz]
|
||||
quality -->|Yes| write[Write MBTiles transaction + sidecar]
|
||||
write --> record[FDR tile-generation event]
|
||||
thumb --> record
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
| Step | From | To | Data | Format |
|
||||
|------|------|----|------|--------|
|
||||
| 1 | Output stage | Ortho generator | Frame, pose, covariance, source label | ROS 2/local message |
|
||||
| 2 | Tile cache | Ortho generator | Existing tile metadata | SQLite/sidecar |
|
||||
| 3 | Ortho generator | Tile cache | Candidate/soft tile and metadata | MBTiles transaction |
|
||||
| 4 | Ortho generator | FDR | Quality, write decision, failure thumbnail reference | FlatBuffers record |
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Orthority latency too high | F-T14/runtime metric | >50 ms/frame budget | Switch implementation to OpenCV + bilinear DEM fallback after validation. |
|
||||
| Pose covariance too high | Eligibility | sigma_xy >5 m | Skip write; do not poison cache. |
|
||||
| Service tile overwrite risk | Dedup/write | Existing trusted tile within freshness budget | Do not overwrite service-source tile. |
|
||||
| Cache write failure | SQLite/MBTiles | Transaction fails | Log event; keep localization running. |
|
||||
|
||||
### Performance Expectations
|
||||
|
||||
| Metric | Target | Notes |
|
||||
|--------|--------|-------|
|
||||
| Orthorectification latency | <=50 ms/frame budget | Measured on Orin Nano Super. |
|
||||
| Misaligned tile probability | >30 m <1%; >100 m <0.1% per flight | AC-NEW-7 Monte Carlo gate. |
|
||||
|
||||
---
|
||||
|
||||
## Flow F6: Post-Flight Candidate Tile Upload
|
||||
|
||||
### Description
|
||||
|
||||
After landing, candidate tiles generated during flight are uploaded from the local cache boundary to the Suite Satellite Service candidate pool. The Service owns voting and trusted-basemap promotion.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- Aircraft has landed and post-flight network is available.
|
||||
- Candidate tiles and sidecars are present.
|
||||
- Suite Service credentials are available in the approved ground context.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Operator
|
||||
participant Uploader as Post-Flight Uploader
|
||||
participant Cache as C-1 Tile Cache
|
||||
participant Service as Suite Satellite Service
|
||||
participant FDR as C-10 FDR
|
||||
|
||||
Operator->>Uploader: Start post-flight sync
|
||||
Uploader->>Cache: Enumerate candidate/soft tiles
|
||||
Cache-->>Uploader: Tile payloads and sidecars
|
||||
Uploader->>Service: Upload candidate pool batch
|
||||
Service-->>Uploader: Accepted/rejected result
|
||||
Uploader->>FDR: Record upload summary
|
||||
```
|
||||
|
||||
### Flowchart
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
start([Post-flight sync]) --> enumerate[Enumerate candidate tiles]
|
||||
enumerate --> any{Any candidates?}
|
||||
any -->|No| done([Nothing to upload])
|
||||
any -->|Yes| upload[Upload batch to Suite Service candidate pool]
|
||||
upload --> accepted{Accepted?}
|
||||
accepted -->|Yes| mark[Mark uploaded locally]
|
||||
accepted -->|No| retry[Keep pending with failure reason]
|
||||
mark --> done
|
||||
retry --> done
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
| Step | From | To | Data | Format |
|
||||
|------|------|----|------|--------|
|
||||
| 1 | Tile cache | Uploader | Candidate tiles and sidecars | Local files/SQLite |
|
||||
| 2 | Uploader | Suite Service | Candidate upload batch | Service API contract |
|
||||
| 3 | Suite Service | Uploader | Accepted/rejected records | API response |
|
||||
| 4 | Uploader | FDR/log | Upload summary | FlatBuffers/log record |
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Network unavailable | Upload | Connection failure | Keep candidates pending; retry on next post-flight sync. |
|
||||
| Service rejects tile | Service ingest | Rejection response | Record reason; do not mark uploaded. |
|
||||
| Contract mismatch | Upload payload | Schema/API error | Block upload and raise integration issue with `../satellite-service/`. |
|
||||
|
||||
### Performance Expectations
|
||||
|
||||
| Metric | Target | Notes |
|
||||
|--------|--------|-------|
|
||||
| Upload timing | Post-flight, not flight-critical | Can retry without affecting flight safety. |
|
||||
| Promotion | Service-owned | This build never marks tiles trusted. |
|
||||
|
||||
---
|
||||
|
||||
## Flow F7: Cold Start, Spoofing Promotion & Failsafe
|
||||
|
||||
### Description
|
||||
|
||||
This flow covers safety state changes around boot, GPS denial/spoofing, promotion to primary GPS substitute, and output failure. It keeps FC behavior explicit and makes QGC telemetry a status surface, not a control-plane dependency.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- FC is configured by F1.
|
||||
- Runtime has access to FC GPS/EKF health telemetry.
|
||||
- Mission cache is loaded for cold-start matching.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Runtime as GPS-Denied Runtime
|
||||
participant FC as ArduPilot FC
|
||||
participant Reloc as F4 Re-Localization
|
||||
participant QGC as QGroundControl
|
||||
participant FDR as C-10 FDR
|
||||
|
||||
Runtime->>FC: Connect with signed MAVLink
|
||||
FC-->>Runtime: Last EKF position + GPS/EKF health
|
||||
Runtime->>Reloc: Cold-start first fix
|
||||
Reloc-->>Runtime: Valid anchor or no-fix
|
||||
alt GPS denial/spoofing detected
|
||||
FC-->>Runtime: GPS health degraded
|
||||
Runtime->>FC: Promote signed GPS_INPUT within <3 s
|
||||
Runtime->>QGC: STATUSTEXT promotion status via FC
|
||||
end
|
||||
alt No output >3 s
|
||||
FC->>FC: Fall back to IMU-only dead reckoning
|
||||
Runtime->>QGC: Degraded/failsafe status via FC
|
||||
end
|
||||
Runtime->>FDR: Boot, promotion, failsafe events
|
||||
```
|
||||
|
||||
### Flowchart
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
boot([Runtime boot]) --> connect[Signed MAVLink connect]
|
||||
connect --> init[Read last FC EKF position]
|
||||
init --> firstFix[Run cold-start re-localization]
|
||||
firstFix --> ttff{First fix <30s?}
|
||||
ttff -->|Yes| normal[Normal GPS_INPUT output]
|
||||
ttff -->|No| degraded[Degraded status and continued re-loc]
|
||||
normal --> gpsHealth{FC reports GPS denial/spoofing?}
|
||||
gpsHealth -->|Yes| promote[Promote our GPS_INPUT primary within <3s]
|
||||
gpsHealth -->|No| monitor[Monitor output age]
|
||||
promote --> monitor
|
||||
degraded --> monitor
|
||||
monitor --> gap{No position >3s?}
|
||||
gap -->|Yes| failsafe[FC IMU-only dead reckoning + log]
|
||||
gap -->|No| normal
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
| Step | From | To | Data | Format |
|
||||
|------|------|----|------|--------|
|
||||
| 1 | FC | Runtime | EKF position, GPS health, status | MAVLink |
|
||||
| 2 | Runtime | FC | Signed GPS_INPUT | MAVLink |
|
||||
| 3 | Runtime | QGC | Status summary / STATUSTEXT via FC | MAVLink |
|
||||
| 4 | Runtime | FDR | Boot, promotion, failsafe events | FlatBuffers record |
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Cold-start no fix | First re-loc | TTFF budget exceeded | Continue re-loc, report degraded, FC continues own fallback behavior. |
|
||||
| Spoofing not promoted | Health monitor | Promotion >3 s | Fails AC-NEW-2; record and investigate. |
|
||||
| Output gap | Runtime output | >3 s without fix | FC falls back to IMU-only dead reckoning. |
|
||||
| Signing failure | MAVLink link | FC rejects frames | Do not bypass signing in flight; report unsafe state. |
|
||||
|
||||
### Performance Expectations
|
||||
|
||||
| Metric | Target | Notes |
|
||||
|--------|--------|-------|
|
||||
| Cold-start first fix | <30 s p95 | From companion boot to first valid GPS_INPUT. |
|
||||
| Spoofing promotion | <3 s p95 | From FC GPS-denial signal. |
|
||||
| Failsafe output gap | >3 s | FC fallback threshold. |
|
||||
|
||||
---
|
||||
|
||||
## Flow F8: AI-Camera Object Localization
|
||||
|
||||
### Description
|
||||
|
||||
Other onboard AI systems can request the coordinates of an object detected by the AI camera. The system projects the object using current GPS-Denied position, altitude, AI-camera gimbal angle, zoom, and level-flight assumptions.
|
||||
|
||||
### Preconditions
|
||||
|
||||
- Current GPS-Denied position estimate is available with confidence.
|
||||
- AI-camera gimbal angle and zoom are available.
|
||||
- Flight altitude is available.
|
||||
- Request is scoped to level flight accuracy unless the caller accepts the published maneuvering error bound.
|
||||
|
||||
### Sequence Diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant AI as AI Detection System
|
||||
participant Obj as C-8 Object Localization
|
||||
participant Pose as C-5 Current Pose
|
||||
participant FC as FC Telemetry
|
||||
participant FDR as C-10 FDR
|
||||
|
||||
AI->>Obj: Object pixel/box + camera metadata
|
||||
Obj->>Pose: Request current GPS-Denied pose
|
||||
Pose-->>Obj: WGS84 position + sigma_xy + source label
|
||||
FC-->>Obj: Altitude and attitude
|
||||
Obj->>Obj: Project object ray to ground plane
|
||||
Obj-->>AI: Object WGS84 coordinate + error bound
|
||||
Obj->>FDR: Object localization audit record
|
||||
```
|
||||
|
||||
### Flowchart
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
request([AI object request]) --> pose[Read current GPS-Denied pose]
|
||||
pose --> poseOk{Pose acceptable?}
|
||||
poseOk -->|No| reject[Return unavailable with reason]
|
||||
poseOk -->|Yes| inputs[Read gimbal angle, zoom, altitude]
|
||||
inputs --> level{Bank/pitch <5 deg?}
|
||||
level -->|Yes| project[Project object to ground plane]
|
||||
level -->|No| bound[Compute maneuvering error bound]
|
||||
bound --> project
|
||||
project --> result[Return WGS84 + confidence/error bound]
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
| Step | From | To | Data | Format |
|
||||
|------|------|----|------|--------|
|
||||
| 1 | AI system | Object localization | Object detection and camera metadata | Local API/topic |
|
||||
| 2 | Output stage | Object localization | Current pose and confidence | Runtime state/topic |
|
||||
| 3 | FC | Object localization | Altitude and attitude | MAVLink/ROS 2 |
|
||||
| 4 | Object localization | AI system | Object WGS84 and error bound | Response DTO/message |
|
||||
|
||||
### Error Scenarios
|
||||
|
||||
| Error | Where | Detection | Recovery |
|
||||
|-------|-------|-----------|----------|
|
||||
| Pose unavailable | C-5 current state | No current estimate or high sigma_xy | Return unavailable; do not invent coordinates. |
|
||||
| Maneuvering flight | FC attitude | bank/pitch >=5 degrees | Publish bounded error, lower confidence. |
|
||||
| Missing gimbal/zoom | AI-camera metadata | Required field absent | Reject request with explicit missing input. |
|
||||
|
||||
### Performance Expectations
|
||||
|
||||
| Metric | Target | Notes |
|
||||
|--------|--------|-------|
|
||||
| Response latency | Near-real-time local call | Not on FC safety-critical path. |
|
||||
| Accuracy | Consistent with frame-center accuracy in level flight | AC-7.1/AC-7.2 scoped behavior. |
|
||||
Reference in New Issue
Block a user