Makefile Reference#
The Makefile at the root of uav-vision-analytics/ provides shorthand targets
for the most common development and deployment tasks.
Run make help (or just make) to list all targets with descriptions.
Quick Reference#
Target |
Description |
|---|---|
|
Create |
|
Download YOLO11s checkpoint and export to OpenVINO™ FP16 |
|
Download and convert the VLM captioning model (OpenVINO™ IR) for CPU and GPU |
|
Rebuild the locally built Pymavlink images (requires network access) |
|
Start the standalone Pymavlink stack (requires model — errors if missing); builds images only if they do not exist yet |
|
Stop and remove the Pymavlink stack (includes volumes) |
|
Start the uav-mission-compute-sdk stack |
|
Stop and remove the uav-mission-compute-sdk stack (includes volumes) |
|
Start the cameras of |
|
Validate |
|
Compare |
|
Alias for |
Target Details#
make init#
Creates .env from .env.example (skipped if .env already exists) and
auto-detects Intel GPU and NPU device paths, writing them into .env so
docker compose picks them up automatically.
GPU: scans
/dev/dri/forcard*andrenderD*entries → setsGPU_DEVICEandGPU_RENDER_DEVICEHost IP: takes the first address of
hostname -I→ setsHOST_IP(falls back to127.0.0.1)USB / RealSense camera: sets
CAMERA_DEVICE_1(/dev/nullwhen none is found)NPU: scans
/dev/accel/foraccel*entries → setsNPU_DEVICE(defaults to/dev/nullif not found, disabling NPU pipelines)
make init
# .env created from .env.example
# ✅ GPU detected:
# GPU_DEVICE=/dev/dri/card1
# GPU_RENDER_DEVICE=/dev/dri/renderD128
# ✅ NPU detected:
# NPU_DEVICE=/dev/accel/accel0
Run this once before the first make pymav-up. On machines where the Intel
iGPU is assigned card1 instead of card0 (common on multi-GPU desktops),
this avoids the manual .env edit.
make model#
Both make model and make vlm-model show the model license and ask for confirmation first ([y/N]). Set ACCEPT_LICENSE=y to accept without the prompt.
Creates a Python virtual environment under resources/venv/, installs
dependencies from resources/requirements.txt, downloads the yolo11s.pt
checkpoint from Ultralytics, and exports it to OpenVINO™ FP16 IR format.
Note
make pymav-up checks for the model before starting containers.
If resources/models/yolo11s/yolo11s_openvino_model/yolo11s.xml is
missing it prints an error and exits — run make model first.
resources/
├── requirements.txt
├── venv/ ← created by this target
└── models/
└── yolo11s/
├── yolo11s.pt ← downloaded checkpoint
└── yolo11s_openvino_model/ ← exported IR (yolo11s.xml + yolo11s.bin)
Important
ultralytics is pinned to 8.4.67. Do not upgrade without
re-verifying GPU/NPU compatibility — newer versions use a CumSum-based
detection head that fails to compile on Intel GPU and NPU OpenVINO™ plugins.
make vlm-model#
Downloads OpenGVLab/InternVL2-1B and converts it to OpenVINO™ IR under resources/ov_models/<device>/. Needed for camera
captions. The conversion script is fetched from the live-video-captioning app at a pinned commit and cached in .cache/
(FORCE_REFRESH=true fetches it again). Overrides: VLM_MODEL_ID, VLM_DEVICE (cpu,gpu by default; the VLM does not run on the NPU) and
VLM_WEIGHT_FORMAT (int8 by default).
make pymav-up / make pymav-down#
Manages the standalone Pymavlink stack (docker-compose-pymavlink.yml), which includes:
dlstreamer-pipeline-server— AI inference, REST API (:8081), RTSP output (:8555) — reached vianginxbroker— Eclipse Mosquitto MQTT broker (:1883)px4— PX4 SITL flight controller simulatormavlink-router— MAVLink routing sidecar (receives from PX4 on:14550, broadcasts to:14541, serves a remote QGroundControl on UDP:14551published onHOST_IP)metrics-manager— system metrics endpoint (:9090) — reached vianginxnginx— reverse proxy; the only service publishing ports to the host (:80,:443,:8555,:1883)
down passes -v to also remove named volumes (pipeline cache).
Before starting, pymav-up (and uavsdk-up) runs scripts/update_device_gids.sh, which writes the group IDs of the
GPU, NPU, and camera device nodes (GPU_CARD_GID, GPU_RENDER_GID, NPU_GID, CAMERA_GID) into .env; the compose
files pass them as group_add, so the non-root pipeline user can open the devices on any host. Nothing to do by hand.
Containers are named uav-va-<service> (for example uav-va-dlstreamer-pipeline-server), use those names with docker exec / docker logs.
The two stacks cannot run together: stop one (make pymav-down / make uavsdk-down) before starting the other.
Two images are built locally (the DL Streamer Pipeline Server with
pymavlink, and mavlink-router). make pymav-up builds them only the
first time, then starts the stack without rebuilding, so it works without
Internet access once the images and the base images exist locally. Run
make pymav-build to rebuild them deliberately, for example after changing
DLSTREAMER_PIPELINE_SERVER_IMAGE.
make uavsdk-up / make uavsdk-down#
Manages the uav-mission-compute-sdk stack (docker-compose-uavsdk.yml),
which requires the federal-and-aerospace-ai-suite/uav-mission-compute-sdk
project to already be running.
Start order:
# 1. Start the SDK project (provides PX4, MQTT telemetry)
cd ../uav-mission-compute-sdk && make up-sim-camera
# 2. Start this application
cd ../uav-vision-analytics && make uavsdk-up
down passes -v to also remove named volumes.
make start-rtsp#
Executes pipeline_manager.py inside the running uav-va-dlstreamer-pipeline-server container. It monitors the MAVLink
ARMED/DISARMED state and starts/stops one inference pipeline per camera of configs/cameras-pymavlink.yaml, each with
RTSP frame output on port :8555 (rtsp://<HOST_IP>:8555/uav-<camera>). The file is read when the manager starts
and again at every arming, so after an edit you either run make start-rtsp again or disarm and arm. CAMERAS=<file>
uses another configuration file.
make check-cameras # validate the file and show what would run (nothing is started)
make start-rtsp # start the cameras on arming
make cameras-status # file versus running pipelines
See Configure the Cameras for
the file format. Requires the DL Streamer Pipeline Server container to already be running
(make pymav-up first). Also used in UAV Mission Compute SDK mode: the container’s
CAMERAS_CONFIG env var (set to configs/cameras-uavsdk.yaml by docker-compose-uavsdk.yml)
is the default file read there; CAMERAS=<file> overrides it in either mode.
make build#
Convenience alias for make pymav-up. Starts the default standalone stack.
Common Workflows#
First-time setup#
# 0. Install system prerequisites
sudo apt install python3.12-venv ffmpeg
# 1. Create .env and auto-detect the host IP, GPU, NPU, and camera devices
make init
# 2. Download and export the detection model, and download the VLM used for captions
make model
make vlm-model
# 3. Start the stack
make pymav-up
# 4. Start inference pipelines
make start-rtsp
Stop everything and clean up#
make pymav-down
Switch to uav-mission-compute-sdk mode#
make pymav-down # stop standalone stack if running
cd ../uav-mission-compute-sdk && make up-sim-camera # start SDK project
cd ../uav-vision-analytics && make uavsdk-up # start uav-vision-analytics against the SDK
make start-rtsp