gps-denied-onboard/_docs/02_tasks/done/AZ-394_c8_inav_outbound.md

C8 Msp2InavAdapter — outbound MSP2_SENSOR_GPS

Task: AZ-394_c8_inav_outbound Name: C8 Msp2InavAdapter outbound — MSP2_SENSOR_GPS 5 Hz (D-C8-8 = (b)) Description: Implement the Msp2InavAdapter.emit_external_position(EstimatorOutput) body: encode EstimatorOutput into an MSP2 MSP2_SENSOR_GPS frame (lat/lon/alt × 1e7 in int32 per MSP2 convention; hPosAccuracy in mm from the injected CovarianceProjector.to_inav_h_pos_accuracy_mm; ground-speed/heading from C5 velocity sub-vector if present); write to the iNav UART via YAMSPy + INAV-Toolkit. Side-channel: emit STATUSTEXT (severity=INFO, "src=") on source_label transition (rate-limited) over the SECONDARY MAVLink telemetry channel (iNav supports MAVLink for telemetry but not for primary positioning per RESTRICT-COMM-2). Body of emit_status_text(msg, severity) writes to the secondary MAVLink channel. open(...) rejects any non-None signing_key per Invariant 2 (RESTRICT-COMM-2). request_source_set_switch raises SourceSetSwitchNotSupportedError (iNav has no equivalent). Smoothed-output guard (Invariant 6). SPD-violation propagates from projector (per Invariant 4). Single-writer-thread invariant (Invariant 8). Sequence-number management for MSP2 frames maintained internally. Complexity: 3 points Dependencies: AZ-390 (Protocol + DTOs + errors), AZ-392 (CovarianceProjector helper), AZ-279 (WgsConverter), AZ-273 (FDR), AZ-263, AZ-269, AZ-266, AZ-272 (FDR record schema) Component: c8_fc_adapter (epic AZ-261 / E-C8) Tracker: AZ-394 Epic: AZ-261 (E-C8)

Document Dependencies

• _docs/02_document/contracts/c8_fc_adapter/fc_adapter_protocol.md — Invariants 2, 3, 4, 6, 8, 9.
• _docs/02_document/components/10_c8_fc_adapter/description.md — § 3 External API (MSP2), § 5 implementation details.
• _docs/02_document/architecture.md — § 5 RESTRICT-COMM-2 (iNav signing-asymmetry).

Problem

Without this task, iNav-targeted flights cannot run: no MSP2_SENSOR_GPS is emitted to the iNav EKF; the system is AP-only. RESTRICT-COMM-2 documents iNav as a supported FC for the program; this task implements the wire surface.

Outcome

• src/gps_denied_onboard/components/c8_fc_adapter/msp2_inav_adapter.py — Msp2InavAdapter class implementing FcAdapter.
• Constructor: __init__(self, config, wgs_converter, covariance_projector, fdr_client, clock).
• Body of emit_external_position — encode + emit MSP2_SENSOR_GPS via YAMSPy.
• Body of emit_status_text — emit STATUSTEXT on the secondary MAVLink channel.
• Body of open(...) — open MSP2 UART; raise FcAdapterConfigError on signing_key != None (RESTRICT-COMM-2).
• Body of close() — close UART connection.
• request_source_set_switch raises SourceSetSwitchNotSupportedError.
• Internal sequence-number counter for MSP2 frames.
• INFO log on first MSP2_SENSOR_GPS emit: kind="c8.inav.first_emit".
• DEBUG log per emit: kind="c8.inav.emit" with {frame_seq, h_pos_accuracy_mm, source_label}.

Scope

Included

• Msp2InavAdapter class implementing FcAdapter.
• MSP2_SENSOR_GPS encoding from EstimatorOutput.
• STATUSTEXT side-channel via secondary MAVLink (transitions only, rate-limited).
• emit_status_text body.
• open / close body.
• Signing-key rejection (Invariant 2).
• request_source_set_switch not-supported.
• iNav signing-asymmetry assertion (Invariant 9): NEVER set the MAVLink2 signed-flag on the side-channel.
• Unit tests: encoding fidelity (decode via INAV-Toolkit reference), signing-key rejection, signing-asymmetry assertion (capture wire bytes, no signed-flag), source-set-switch unsupported, smoothed-output rejected.

Excluded

• AP outbound — owned by AP task.
• GCS adapter — owned by GCS task.
• Inbound subscription — owned by inbound task.
• C8-IT/PT/ST tests — deferred to E-BBT.

Acceptance Criteria

AC-1: MSP2_SENSOR_GPS field fidelity — emit a known EstimatorOutput; decode the wire bytes via INAV-Toolkit reference decoder; assert lat/lon/alt match WgsConverter output × 1e7; hPosAccuracy matches CovarianceProjector.to_inav_h_pos_accuracy_mm(cov_6x6).

AC-2: MSP2_SENSOR_GPS every frame — drive 100 frames; assert 100 MSP2 frames on the wire with monotonically incrementing sequence numbers.

AC-3: STATUSTEXT secondary channel transition — drive 100 frames with source_label toggling every 10 frames; assert exactly 10 STATUSTEXT on the secondary MAVLink channel; never on the primary MSP2 channel.

AC-4: Signing key rejection (Invariant 2) — open(port, signing_key=b"...") → FcAdapterConfigError("iNav does not support MAVLink signing per RESTRICT-COMM-2").

AC-5: Signing-asymmetry assertion (Invariant 9) — capture every byte the iNav adapter writes to the secondary MAVLink channel for 60 s; assert no frame has the MAVLink2 signed-flag set. (This is the unit-level form of C8-IT-08.)

AC-6: Source-set-switch not-supported — request_source_set_switch() → SourceSetSwitchNotSupportedError("iNav: no MAV_CMD_SET_EKF_SOURCE_SET equivalent").

AC-7: Smoothed output rejected — output.smoothed=True → FcEmitError (parallel to AC-5 of the AP task).

AC-8: Non-SPD covariance rejected — propagated from projector → FcEmitError.

AC-9: Single-writer thread — second-thread emit raises RuntimeError.

AC-10: First emit logged once — kind="c8.inav.first_emit" INFO log exactly once per open(...) lifetime.

Non-Functional Requirements

• emit_external_position p95 ≤ 5 ms (C8-PT-01 budget; iNav side mirrors AP side).

Constraints

• YAMSPy + INAV-Toolkit at the project's pinned versions.
• Single-writer thread enforced.
• Secondary MAVLink telemetry channel MUST never set the MAVLink2 signed-flag (Invariant 9).
• MSP2 wire format requires explicit sequence numbers — counter persisted in adapter instance state for the flight lifetime.

Risks & Mitigation

• Risk: YAMSPy + INAV-Toolkit cross-version drift — Mitigation: pinned versions; integration test against the targeted iNav firmware in IT-3 (separate SITL).
• Risk: int32 lat/lon overflow at extreme values — Mitigation: WgsConverter clamps to ±90° latitude / ±180° longitude before scaling; documented.
• Risk: Sequence number wrap-around mid-flight — Mitigation: sequence counter is uint8 per MSP2; modular increment is the wire convention; no special handling needed.

Runtime Completeness

• Named capability: iNav outbound external-position emission.
• Production code: real YAMSPy encode + send; real CovarianceProjector usage.
• Unacceptable substitutes: a MAVLink_GPS_INPUT_send against iNav (wrong wire format; defeats AC-1).

Contract

Implements _docs/02_document/contracts/c8_fc_adapter/fc_adapter_protocol.md — emit_external_position, emit_status_text for iNav; Invariants 2, 3, 4, 6, 8, 9.