Hailo-8 Runtime Setup and CV Model Deployment

Use this guide to verify the Hailo-8 runtime and deploy an AI Lab CV model on a Raspberry Pi CM5 with a PCIe Hailo-8 accelerator. This page covers the common device, runtime, and container workflow. Model-specific image names, HEF names, and post-processing arguments remain on each model card.

1. Verify the Device

Run these commands on the Raspberry Pi before starting a container:

bash

lspci -nn | grep -i hailo
lsmod | grep hailo
hailortcli --version
ls -l /dev/hailo0
sudo hailortcli fw-control identify

Expected result: the PCIe device is identified as Hailo-8, the Hailo PCIe driver is loaded, and /dev/hailo0 exists. The HailoRT release installed on the host must match the release expected by the image and HEF.

2. Pull the Model Image

Use the exact image shown on the relevant AI Lab model card:

bash

sudo docker pull ghcr.io/seeed-projects/recomputer-hailo8-cv/<model>:latest

3. Run the Model

This is the standard Hailo-8 container shape. Replace the placeholders with the command from the model card; do not substitute a Hailo-10H image or HEF.

bash

sudo docker run --rm \
  --name cm5-hailo8-<model> \
  --privileged \
  --net=host \
  -e PYTHONUNBUFFERED=1 \
  --device /dev/hailo0:/dev/hailo0 \
  -v /usr/lib/libhailort.so.4.23.0:/usr/lib/libhailort.so.4.23.0:ro \
  -v /usr/lib/libhailort.so:/usr/lib/libhailort.so:ro \
  ghcr.io/seeed-projects/recomputer-hailo8-cv/<model>:latest \
  python web_detection.py --model_path model/<model>.hef --video_path video/test.mp4

When the service starts, open http://<BOARD_IP>:8000 in a browser. The model card documents any extra arguments, such as a second detector HEF for a multi-stage pipeline.

4. Diagnose Common Failures

Symptom	Check
`/dev/hailo0` does not exist	Check `lspci`, the PCIe driver, and restart after driver installation.
`HAILO_DRIVER_OPERATION_FAILED`	Confirm the host driver/runtime, PCIe connection, and power state.
`libhailort.so` load error	Mount the versioned host library and the unversioned symlink shown above.
Model does not start	Verify the image, HEF, HailoRT major release, and model-specific command all target Hailo-8.

5. Before Publishing a New Model

Test the image on physical Hailo-8 hardware, record the exact command in the model README and AI Lab Wiki, and configure the GHCR package URL in the model card's downloadSources.