Real-Time Object Detection with Raspberry Pi 5: Hailo-8L AI Kit Build & Debug Guide

For real-time object detection with Raspberry Pi in 2026, the definitive hardware stack is the Raspberry Pi 5 (8GB variant) paired with the Hailo-8L M.2 AI Kit and the Camera Module 3. This combination pushes inference speeds past 30 FPS on YOLOv8n models, bypassing the CPU bottlenecks that plagued earlier Pi generations. Below is the exact bench-tested procedure to assemble, wire, and code this stack, along with the specific HailoRT error strings you will inevitably encounter and how to fix them.

Hardware Spec Sheet & Parts List

Do not attempt this build with a 4GB Pi 5 if you plan to run 1080p video streams alongside inference; the memory overhead for libcamera buffers and Hailo tensor allocation will trigger OOM (Out of Memory) kills. Secure the 8GB variant.

Physical Assembly & Pin Mapping

The Raspberry Pi 5 routes its PCIe Gen 2 x1 interface to the 40-pin header area via a dedicated FFC (Flexible Flat Cable) connector. The M.2 HAT+ bridges this to the Hailo module. The Camera Module 3 uses the 22-pin MIPI CSI-2 connector.

Software Setup & Compilable Python Code

This code targets the Raspberry Pi 5 (8GB) running Raspberry Pi OS (64-bit, Bookworm). You must install the Hailo runtime and Picamera2 dependencies first:

sudo apt update
sudo apt install -y hailo-all python3-picamera2 python3-opencv

The following Python script initializes the Pi Camera 3, loads a YOLOv8n HEF (Hailo Executable Format) compiled specifically for the Hailo-8L architecture, and runs a continuous inference loop with bounding box rendering.

import sys
import cv2
import numpy as np
from picamera2 import Picamera2
from hailo_platform import HEF, VDevice, ConfigureParams, InputVStreamParams, OutputVStreamParams, InferVStreams

# --- DEVICE & PIN DEFINITIONS ---
CAMERA_ID = 0
HEF_PATH = "yolov8n_h8l_pi.hef"  # Must be compiled for Hailo-8L
CONFIDENCE_THRESHOLD = 0.5

def setup_camera():
    """Initialize Pi Camera 3 via libcamera/picamera2"""
    picam2 = Picamera2(CAMERA_ID)
    config = picam2.create_preview_configuration(main={"size": (640, 480), "format": "RGB888"})
    picam2.configure(config)
    picam2.start()
    return picam2

def run_inference():
    try:
        picam2 = setup_camera()
        hef = HEF(HEF_PATH)
        target = VDevice()
        
        network_group = target.configure(hef)[0]
        input_vstream_params = InputVStreamParams.make(network_group)
        output_vstream_params = OutputVStreamParams.make(network_group)
        
        input_shape = hef.get_input_vstream_infos()[0].shape
        output_name = hef.get_output_vstream_infos()[0].name
        
        print(f"[INFO] Inference started on {HEF_PATH}")
        
        with InferVStreams(network_group, input_vstream_params, output_vstream_params) as pipeline:
            while True:
                frame = picam2.capture_array()
                frame_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
                
                # Pre-process: Resize and normalize to match HEF input expectations
                resized = cv2.resize(frame_rgb, (input_shape[1], input_shape[0]))
                input_data = np.expand_dims(resized.astype(np.float32) / 255.0, axis=0)
                
                # Push to Hailo NPU
                raw_results = pipeline.infer({
                    hef.get_input_vstream_infos()[0].name: input_data
                })
                
                # Post-process (Simplified YOLO extraction)
                output_tensor = raw_results[output_name][0]
                # Note: Real-world YOLO post-processing requires NMS (Non-Maximum Suppression)
                # This block demonstrates tensor retrieval and basic thresholding
                detections = output_tensor[output_tensor[:, 4] > CONFIDENCE_THRESHOLD]
                
                for det in detections:
                    x1, y1, x2, y2, conf = det[:5]
                    cv2.rectangle(frame_rgb, (int(x1*640), int(y1*480)), 
                                  (int(x2*640), int(y2*480)), (0, 255, 0), 2)
                    cv2.putText(frame_rgb, f"{conf:.2f}", (int(x1*640), int(y1*480)-10),
                                cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 2)
                
                cv2.imshow("Hailo-8L Object Detection", frame_rgb)
                if cv2.waitKey(1) & 0xFF == ord('q'):
                    break
                    
    except Exception as e:
        print(f"[FATAL ERROR] {type(e).__name__}: {e}")
        sys.exit(1)
    finally:
        if 'picam2' in locals():
            picam2.stop()
        cv2.destroyAllWindows()

if __name__ == "__main__":
    run_inference()

Debugging: First Three Things to Check When It Fails

When building embedded vision pipelines, the hardware-software boundary is where 90% of failures occur. If your script crashes, check these three exact error strings and their ranked causes.

1. HailoRTException: Failed to open device (status: HAILO_PCIE_DEVICE_NOT_FOUND)

This means the Raspberry Pi 5 OS cannot see the Hailo-8L module on the PCIe bus. The first three things to check:

1. Insufficient Power Delivery: The Pi 5 limits PCIe current if it doesn't detect a 27W USB-C PD power supply. Check dmesg | grep -i power. If you are using a 15W charger, the Pi disables the PCIe bus to save power. Swap to the official 27W supply.
2. FFC Cable Seating: The PCIe ribbon cable must be fully inserted into both the Pi 5 J2 connector and the M.2 HAT. If it is skewed by 1mm, the TX/RX lanes will fail to negotiate.
3. PCIe Probe Delay: Add dtparam=pciex1_gen=2 to your /boot/firmware/config.txt and reboot. Sometimes the Gen 2 link training fails on cold boot without this explicit parameter.

2. RuntimeError: Failed to open camera /dev/video0

This is a libcamera or ribbon cable issue, not a Hailo issue.

1. Ribbon Orientation: The Camera Module 3 ribbon cable has exposed silver contacts on one side. On the Pi 5 CAM1 port, these contacts must face inward toward the SoC, not outward toward the board edge.
2. Libcamera Service Hang: If a previous script crashed without calling picam2.stop(), the camera daemon locks the device. Run sudo systemctl restart libcameraservice or simply reboot.
3. Port Selection: The Pi 5 has two camera ports (CAM0 and CAM1). Ensure your physical connection matches the CAMERA_ID in the code (CAM1 is typically ID 0 in picamera2 if CAM0 is empty).

3. HailoRTException: HEF file architecture mismatch

You are trying to load a model compiled for the wrong silicon.

1. Hailo-8 vs Hailo-8L: The Raspberry Pi AI Kit uses the Hailo-8L (13 TOPS). If you downloaded a pre-compiled HEF from a generic Hailo developer portal meant for the full Hailo-8 (26 TOPS), the runtime will reject it. You must recompile the ONNX model using the Hailo Dataflow Compiler (DFC) targeting the hailo8l architecture.

Extending and Simplifying the Build

How to Simplify: If you do not need 30+ FPS and want to avoid the M.2 HAT assembly, drop the Pi 5 and Hailo kit. Use a Raspberry Pi 4 (4GB) with a Google Coral USB Accelerator ($35). You will swap the HailoRT Python API for the pycoral library and use TFLite models instead of HEF files. Expect ~12 FPS on MobileNet SSD.

How to Extend: To turn this into a smart-home security node, integrate the paho-mqtt Python library. Inside the inference while loop, when len(detections) > 0, publish a JSON payload to your MQTT broker containing the bounding box coordinates and class ID. Home Assistant can then trigger automations (e.g., turning on porch lights when a "person" class is detected in the lower third of the frame).

Frequently Asked Questions

Can I run object detection with Raspberry Pi 4 instead of Pi 5?

Yes, but not with the Hailo-8L M.2 AI Kit. The Pi 4 lacks the PCIe interface required for the M.2 HAT. For the Pi 4, you must use a USB-based NPU like the Google Coral USB Accelerator or the Hailo-8R (which uses a different interface, rarely adapted for Pi 4). Expect significantly lower framerates and higher CPU utilization on the Pi 4 compared to the Pi 5's native PCIe integration.

Why is my object detection with Raspberry Pi dropping frames at 1080p?

Dropped frames at 1080p usually indicate a memory bandwidth bottleneck, not an NPU bottleneck. The Hailo-8L can process the tensors fast enough, but moving 1080p RGB frames from the libcamera buffer through the CPU's memory space to the PCIe bus saturates the Pi 5's memory controller. Drop the picamera2 preview resolution to 640x480 or 720p for inference, and only trigger full-resolution JPEG captures when an object of interest is detected.

How do I train a custom model for object detection with Raspberry Pi?

You do not train the model on the Raspberry Pi itself. Train a YOLOv8 or YOLOv10 model on a desktop GPU using the Ultralytics framework. Once you have an ONNX export, use the Hailo Dataflow Compiler (DFC) on an x86 Ubuntu machine (or WSL2) to quantize and compile the ONNX file into a .hef file specifically targeting the hailo8l architecture. Transfer the resulting HEF file to your Pi 5 via SCP.