Enable NPU Inference#
NPU is a first-class supported inference device — it has its own pipeline
entries (..._npu) selectable per camera in configs/cameras-pymavlink.yaml
(detection.device: npu) — but it requires hardware detection at make init
time and has a couple of recognizable failure modes. This tutorial covers
one-time hardware/driver enablement end-to-end. Once done, switching a
camera to (or away from) the NPU is a one-line change in the camera file, see
Configure the Cameras.
Prerequisites#
An Intel NPU (e.g., Intel® Core™ Ultra Series 1 or Intel® Core™ Ultra Series 3) with the NPU driver installed on the host.
The stack not yet started for this session (or willing to restart it).
Steps#
1. Confirm the NPU device node exists on the host#
ls /dev/accel/
# expected: accel0 (or similar)
If this directory does not exist or is empty, the NPU driver is not installed / loaded on the host — install it before continuing (outside the scope of this app).
2. Detect and wire it via make init#
make init
make init scans /dev/accel/ and writes the first match to .env:
✅ NPU detected:
NPU_DEVICE=/dev/accel/accel0
make init skips entirely if .env already exists — if you added the
NPU after your first make init, either delete .env and re-run it, or set
NPU_DEVICE manually:
echo "NPU_DEVICE=/dev/accel/accel0" >> .env
3. Verify the compose wiring#
docker-compose-pymavlink.yml (and the UAVSDK compose file) already pass
NPU_DEVICE through as both a device mount and an environment variable:
environment:
- ZE_ENABLE_ALT_DRIVERS=libze_intel_npu.so
- NPU_DEVICE=${NPU_DEVICE:-/dev/null}
devices:
- ${NPU_DEVICE:-/dev/null}:${NPU_DEVICE:-/dev/null}
No manual edits are needed here — this is just what makes NPU_DEVICE from
.env reach the container. ZE_ENABLE_ALT_DRIVERS enables the NPU OpenVINO™
plugin and is already set by default.
4. Restart the stack so the container picks up the device#
make pymav-down && make pymav-up
5. Start a camera on the NPU#
Set detection.device: npu for a camera in configs/cameras-pymavlink.yaml
(see Configure the Cameras), then:
make check-cameras
make start-rtsp
ffplay -rtsp_transport tcp rtsp://<HOST_IP>:8555/uav-front-camera
Verify#
curl -k -s https://<HOST_IP>/pipelines/status | python3 -m json.tool
Confirm the ..._npu pipeline shows "state": "RUNNING", and that
dmesg | grep -i npu on the host shows no driver errors.
Troubleshooting#
[pipeline] Skipping ... NPU_DEVICE not available, a poisoned
model-instance-id, and the driver checks are covered in
Troubleshooting — NPU inference fails.
Until the NPU is detected, set the camera to cpu or gpu; make check-cameras reports an NPU camera as unavailable rather than silently
falling back.