groundstation/README.md

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;
• publishes immutable flight OSD snapshots — final RC channels, arm state derived from the configured arm channel, the adaptive-link contract values (operator target table, temporary CH6 maxPower ceiling, requested runtime level, VTX acknowledgment, observed link — pending/unknown until their producers exist) and decoded-video presence — to a tmpfs state file without ever blocking the UART, WFB or video paths; unchanged state is republished as a heartbeat and the file is removed on shutdown;
• 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 flight OSD rendering surface: it never intercepts video input, and it punches its output shape only around the text it draws;
• renders the flight OSD from startup on the transparent overlay — on top of the no-video fallback presentation and above fullscreen video alike: the arm state, the compact adaptive-link line, and an explicit VIDEO ON/OFF line sourced from the display-observed video lifecycle; before any snapshot has arrived it shows explicit NO DATA / unknown marks, and a snapshot beyond the freshness window stays visible marked DATA STALE instead of being presented as current — refreshing on a slower cadence than the video so the pilot stream keeps priority.

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

Installation on Orange Pi

Extract the artifact and install both files:

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:

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:

groundstation-display -target x11

Configuration

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

serial:
  path: /dev/ttyS2

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

The flight OSD is configured alongside:

osd:
  state_path: /run/groundstation/osd-state.bin
  arm_index: 4        # CH5/AUX1, zero-based
  armed_threshold: 0  # armed while the arm channel stays above this
  vtx_table_gen: 0    # operator-selected VTX table (0 = none selected)
  vtx_table_hash: 0

CH6 acts only as the temporary operator maxPower ceiling and static configuration is never applied VTX state. groundstation-display reads the same state file; both sides must agree on the path (override the renderer's with groundstation-display -osd-state <path> if you change osd.state_path). The state file carries only flight telemetry and never any credentials or keys.

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.