AI Retail Shelf Monitor with Raspberry Pi 5 and Hailo-8

Introduction

Keeping a retail shelf stocked sounds simple until products are moved, a customer blocks the camera, or several visually similar packages appear in the same frame. This project turns a Raspberry Pi 5 and a Hailo-8 accelerator into an edge-AI shelf monitor that detects products, maintains inventory by shelf region, reports pickup and low-stock events, and exposes the result through a browser dashboard.

All inference runs locally. The reference application uses two Hailo-8 HEF models: one detects products on the shelf and the other detects products being held. Region mapping and temporal filtering turn raw detections into stable inventory state. A FastAPI application publishes an annotated MJPEG stream and JSON status API on the local network.

What the system does

• Runs two custom HEF models on one physical Hailo-8 accelerator.
• Assigns detections to configurable shelf regions.
• Maps generic detections to product names according to shelf placement.
• Stabilizes counts over time to reduce one-frame flicker.
• Displays inventory totals, region status, inference FPS, and video time.
• Marks pickup and low-stock events on the processed video.
• Streams the dashboard to any browser on the same network.
• Supports both a prebuilt Docker image and a bare-metal Python setup.

System architecture

The video pipeline is:

Both models share a Hailo virtual device with round-robin scheduling. This is important: opening an independent device for each model can make the second model fail because the accelerator is already in use.

The shelf model detects a generic product class. Product identity is inferred from configurable shelf regions, which works well for planogram-based retail displays. If the camera position or shelf layout changes, update the region and product mapping JSON files under `configs/`.

Hardware preparation

1. Install the Hailo-8 M.2 module on an M.2 HAT+ or another Raspberry Pi 5

PCIe adapter.

2. Connect the adapter to the Raspberry Pi 5 PCIe FFC connector.

3. Fit active cooling and use a stable power supply.

4. Boot a 64-bit Raspberry Pi OS or compatible Debian installation.

5. Confirm that the accelerator is exposed as `/dev/hailo0`.

The provided HEF files target **Hailo-8**, not Hailo-8L. The host driver, firmware, shared library, and Python package must use compatible HailoRT versions. The reference container uses HailoRT 4.23.x and Python 3.11 on `linux/arm64`.

Quick start with Docker

Pull the prebuilt image:

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

Run the bundled demo and expose the dashboard on port 8000:

bash
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

Find the Raspberry Pi address:

bash
hostname -I

From a computer or phone on the same network, open:

text
http://<PI_IP>:8000

The browser shows the latest annotated frame, inference FPS, total inventory, and stock state for every configured region. The preview preserves the source aspect ratio, including videos with rotation metadata.

Run directly on Raspberry Pi OS

Clone the source code:

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

Install the board dependencies and create the Python environment:

bash
chmod +x scripts/*.sh
./scripts/install_rpi5.sh

Reboot if the installer requests it. Then verify the Hailo device, HailoRT binding, configuration, and model files:

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

Start the web application:

bash
python3 web_detection.py \
--config configs/runtime.json \
--video_path input/demo.mp4 \
--host 0.0.0.0 \
--port 8000

To write an annotated MP4 without the browser interface, run:

bash
./scripts/run_demo.sh

The result is saved as `outputs/restock_demo_hailo8.mp4`.

Web endpoints

The JSON endpoint makes it straightforward to connect the detector to another dashboard, a store-management service, or an alerting workflow.

Use another video or camera

For another recorded video, mount the file into the container and point `--video_path` to the mounted path. Update `configs/runtime.json` when paths or model settings change.

For a different camera position or shelf planogram, recalibrate the normalized region coordinates in `configs/shelf_regions_freshco.json` and update the type mapping files. The current region-to-product mapping assumes that a product's identity can be derived from its assigned shelf location.

The repository also contains `configs/scripted_demo_events.json`. These entries are deterministic presentation events for the bundled demo and are explicitly not model predictions. Disable or replace them when evaluating live behavior.

Troubleshooting

• /dev/hailo0` is missing

Check that the PCIe adapter is connected correctly and that the matching Hailo driver and firmware are installed. Run `lspci`, `hailortcli scan`, and./scripts/probe.sh` before starting the container.

• HailoRT version errors

The host driver, firmware, shared library, and container runtime must be compatible. The example mounts `libhailort.so.4.23.0`; adjust both volume paths if the host uses another compatible installation.

• The dashboard is not reachable

Confirm that the application logs show `0.0.0.0:8000`, use the Raspberry Pi's LAN address rather than `localhost` on another computer, and allow TCP port 8000 through any host firewall.

• Counts do not match a new shelf

Region boundaries and type mappings are specific to a camera view and planogram. Recalibrate the JSON configuration whenever the resolution, camera angle, shelf geometry, or product placement changes.

• Build the container from source

From the repository root:

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

The GitHub Actions workflow builds the `linux/arm64` image and publishes it to GHCR, keeping the source, Dockerfile, and deployable artifact together.

Conclusion

This project demonstrates a complete edge-AI workflow rather than only drawing object-detection boxes: two Hailo-accelerated models feed configurable shelf logic, stable inventory state, event overlays, and a browser-accessible API. The included video and container provide a repeatable starting point, while the region files and web endpoints make the system adaptable to another shelf or a larger retail application.