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

```bash
# 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

```bash
# 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:

```bash
# 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+:

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
./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:
```bash
# 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:
```bash
# 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:
```bash
# 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:

```bash
# 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