# 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. |