docs: explain Ground Station artifact components
Build Ground Station / build (push) Successful in 35s
Build Ground Station / build (push) Successful in 35s
This commit is contained in:
@@ -1,44 +1,61 @@
|
|||||||
# Ground Station
|
# 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;
|
- validates protocol version, frame length and CRC-16;
|
||||||
- logs final mixed channel values;
|
- logs channel changes instead of every frame;
|
||||||
- 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;
|
- starts/stops `fpv-video` from the configured CH6 power/lifecycle control;
|
||||||
- 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.
|
- 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
|
```bash
|
||||||
# Supervisor (YAML configuration, default /etc/groundstation/config.yml;
|
sudo install -m 0755 groundstation-linux-arm64 /usr/local/bin/groundstation
|
||||||
# hardware UART paths live in the config file)
|
sudo install -m 0755 groundstation-display-linux-arm64 /usr/local/bin/groundstation-display
|
||||||
groundstation -config /etc/groundstation/config.yml
|
sudo systemctl restart groundstation
|
||||||
|
```
|
||||||
|
|
||||||
# Test input mode
|
Check logs:
|
||||||
groundstation -stdin
|
|
||||||
|
|
||||||
# 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
|
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
|
## 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);
|
- X11 session on `:0` owned by `orangepi`; the kiosk waits for X11 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);
|
- `wmctrl` for fullscreen/below kiosk state; without it the canvas maps as a normal window and the condition is logged;
|
||||||
- `runuser` from util-linux (base install) for the unprivileged kiosk launch.
|
- `runuser` from util-linux 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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user