# Ground Station — agent guide

## Purpose

`groundstation` runs on Orange Pi Zero 3W as the control and observability process for the custom OpenIPC/WFB ground station.

It receives final mixed RC channels from RadioMaster GX12 through the dedicated AUX1 UART, logs/renders pilot state, and starts the independent `fpv-video` launcher for Viture.

## Safety boundaries

- Primary pilot video must remain independent. Never restart, block, or add buffering to WFB/video decode from this process.
- Never modify sticks, arm, flight mode, or existing AUX channels.
- The future reverse path may override exactly one explicitly reserved profile AUX with SAFE/NORMAL/HIGH.
- No valid heartbeat must return that AUX to its native EdgeTX SAFE value.
- UART wiring is 3.3 V TTL only: crossed TX/RX plus GND. Never connect header 5 V or AUX_BOOT.
- Do not use headtracking as a transport; it is reserved for a future Viture 3DoF gimbal aircraft.

## Wire protocol v1

```text
0x47 0x53             magic "GS"
1 byte                version (1)
1 byte                type
2 bytes little-endian sequence
4 bytes little-endian millisecond timestamp
N bytes               payload
2 bytes little-endian CRC-16/CCITT-FALSE over all preceding bytes
```

`type=1` is `RCChannels`: payload contains 16 signed little-endian int16 values in final EdgeTX output units (`-1024..1024`). Validate length and CRC before accepting frames.

## Development

- Go is the implementation language.
- Use `golang.org/x/sys/unix` for Linux UART termios. Add `periph.io` only for real GPIO/SPI/I2C display work.
- Run `gofmt`, `go test ./...`, and `go vet ./...` before committing.
- Keep hardware paths CLI-configurable.
- Never commit credentials, Wi-Fi passwords, WFB keys, or live network addresses.

## Repository workflow

- `main` must remain deployable.
- Keep hardware changes focused and tested separately from protocol parsing.
- Grzesiu may maintain focused Gitea issues after the baseline protocol and hardware acceptance are recorded.