docs: explain Ground Station artifact components

README.md

@@ -1,44 +1,61 @@
 # Ground Station
 
-Orange Pi Zero 3W application for the custom OpenIPC/WFB ground station.
+Orange Pi Zero 3W supervisor and kiosk display for the custom OpenIPC/WFB ground station.
 
-## Current baseline
+## Components
 
-- receives framed GX12 RC channel data over the dedicated AUX1 UART at 115200 8N1;
+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 final mixed channel values;
-- starts an independent kiosk display process that maps a fullscreen black canvas on `DISPLAY=:0` before video, tolerates X11 downtime without restarting the supervisor, and stops deterministically on shutdown;
-- video keeps rendering priority: the kiosk canvas stays below the `fpv-video` window, shows the exact fallback text `Brak połączenia WFB` only while no video output is presented, and future display targets (MIPI/touch) get their own target-specific templates instead of one global layout.
+- 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 fallback canvas below `fpv-video`, with `Brak połączenia WFB` while video is absent.
 
-The first baseline is intentionally small. It does **not** yet control an AUX, manipulate the flight-control link, or replace the primary video pipeline.
+Future MIPI/touch targets use their own template rather than sharing one global layout. Flight OSD will use a separate transparent layer above video, preserving the pilot stream's priority.
 
-## Run
+## Installation on Orange Pi
+
+Extract the artifact and install **both** files:
 
 ```bash
-# Supervisor (YAML configuration, default /etc/groundstation/config.yml;
-# hardware UART paths live in the config file)
-groundstation -config /etc/groundstation/config.yml
+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
+```
 
-# Test input mode
-groundstation -stdin
+Check logs:
 
-# Kiosk canvas alone (the supervisor starts it; standalone for debugging)
+```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
 
-- an X11 session on `:0` owned by the `orangepi` desktop user (the kiosk waits for X11 to appear and reconnects after display-manager restarts);
-- `wmctrl` for the fullscreen/below kiosk window state — without it the canvas still maps but stays a plain window (logged);
-- `runuser` from util-linux (base install) for the unprivileged kiosk launch.
-
-## Protocol
-
-The v1 protocol is described in `AGENTS.md` once the repository policy file is approved. It carries 16 final EdgeTX channel outputs as a binary framed message with CRC.
-
-## Project direction
-
-1. GX12 Ground Station UART mode sends final RC/switch state to Orange Pi.
-2. Orange Pi logs and renders state while supervising the FPV video launcher.
-3. Add WFB quality, recorder state, and MIPI touch display independently of pilot video.
-4. Add a watchdog-protected override of exactly one reserved `SAFE/NORMAL/HIGH` AUX.
+- X11 session on `:0` owned by `orangepi`; the kiosk waits for X11 and reconnects after display-manager restarts;
+- `wmctrl` for fullscreen/below kiosk state; without it the canvas maps as a normal window and the condition is logged;
+- `runuser` from util-linux for the unprivileged kiosk launch.