# Component — `gimbal_controller`

**Layer**: Action (data plane out)
**Status**: forward-looking design (Rust); ViewPro A40 vendor protocol

## 1. Purpose

Drives the ViewPro A40 gimbal: pan (yaw), tilt (pitch), and zoom. Honours the ≤2 s zoom-transition budget and ≤500 ms decision-to-movement latency. Owns the zoom-out sweep, the smooth-pan path-tracking primitive used during the zoom-in level (follow-the-footpath behaviour), and the centre-window primitive used during target-follow.

## 2. Inputs

| Input | Source | Cadence | Notes |
|---|---|---|---|
| `GimbalCommand` | `scan_controller` | per state-machine tick or per zoom-in plan step | yaw / pitch / zoom goal; or pan plan; or centre-on-target. |
| Sweep config | startup config | once | Zoom-out sweep pattern (pendulum / raster / lawn-mower — see `architecture.md §8 Q1`). |
| Live gimbal status | ViewPro A40 (vendor protocol) | as emitted by camera | yaw / pitch / zoom feedback + faults. |

## 3. Outputs

| Output | Consumer | Shape |
|---|---|---|
| Vendor-protocol commands | ViewPro A40 (UDP) | yaw / pitch / zoom commands |
| `GimbalState` | `frame_ingest` (for telemetry tagging), `movement_detector` (for ego-motion compensation) | `{ yaw, pitch, zoom, ts_monotonic, command_in_flight: bool }` |
| Health metric | health aggregator | `commands_per_min`, `decision_to_movement_p99_ms`, `zoom_transition_p99_ms`, `vendor_faults_total`. |

## 4. Key Responsibilities

- Send vendor-protocol commands to the ViewPro A40 over UDP. Re-issue on timeout with bounded retry.
- Run the zoom-out sweep pattern when `scan_controller` is in `ZoomedOut` (pattern itself depends on `architecture.md §8 Q1` resolution).
- For the zoom-in path-follow, accept a pan plan (sequence of yaw / pitch / zoom goals with timing) from `scan_controller` / `semantic_analyzer` and execute it smoothly.
- For target-follow, accept a centre-on-target stream (target bbox normalized) from `scan_controller` and command the gimbal to keep the target inside the centre 25 % of frame while visible.
- Stamp every emitted command with a monotonic timestamp so `movement_detector` can synchronise it with frames.
- Surface vendor-protocol faults to health and to `scan_controller`.

## 5. Internal State

- Last-known commanded yaw / pitch / zoom.
- Last-known reported yaw / pitch / zoom (from gimbal feedback).
- Sweep pattern state (current direction, dwell counter).
- Current execution mode: `Sweep | PanPlan | CentreOnTarget | Idle`.

State is in-process only.

## 6. Failure Modes

| Failure | Detection | Behaviour |
|---|---|---|
| ViewPro A40 not responding | command timeout | Bounded exponential backoff; health → yellow then red; `scan_controller` is informed and may pause zoom-in. |
| Decision-to-movement above budget | self-instrumented | Health → yellow; investigate (likely UDP loss or vendor firmware issue). |
| Zoom transition stalls | feedback shows no zoom progress | Re-issue command; health → yellow; report to `scan_controller`. |
| Target lost during target-follow | feedback + tracker | Surface `target_lost` to `scan_controller`; controller decides to release follow. |
| Conflicting commands | execution-mode mismatch | Reject the lower-priority command; log a hard error; never silently merge. |

## 7. Dependencies

**In-process** (input): `scan_controller`.
**In-process** (output): `frame_ingest`, `movement_detector` (timestamped state).

**External**: ViewPro A40 over UDP (vendor protocol).

## 8. Non-Functional Targets

| Concern | Target |
|---|---|
| Decision-to-movement latency | ≤500 ms |
| Zoom transition (medium → high) | ≤2 s |
| Sweep pattern stability | bounded jitter; no overshoot beyond configured FOV bounds |
| Target-follow centre-window | target inside centre 25 % of frame while visible |

## 9. Open Questions

- Sweep pattern specification (`architecture.md §8 Q1`): pendulum / raster / lawn-mower; FOV per zoom tier; dwell time per direction.

## 10. References

- `architecture.md §3`, `§6 NFR`, `§7.6 Solution Architecture`.
- `system-flows.md §F2 Movement detection (zoom-out + zoom-in)`.
- `data_model.md §GimbalState`.