# 🔧 Troubleshooting Guide

## Common Issues and Solutions

### 1. Camera Not Detected

**Symptoms:**
```
[ WARN:0@1.554] global cap_v4l.cpp:914 open VIDEOIO(V4L2:/dev/video0): can't open camera by index
```

**Solutions:**

#### Check Available Cameras
```bash
# List USB cameras
lsusb

# List video devices
ls -la /dev/video*

# Test camera with OpenCV
python3 -c "import cv2; cap = cv2.VideoCapture(0); print('Camera OK' if cap.isOpened() else 'Camera FAILED'); cap.release()"
```

#### Try Different Camera Indices
The POC now automatically tries cameras 0, 1, and 2. If your camera is on a different index:

1. Edit `src/poc_demo.py`
2. Find `for camera_idx in [0, 1, 2]:`
3. Add your camera index: `for camera_idx in [0, 1, 2, 3, 4]:`

#### USB Camera Issues
```bash
# Check USB permissions
ls -l /dev/video*

# If permission denied, add user to video group
sudo usermod -a -G video $USER
# Then logout and login again
```

#### Raspberry Pi Camera
For Raspberry Pi Camera Module:
```python
# In src/poc_demo.py, replace:
cap = cv2.VideoCapture(0)

# With:
cap = cv2.VideoCapture('nvarguscamerasrc ! video/x-raw(memory:NVMM), width=640, height=480, framerate=30/1 ! nvvidconv ! video/x-raw, format=BGRx ! videoconvert ! video/x-raw, format=BGR ! appsink', cv2.CAP_GSTREAMER)
```

### 2. Streamlit Deprecation Warnings

**Fixed!** The `use_container_width` warning has been resolved. The code now uses `width='stretch'` instead.

### 3. Low FPS / Performance Issues

**Solutions:**

1. **Increase inference skip:**
   - Edit `config/poc_config.yaml`
   - Change `inference_skip: 2` to `inference_skip: 3` or `4`

2. **Reduce frame size:**
   - Edit `config/poc_config.yaml`
   - Change `frame_size: [640, 480]` to `frame_size: [320, 240]`

3. **Close other applications:**
   - Free up CPU and memory

### 4. "Driver Absent" Always Active

**Cause:** Camera not working or face not detected

**Solutions:**
1. Fix camera issue (see #1)
2. Ensure good lighting
3. Position face clearly in frame
4. Check camera focus

### 5. Alerts Not Triggering

**Check:**
1. **Thresholds too high:**
   - Edit `config/poc_config.yaml`
   - Lower `perclos_threshold` (try 0.2)
   - Lower `head_pose_threshold` (try 20)

2. **Face not detected:**
   - Improve lighting
   - Face should be clearly visible
   - Remove obstructions

### 6. Memory Issues

**Symptoms:** App crashes, "Killed" messages

**Solutions:**
1. Reduce queue size in code
2. Increase inference skip
3. Use smaller frame size
4. Close other applications

### 7. Models Not Loading

**Solutions:**
```bash
# Check if models exist
ls -lh models/

# If missing, they'll auto-download on first run
# Or manually download:
cd models/
wget https://github.com/ultralytics/assets/releases/download/v8.3.0/yolov8n.pt
```

### 8. Import Errors

**Solution:**
```bash
# Reinstall dependencies
source venv/bin/activate
pip install --upgrade -r requirements.txt
```

### 9. Port Already in Use

**Symptoms:** `Address already in use`

**Solutions:**
```bash
# Kill existing Streamlit process
pkill -f streamlit

# Or use different port
streamlit run src/poc_demo.py --server.port 8502
```

### 10. Raspberry Pi Specific Issues

#### Camera Module Not Working
```bash
# Enable camera
sudo raspi-config
# Interface Options > Camera > Enable

# Test camera
raspistill -o test.jpg
```

#### Low Performance
1. Use USB 3.0 SSD instead of SD card
2. Increase swap space
3. Use active cooling
4. Reduce frame size and inference skip

#### Memory Issues
```bash
# Increase swap
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile  # Change CONF_SWAPSIZE=100 to 2048
sudo dphys-swapfile setup
sudo dphys-swapfile swapon
```

## Quick Diagnostic Commands

```bash
# Check camera
python3 -c "import cv2; print('Camera 0:', cv2.VideoCapture(0).isOpened()); print('Camera 1:', cv2.VideoCapture(1).isOpened())"

# Check dependencies
python3 src/check_dependencies.py

# Check system resources
free -h
df -h
top

# Check logs
tail -f logs/poc_demo.log
```

## Getting Help

1. Check logs: `logs/poc_demo.log`
2. Review configuration: `config/poc_config.yaml`
3. Test camera separately
4. Check system resources

---

**Most Common Fix:** Camera permissions and camera index. Try different indices (0, 1, 2) or check USB connections.