DriverTrac/docs/TROUBLESHOOTING.md

🔧 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

# 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

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

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

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

# Reinstall dependencies
source venv/bin/activate
pip install --upgrade -r requirements.txt

9. Port Already in Use

Symptoms: Address already in use

Solutions:

# 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

# 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

# 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

# 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.