DriverTrac/docs/RASPBERRY_PI_INSTALL.md

Raspberry Pi Installation Guide

Overview

This guide helps you install the Driver DSMS ADAS system on Raspberry Pi with ARM architecture. The main challenge is that MediaPipe has limited ARM support, especially for Python 3.11+.

System Requirements

• Raspberry Pi: 4 or 5 (8GB RAM recommended)
• OS: Raspberry Pi OS (64-bit) or Ubuntu 22.04+ (ARM64)
• Python: 3.9, 3.10, or 3.11 (3.12+ may have compatibility issues)

Step 1: Check Your System

# Check Python version
python3 --version

# Check architecture
uname -m  # Should show aarch64 for 64-bit ARM

# Check OS
cat /etc/os-release

Step 2: Install System Dependencies

# Update system
sudo apt update && sudo apt upgrade -y

# Install build tools (required for some packages)
sudo apt install -y build-essential cmake pkg-config
sudo apt install -y libjpeg-dev libtiff5-dev libjasper-dev libpng-dev
sudo apt install -y libavcodec-dev libavformat-dev libswscale-dev libv4l-dev
sudo apt install -y libxvidcore-dev libx264-dev
sudo apt install -y libfontconfig1 libxrender1
sudo apt install -y libgstreamer-plugins-base1.0-dev libgstreamer1.0-dev

Step 3: Choose Installation Method

Option A: MediaPipe 0.10.x (Python 3.9-3.10)

If you have Python 3.9 or 3.10, you can try installing MediaPipe 0.10.x:

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Upgrade pip
pip install --upgrade pip setuptools wheel

# Install MediaPipe 0.10.x (last version with some ARM support)
pip install mediapipe==0.10.8

# Install other requirements
pip install -r requirements_rpi.txt

Option B: MediaPipe 1.0+ (If Available)

For Python 3.11+, try MediaPipe 1.0+:

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Upgrade pip
pip install --upgrade pip setuptools wheel

# Try MediaPipe 1.0+
pip install mediapipe>=1.0.0

# Install other requirements
pip install -r requirements_rpi.txt

Option C: mediapipe-rpi4 (32-bit Raspberry Pi OS)

If you're on 32-bit Raspberry Pi OS:

# Install system dependencies
sudo apt install libusb-1.0-0 libgcc1 libjpeg62-turbo libjbig0 libstdc++6 \
    libtiff5 libc6 liblzma5 libpng16-16 zlib1g libudev1 libdc1394-22 \
    libatomic1 libraw1394-11

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install mediapipe-rpi4
pip install mediapipe-rpi4

# Install other requirements (comment out mediapipe line in requirements_rpi.txt)
pip install -r requirements_rpi.txt

Option D: OpenCV Fallback (No MediaPipe)

If MediaPipe installation fails, the system will automatically use OpenCV fallback:

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Upgrade pip
pip install --upgrade pip setuptools wheel

# Install requirements (MediaPipe will be skipped)
pip install -r requirements_rpi.txt

# The code will automatically detect MediaPipe absence and use OpenCV

Step 4: Verify Installation

# Activate virtual environment
source venv/bin/activate

# Test MediaPipe import (if installed)
python3 -c "import mediapipe; print('MediaPipe OK')" || echo "MediaPipe not available, will use OpenCV fallback"

# Test OpenCV
python3 -c "import cv2; print(f'OpenCV {cv2.__version__} OK')"

# Test other dependencies
python3 -c "import streamlit; import numpy; import torch; print('All OK')"

Step 5: Run the Application

# Activate virtual environment
source venv/bin/activate

# Run the POC demo
streamlit run src/poc_demo.py --server.port 8501 --server.address 0.0.0.0

Or use the provided script:

./run_poc.sh

Troubleshooting

Issue: MediaPipe Installation Fails

Solution: The code automatically falls back to OpenCV. You'll see a warning in the logs:

MediaPipe not available, will use OpenCV fallback

The OpenCV fallback provides:

• Face detection (using OpenCV DNN)
• Simplified pose estimation
• All core features still work, with slightly reduced accuracy

Issue: Python Version Too New

Solution: Use Python 3.10 or 3.11:

# Install Python 3.10
sudo apt install python3.10 python3.10-venv python3.10-dev

# Create venv with Python 3.10
python3.10 -m venv venv
source venv/bin/activate

Issue: Out of Memory During Installation

Solution: Increase swap space:

# Check current swap
free -h

# Increase swap (add 2GB)
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile  # Change CONF_SWAPSIZE=2048
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

Issue: Torch Installation Fails

Solution: Install PyTorch for ARM:

# For Raspberry Pi, use pre-built wheels
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

Performance Optimization

For Better Performance:

1. Use ONNX Runtime: Already configured in the code
2. Reduce Frame Size: Already set to 640x480
3. Skip Frames: Already configured (process every 2nd frame)
4. Use MediaPipe if Available: More optimized than OpenCV fallback

Expected Performance:

• With MediaPipe: 15-20 FPS on Raspberry Pi 4 (8GB)
• With OpenCV Fallback: 10-15 FPS on Raspberry Pi 4 (8GB)
• CPU Usage: 50-70% on Raspberry Pi 4

Alternative: Use Docker

If installation is problematic, consider using Docker:

# Build Docker image
docker build -t dsms-adas:rpi .

# Run container
docker run -p 8501:8501 --device=/dev/video0 dsms-adas:rpi

Support

If you encounter issues:

1. Check the logs in logs/poc_demo.log
2. Verify Python version: python3 --version
3. Verify architecture: uname -m
4. Check installed packages: pip list

Notes

• MediaPipe <1.0.0: Limited ARM support, works best on Python 3.9-3.10
• MediaPipe 1.0+: Better ARM support, but may not be available for all Python versions
• OpenCV Fallback: Always works, but with reduced accuracy for face/pose detection
• Performance: MediaPipe is faster and more accurate, but OpenCV fallback is acceptable for POC