Get Started#

This guide walks through deploying uav-ground-station end to end: the UAV side it connects to, the base viewer, the optional VSS search overlay, multi-UAV use, and the Flight Summary report. See Configuration for the full .env variable reference.

Deploy the UAV Side First#

uav-ground-station is a remote viewer — it has nothing to show until a UAV host is already running pipelines it can connect to. Deploy one of these first, on a different machine than this one:

Either way, come back here once at least one camera pipeline is RUNNING.

You will need that host’s IP address in the next section.

Get the Ground-Station Source#

There are two options to get the application source first:

Option B — Clone the Whole Repository#

git clone https://github.com/open-edge-platform/federal-and-aerospace-ai-suite.git --branch main
cd federal-and-aerospace-ai-suite/uav-ground-station

Then, for either option:

make up      # creates .env from template (host IP and devices auto-detected), builds, and starts the container

make up runs make init, which sets VIZ_HOST_IP and VIZ_PUBLIC_HOST to this machine’s LAN IP and detects the GPU/NPU devices; edit .env only to override them (for example 127.0.0.1 for loopback-only access).

Note

make up starts only the viewer + mediamtx relay (video, captions, metrics, Flight Summary) — the Search Videos button and /api/search* stay hidden/404 until the separate VSS overlay is started with make up-vss instead of make up (it is not a flag to make up). See VSS Search below for the extra .env variables it needs and exactly what make up-vss adds.
make up-vss always includes everything make up does (viewer + mediamtx

  • the 8 VSS containers), so you only ever run one or the other, not both.
    Started with plain make up and want Search later? Just run make up-vss — it brings up the same viewer/mediamtx containers (unchanged, so this is fast) plus the missing VSS ones, in place.
    Dashboard, video, captions, Flight Summary, and per-host metrics work the same either way — only Search Videos depends on which one you ran. Tear down with the matching command: make down after make up, make down-vss after make up-vss (see the [!IMPORTANT] note below make down).

Note

make up and make up-vss check the ports this stack publishes (VIZ_PORT, MEDIAMTX_WEBRTC_PORT, the WebRTC ICE ports, and VSS_MANAGER_PORT) and move any that another process on this machine already uses to the next free port, saved in .env; the dashboard URL printed at the end uses the result. The UAV Mission Compute SDK publishes 8080 (REST), 8554 (RTSP), 8888 (HLS), and 8889 (WebRTC), so on a machine with the SDK installed the ground station takes 8081 and 8890 instead, and never one of those four, even while the SDK is stopped. Running the SDK and the ground station on separate machines is the intended setup; if you start the ground station first and install the SDK afterwards, the SDK’s own make fails on the ports the ground station holds, so start the SDK first or set different ports in .env yourself.

Then open http://<VIZ_HOST_IP>:<VIZ_PORT> (default port 8080; http://localhost:<VIZ_PORT> when VIZ_HOST_IP is 127.0.0.1), enter the UAV host’s IP from Deploy the UAV Side First (defaults to VIZ_COMPANION_HOST, 127.0.0.1), and press Connect. Device cards (cpu/gpu/npu) are detected automatically from whichever pipelines are currently running on the remote host.

make down    # stop and remove the stack started with make up
make logs    # tail the container's logs

Important

If you started with make up-vss, tear down with make down-vss (or make clean-vss-index / make delete-vss-volumes — see VSS Search), not plain make down: make down only targets docker-compose.yml + docker-compose-mediamtx.yml and leaves the 8 uav-gs-vss-* containers from docker-compose-vss.yml running.

Flight Summary#

The Flight Summary button (top bar) opens a report built from the MQTT scene-caption stream (uav/caption/<camera>) — the same captions shown live under each camera’s video. It works independently of VSS: no extra containers, no LLM call, always available once a camera’s pipeline is running with captioning on.

Generating a Flight Summary report from the scene captions

  1. uav-gs-backend keeps a small ring buffer of recent captions per (host, camera) (caption_log.py), kept warm only while the dashboard’s normal pipeline-info polling has observed that camera captioning; an idle (host, camera) pair is dropped after CAPTION_LOG_IDLE_TTL_SECONDS.

  2. Open Flight Summary, confirm the host (defaults to the connected UAV), pick one or more cameras from the list (populated from whichever cameras are currently captioning) and a time window, then Generate.

  3. vss_summary.py runs an extractive map-reduce over that camera’s buffered captions: consecutive near-identical captions are folded into one “scene” (with an occurrence count), a keyword tally feeds the overview paragraph, and a representative subset of scenes (favoring long-held/repeated ones, filled out with an even chronological spread of the rest) is kept per camera up to the requested highlight budget. With more than one camera selected, the timeline is grouped by camera — all of one camera’s highlights in order, then the next camera’s — rather than interleaved by arrival time, which is hard to follow once several cameras are captioning concurrently.

  4. Download PDF renders the same report via pdf_writer.py (a small, dependency-free PDF writer — no extra system packages).

If a search was just run, the report also appends the query and its matched clips as an “appendix”, tying a natural-language search back to the raw caption evidence around the same time window.

See Configuration for the report’s route reference.