Quick Start Guide

Get YOLO-Pi running on your hardware in just a few steps. This guide will walk you through the fastest path to real-time object detection.

Prerequisites

Before you begin, ensure you have:

Hardware

Raspberry Pi 3 or newer (or x86 computer for testing)
USB camera or Raspberry Pi Camera Module
8GB+ microSD card
Internet connection

Software

Docker installed (recommended), or
Python 3.5+ with pip
Git for cloning the repository

Installation Methods

Choose the installation method that best fits your needs:

Docker (Recommended)
Manual Installation

Docker provides the fastest setup with all dependencies pre-configured.

Clone the repository

git clone https://github.com/CiscoBlockChain/YOLO-Pi.git
cd YOLO-Pi

Build the Docker image

For x86/x64 systems (MacBook, Linux workstation):

docker build -t yolo-pi --file Dockerfile.x86 .

For Raspberry Pi:

docker build -t yolo-pi --file Dockerfile.rpi .

Building on Raspberry Pi can take 6-12 hours. Consider using pre-built images or building on x86 first.

Run the container

docker run -it --rm --device=/dev/video0:/dev/video0 \
  -e MQTT=mqtt.example.com \
  yolo-pi /bin/bash

Replace mqtt.example.com with your MQTT broker address.

Continue to Model Setup below.

Install dependencies manually for development or custom configurations.

Install system dependencies

# On Raspberry Pi or Debian/Ubuntu
sudo apt-get update
sudo apt-get install -y \
  python3 python3-pip python3-dev \
  build-essential cmake git wget \
  libopencv-dev python3-opencv

Install Python packages

pip3 install numpy keras==2.1.2 tensorflow pillow h5py paho-mqtt

Use Keras 2.1.2 for compatibility with the YOLO models. Newer versions may cause issues.

Clone the repository

git clone https://github.com/CiscoBlockChain/YOLO-Pi.git
cd YOLO-Pi/src

Model Setup

Download and convert a pre-trained YOLO model to Keras format.

Download YOLO model

Download the tiny-yolo-voc model (recommended for Raspberry Pi):

cd model_data
wget https://pjreddie.com/media/files/tiny-yolo-voc.weights
wget https://raw.githubusercontent.com/pjreddie/darknet/master/cfg/tiny-yolo-voc.cfg
cd ..

The tiny-yolo-voc model provides a good balance between speed and accuracy for edge devices.

Convert to Keras format

Use the YAD2K converter to create a Keras model:

python3 yad2k/yad2k.py \
  model_data/tiny-yolo-voc.cfg \
  model_data/tiny-yolo-voc.weights \
  model_data/tiny-yolo-voc.h5

This creates tiny-yolo-voc.h5 which contains the Keras model.

Verify model files

Ensure you have all required files:

ls model_data/

You should see:

tiny-yolo-voc.h5 - Keras model
tiny-yolo-voc_anchors.txt - Anchor boxes
pascal_classes.txt - Object class names

Configuration

Configure YOLO-Pi to use your model and MQTT broker.

Set MQTT broker

Set the MQTT environment variable:

export MQTT=mqtt.example.com

Replace with your MQTT broker hostname or IP address.

Configure model paths

Edit src/yolo-pi.py and update the model configuration:

model_path = 'model_data/tiny-yolo-voc.h5'
anchors_path = 'model_data/tiny-yolo-voc_anchors.txt'
classes_path = 'model_data/pascal_classes.txt'

These paths are correct for the tiny-yolo-voc model. Change them if using a different model.

First Detection

Run YOLO-Pi and start detecting objects!

Start the detection script

cd src
python3 yolo-pi.py

The script will:

Load the YOLO model
Connect to your MQTT broker
Start capturing from the camera
Process frames and detect objects

Monitor detections

Watch the console output for detected objects:

image: [{"item": "person", "score": "0.87"}, {"item": "cat", "score": "0.92"}]

Detections are also published to the MQTT topic yolo in JSON format.

Subscribe to MQTT (optional)

In another terminal, subscribe to see detections:

mosquitto_sub -h mqtt.example.com -t yolo

You’ll receive JSON messages with detected objects and confidence scores.

Performance Expectations

Detection speed varies by hardware:

Hardware	FPS	Notes
Raspberry Pi 3	~0.5 FPS	One frame every 2 seconds
Raspberry Pi 4	~1 FPS	Improved performance
MacBook Pro	~5-10 FPS	M1/M2 or recent Intel

For better performance on Raspberry Pi, ensure adequate cooling and consider using the GPU-accelerated TensorFlow build.

Visualization (Optional)

By default, visualization is disabled. To see the detection output:

Edit src/yolo-pi.py
Uncomment line 174:

cv2.imshow("preview", open_cv_image)

Run the script with display access

Enabling visualization adds overhead and reduces FPS, especially on Raspberry Pi.

Next Steps

Model Conversion

Learn how to convert other YOLO models

MQTT Integration

Integrate detections with your IoT platform

Raspberry Pi Setup

Optimize for Raspberry Pi hardware

Production Deployment

Deploy in production environments

Troubleshooting

Camera not detected

Ensure your camera is connected and recognized:

ls -la /dev/video*

You should see /dev/video0. If using Docker, ensure the device is passed with --device=/dev/video0:/dev/video0.

MQTT connection failed

Check the MQTT broker is accessible:

ping mqtt.example.com

Verify the MQTT environment variable is set:

echo $MQTT

Out of memory errors

On Raspberry Pi, ensure adequate swap space:

free -h

See Raspberry Pi Setup for swap configuration.

Model loading errors

Verify all model files exist:

ls -la model_data/

Ensure the paths in yolo-pi.py match your actual file locations.

Get Help

View Full Documentation

Explore comprehensive guides, API reference, and deployment options

Getting Started

Setup

Guides

Deployment

Quickstart

Quick Start Guide

Prerequisites

Hardware

Software

Installation Methods

Model Setup

Configuration

First Detection

Performance Expectations

Visualization (Optional)

Next Steps

Model Conversion

MQTT Integration

Raspberry Pi Setup

Production Deployment

Troubleshooting

Get Help

View Full Documentation

Build docs developers (and LLMs) love

Getting Started

Setup

Guides

Deployment

​Quick Start Guide

​Prerequisites

Hardware

Software

​Installation Methods

​Model Setup

​Configuration

​First Detection

​Performance Expectations

​Visualization (Optional)

​Next Steps

Model Conversion

MQTT Integration

Raspberry Pi Setup

Production Deployment

​Troubleshooting

​Get Help

View Full Documentation

Build docs developers (and LLMs) love

Quick Start Guide

Prerequisites

Installation Methods

Model Setup

Configuration

First Detection

Performance Expectations

Visualization (Optional)

Next Steps

Troubleshooting

Get Help