# Ground Station

Orange Pi Zero 3W supervisor and kiosk display for the custom OpenIPC/WFB ground station.

## Components

The ARM64 artifact intentionally contains two executables:

- `groundstation-linux-arm64` — the long-running root supervisor. It owns the GX12 UART, logging, RC state, video lifecycle, and starts the display process.
- `groundstation-display-linux-arm64` — the unprivileged X11 kiosk renderer. It runs as `orangepi` on `DISPLAY=:0`; the supervisor owns it during normal use.

Current capabilities:

- receives framed GX12 RC channel data at 115200 8N1;
- validates protocol version, frame length and CRC-16;
- logs channel changes instead of every frame;
- starts/stops `fpv-video` from the configured CH6 power/lifecycle control;
- starts an independent kiosk display before video, tolerates temporary X11 downtime without restarting the supervisor, and stops deterministically on shutdown;
- keeps the fullscreen fallback/menu canvas below `fpv-video`, showing `Brak połączenia WFB` only while video is absent;
- maps a transparent, input-transparent OSD overlay above `fpv-video` as the reserved flight OSD rendering surface: it never presents pixels over the video or intercepts its input.

Future MIPI/touch targets use their own templates rather than sharing one global layout. The flight OSD will render on the existing transparent layer above video, preserving the pilot stream's priority.

## Installation on Orange Pi

Extract the artifact and install **both** files:

```bash
sudo install -m 0755 groundstation-linux-arm64 /usr/local/bin/groundstation
sudo install -m 0755 groundstation-display-linux-arm64 /usr/local/bin/groundstation-display
sudo systemctl restart groundstation
```

Check logs:

```bash
systemctl status groundstation --no-pager
journalctl -u groundstation -b --no-pager -n 80
```

Do not run `groundstation-display` by hand during normal operation. It needs the X11 user/session environment and is managed by the supervisor. For isolated renderer debugging it supports:

```bash
groundstation-display -target x11
```

## Configuration

The service reads `/etc/groundstation/config.yml`. For the verified permanent GX12 connection, use:

```yaml
serial:
  path: /dev/ttyS2
```

`/dev/ttyS0` is the Orange Pi boot/debug UART and must not be used for the permanently connected GX12.

## Runtime dependencies

- X11 session on `:0` owned by `orangepi`; the kiosk waits for X11 and reconnects after display-manager restarts;
- `wmctrl` for the fullscreen/stacking kiosk window states; without it the kiosk windows map as normal windows and the condition is logged;
- `runuser` from util-linux for the unprivileged kiosk launch.