Retail Shelf Detection with Raspberry Pi 5 and Hailo-8

Retail Shelf Detection with Raspberry Pi 5 and Hailo-8

This project uses a Raspberry Pi 5 and Hailo-8 accelerator to detect products on retail shelves, track shelf inventory, and render pickup and low-stock events on video. Two Hailo-8 HEF models detect shelf products and products being held, while a FastAPI/MJPEG dashboard provides browser access over the local network.

Source code: https://github.com/Seeed-Projects/reComputer-AI-Lab-Project/tree/main/pi_project/retail_shelf_detection

Features

• Hailo-8 accelerated inference on Raspberry Pi 5
• Shelf-product and held-product detection with two HEF models
• Configurable shelf regions and product type mapping
• Inventory count, pickup event, and low-stock overlays
• Browser-based MJPEG preview and inventory status on port 8000
• Included demo video, model files, and device validation tools
• Bare-metal and Docker deployment options

Hardware and Software

The host driver, firmware, shared library, and Python package must use compatible HailoRT versions. The included models target Hailo-8 rather than Hailo-8L.

Quick Start with Docker

Pull the prebuilt linux/arm64 image from GHCR:

sudo docker pull \
  ghcr.io/seeed-projects/recomputer-ai-lab-project/retail_shelf_detection:latest

Run the bundled video and web dashboard:

sudo docker run --rm \
  --name rpi5-hailo8-retail-shelf-detection \
  --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-ai-lab-project/retail_shelf_detection:latest \
  python web_detection.py \
    --config configs/runtime.json \
    --video_path input/demo.mp4 \
    --host 0.0.0.0 \
    --port 8000

Open the following address from a browser on the same network:

http://<PI_IP>:8000

The dashboard shows the annotated video, inference FPS, total inventory, and the stock status of each shelf region.

Get the Project

git clone https://github.com/Seeed-Projects/reComputer-AI-Lab-Project.git
cd reComputer-AI-Lab-Project

Run on Raspberry Pi OS

Install the board dependencies and create a Python virtual environment:

cd pi_project/retail_shelf_detection
chmod +x scripts/*.sh
./scripts/install_rpi5.sh

After installing the Hailo packages, reboot if the installer requests it. Then verify the accelerator, runtime, configuration, and HEF models:

./scripts/probe.sh
python3 tools/check_deployment.py

Start the browser dashboard with the bundled video:

python3 web_detection.py \
  --config configs/runtime.json \
  --video_path input/demo.mp4

To generate a processed MP4 without the Web dashboard, run:

./scripts/run_demo.sh

The processed result is saved to outputs/restock_demo_hailo8.mp4.

Build the Container from Source

The repository includes the Dockerfile and matching HailoRT 4.23.0 Python 3.11 aarch64 wheel. Build the image from the repository root:

sudo docker build \
  -f docker/hailo8/retail_shelf_detection.dockerfile \
  -t retail_shelf_detection:latest \
  pi_project/retail_shelf_detection

If HailoRT is installed to a different host path, adjust the two shared-library mounts while keeping the host and container versions compatible.

Web API

• GET /: browser dashboard
• GET /api/video_feed: MJPEG annotated video stream
• GET /api/status: inference, inventory, region, and event state
• GET /healthz: service and inference health

Validate the Configuration Only

Use --check-config to check paths and configuration structure without loading HailoRT:

cd pi_project/retail_shelf_detection
python3 app/infer_video_hailo.py --check-config

Use Another Video or Shelf Layout

Update configs/runtime.json to select another input and output path. If the camera position, video resolution, shelf geometry, or product placement changes, also update the shelf region and product mapping files under configs/.

Project Structure

pi_project/retail_shelf_detection/
├── app/                 # Video inference entry point
├── configs/             # Model, region, product, and event configuration
├── input/               # Bundled demo video
├── models/hef/          # Hailo-8 HEF models
├── runtime/             # HailoRT integration and YOLO post-processing
├── shelf_monitor/       # Inventory, event, region, and drawing logic
├── scripts/             # Installation, probing, and demo scripts
├── tools/               # Deployment checks
└── web_detection.py     # FastAPI dashboard and MJPEG stream