# MAVLink GCS Gateway

**Task**: AZ-224_mavlink_gcs_gateway
**Name**: MAVLink GCS Gateway
**Description**: Subscribe to FC telemetry, emit `GPS_INPUT`, and publish QGC-visible status/failsafe messages.
**Complexity**: 3 points
**Dependencies**: AZ-220_shared_runtime_contracts, AZ-222_runtime_config_errors_telemetry
**Component**: MAVLink And GCS Integration
**Tracker**: AZ-224
**Epic**: AZ-210

## Problem

The runtime needs a strict protocol boundary for ArduPilot Plane telemetry in and GPS-denied estimates/status out.

## Outcome

- FC telemetry is normalized into shared samples.
- `GPS_INPUT` is emitted only from validated position estimates.
- QGC status is rate-limited and safety-relevant.

## Scope

### Included
- Telemetry subscription behavior.
- `GPS_INPUT` field validation and emission result.
- QGC status/failsafe message emission.

### Excluded
- Safety policy and covariance calculation.
- SITL test runner implementation.

## Dependencies

### Document Dependencies
- `_docs/02_document/contracts/shared/runtime_contracts.md`
- `_docs/02_document/contracts/shared/config_errors_telemetry.md`

## Acceptance Criteria

**AC-1: Telemetry sample emitted**
Given a valid FC telemetry stream
When the gateway subscribes
Then normalized telemetry samples are available to consumers.

**AC-2: Invalid GPS_INPUT is rejected**
Given a malformed or unsafe position estimate
When emission is requested
Then no invalid `GPS_INPUT` packet is emitted.

**AC-3: Operator status is rate-limited**
Given repeated mode changes or warnings
When status is emitted
Then QGC-visible messages stay within the configured rate.

## Non-Functional Requirements

**Reliability**
- Connection loss is surfaced to wrapper/FDR.

## Unit Tests

| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Telemetry normalization | Shared sample emitted |
| AC-2 | Invalid fix type/accuracy | Emission rejected |
| AC-3 | Status burst | Rate limit enforced |

## Blackbox Tests

| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-2 | Plane SITL | `GPS_INPUT` output | Fields match ArduPilot expectations | Reliability |

## Constraints

- v1 emits `GPS_INPUT` only.
- Do not hide MAVLink disconnects or invalid output errors.

## Risks & Mitigation

**Risk 1: ArduPilot parameter mismatch**
- *Risk*: Plane ignores or mishandles emitted estimates.
- *Mitigation*: SITL validation remains a release gate.