# Raspberry Pi Deployment Guide

## Testing Strategy: Ubuntu vs Raspberry Pi

### ✅ **Recommendation: Test on Ubuntu First, Then Deploy to Raspberry Pi**

**Why test on Ubuntu first:**
1. **Faster Development Cycle**: Ubuntu on x86_64 is much faster for debugging and iteration
2. **Better Tooling**: IDEs, debuggers, and development tools work better on Ubuntu
3. **Easier Dependency Management**: Most packages install smoothly on Ubuntu
4. **Identify Logic Bugs**: Fix algorithmic and code issues before dealing with hardware constraints
5. **Protect SD Card**: Avoid excessive writes during development (Raspberry Pi uses SD cards)

**Then test on Raspberry Pi:**
1. **Architecture Validation**: Ensure ARM compatibility
2. **Performance Benchmarking**: Real-world performance on target hardware
3. **Memory Constraints**: Test with actual 4-8GB RAM limits
4. **Thermal Management**: Check CPU throttling under load
5. **Final Optimizations**: Pi-specific tuning

---

## Architecture Differences

### Ubuntu (x86_64) vs Raspberry Pi (ARM)

| Aspect | Ubuntu (x86_64) | Raspberry Pi (ARM) |
|--------|----------------|-------------------|
| **CPU Architecture** | x86_64 (Intel/AMD) | ARM (Broadcom) |
| **Performance** | High (multi-core, high clock) | Lower (4-8 cores, 1.5-2.4 GHz) |
| **Memory** | Typically 8GB+ | 4-8GB (Pi 4/5) |
| **Python Packages** | Pre-built wheels available | May need compilation |
| **ONNX Runtime** | `onnxruntime` | `onnxruntime` (ARM build) |
| **PyTorch** | CUDA support available | CPU-only (or limited GPU) |
| **OpenCV** | Full features | May need compilation for some features |

---

## Raspberry Pi Requirements

### Hardware Recommendations

**Minimum (for testing):**
- Raspberry Pi 4 (4GB RAM) or better
- 32GB+ Class 10 SD card (or better: USB 3.0 SSD)
- Good power supply (5V 3A)
- Active cooling (heatsink + fan recommended)

**Recommended (for production):**
- Raspberry Pi 5 (8GB RAM) - **Best choice**
- 64GB+ high-speed SD card or USB 3.0 SSD
- Official Raspberry Pi power supply
- Active cooling system
- Camera module v2 or v3

### Software Requirements

**OS:**
- Raspberry Pi OS (64-bit) - **Recommended** (better for Python packages)
- Ubuntu Server 22.04 LTS (ARM64) - Alternative

**Python:**
- Python 3.9+ (3.10 or 3.11 recommended)

---

## Installation Steps for Raspberry Pi

### 1. Prepare Raspberry Pi OS

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

# Install essential build tools
sudo apt install -y python3-pip python3-venv build-essential cmake
sudo apt install -y libopencv-dev python3-opencv  # OpenCV system package (optional)
```

### 2. Create Virtual Environment

```bash
cd ~/work/tools/Driver_DSMS_ADAS
python3 -m venv venv
source venv/bin/activate
```

### 3. Install Dependencies (Pi-Specific Considerations)

**Important**: Some packages may need ARM-specific builds or compilation.

```bash
# Upgrade pip first
pip install --upgrade pip setuptools wheel

# Install NumPy (may take time - compiles from source if no wheel)
pip install numpy

# Install PyTorch (CPU-only for ARM)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

# Install other dependencies
pip install -r requirements.txt
```

**Note**: Installation may take 30-60 minutes on Raspberry Pi due to compilation.

### 4. Install ONNX Runtime (ARM)

```bash
# For ARM64 (Raspberry Pi 4/5 64-bit)
pip install onnxruntime

# If above fails, try:
# pip install onnxruntime-arm64  # May not exist, check availability
```

### 5. Test Installation

```bash
python3 check_dependencies.py
```

---

## Performance Optimizations for Raspberry Pi

### 1. Model Optimization

**Already Implemented:**
- ✅ ONNX format (faster than PyTorch)
- ✅ Frame skipping (`inference_skip: 3`)
- ✅ VideoMAE disabled (too heavy)

**Additional Optimizations:**

```python
# In CONFIG, reduce further for Pi:
CONFIG = {
    'yolo_base': 'yolov8n.pt',  # Already nano (smallest)
    'conf_threshold': 0.7,
    'inference_skip': 5,  # Increase from 3 to 5 for Pi
    'frame_resize': (320, 240),  # Smaller resolution for face analysis
    'object_resize': (416, 416),  # Smaller for YOLO
}
```

### 2. System Optimizations

```bash
# Increase GPU memory split (if using GPU acceleration)
sudo raspi-config
# Advanced Options > Memory Split > 128 (or 256)

# Disable unnecessary services
sudo systemctl disable bluetooth
sudo systemctl disable avahi-daemon

# Set CPU governor to performance (temporary)
echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
```

### 3. Memory Management

```python
# Add to track_drive.py for Pi:
import gc

# In run_inference, after processing:
if frame_idx % 10 == 0:
    gc.collect()  # Force garbage collection
```

### 4. Use USB 3.0 SSD Instead of SD Card

SD cards are slow and can wear out. For production:
- Use USB 3.0 SSD for OS and application
- Much faster I/O
- Better reliability

---

## Expected Performance on Raspberry Pi

### Raspberry Pi 4 (4GB)

**Current (After Fixes):**
- FPS: 3-5
- Memory: 2-3GB
- CPU: 80-100% (may throttle)
- Temperature: 60-75°C (with cooling)

**After Optimizations:**
- FPS: 5-8
- Memory: 1.5-2.5GB
- CPU: 70-85%
- Temperature: 55-70°C

### Raspberry Pi 5 (8GB) - **Recommended**

**Current (After Fixes):**
- FPS: 5-8
- Memory: 2-3GB
- CPU: 60-80%
- Temperature: 50-65°C

**After Optimizations:**
- FPS: 8-12
- Memory: 1.5-2.5GB
- CPU: 50-70%
- Temperature: 45-60°C

---

## Common Issues and Solutions

### Issue 1: Out of Memory

**Symptoms**: Process killed, "Killed" message

**Solutions:**
```bash
# Increase swap (temporary)
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile  # Change CONF_SWAPSIZE=100 to 2048
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

# Or reduce model sizes, increase frame skipping
```

### Issue 2: Slow Model Loading

**Solution**: Pre-download models on Ubuntu, copy to Pi
```bash
# On Ubuntu, models download to ~/.cache/
# Copy to Pi:
scp -r ~/.cache/huggingface user@pi:~/.cache/
scp -r ~/.cache/ultralytics user@pi:~/.cache/
```

### Issue 3: ONNX Runtime Not Found

**Solution**: Install ARM-compatible version
```bash
# Check architecture
uname -m  # Should show aarch64 for Pi 4/5 64-bit

# Install correct version
pip uninstall onnxruntime
pip install onnxruntime  # Should auto-detect ARM
```

### Issue 4: Camera Not Detected

**Solution**: 
```bash
# Check camera
vcgencmd get_camera  # Should show supported=1 detected=1

# For USB webcam:
lsusb  # Check if detected
v4l2-ctl --list-devices  # List video devices
```

### Issue 5: High CPU Temperature

**Solution**:
```bash
# Monitor temperature
watch -n 1 vcgencmd measure_temp

# If >80°C, add cooling or reduce load
# Throttling starts at 80°C
```

---

## Deployment Checklist

### Before Deploying to Pi:

- [ ] Code runs successfully on Ubuntu
- [ ] All critical bugs fixed
- [ ] Dependencies documented
- [ ] Models pre-downloaded (optional, saves time)
- [ ] Configuration tested

### On Raspberry Pi:

- [ ] OS updated and optimized
- [ ] Python 3.9+ installed
- [ ] Virtual environment created
- [ ] All dependencies installed
- [ ] Models load successfully
- [ ] Camera/webcam detected
- [ ] Performance benchmarks run
- [ ] Temperature monitoring active
- [ ] Auto-start script configured (if needed)

### Production Readiness:

- [ ] Performance meets targets (FPS > 5)
- [ ] Memory usage acceptable (<3GB)
- [ ] CPU temperature stable (<75°C)
- [ ] No crashes during extended testing
- [ ] Error handling robust
- [ ] Logging configured
- [ ] Auto-restart on failure (systemd service)

---

## Testing Workflow

### Phase 1: Ubuntu Development (Current)
1. ✅ Fix critical bugs
2. ✅ Test functionality
3. ✅ Optimize code
4. ✅ Verify accuracy

### Phase 2: Raspberry Pi Validation
1. Deploy to Pi
2. Test compatibility
3. Benchmark performance
4. Optimize for Pi constraints

### Phase 3: Production Tuning
1. Fine-tune parameters
2. Add Pi-specific optimizations
3. Stress testing
4. Long-term stability testing

---

## Quick Start for Pi

```bash
# 1. Clone/copy project to Pi
cd ~/work/tools/Driver_DSMS_ADAS

# 2. Create venv and install
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 3. Test
python3 check_dependencies.py
streamlit run track_drive.py
```

---

## Conclusion

**Testing on Ubuntu first is the right approach.** It allows you to:
- Fix bugs quickly
- Iterate faster
- Identify issues before hardware constraints complicate debugging

**Then deploy to Raspberry Pi** for:
- Real-world performance validation
- Architecture compatibility
- Final optimizations

This two-phase approach saves significant development time while ensuring the application works correctly on the target hardware.