NYSM-NYD/docs/troubleshooting.md

# Troubleshooting Guide

This guide helps you diagnose and resolve common issues with NowYouSeeMe. If you can't find a solution here, please check our [GitHub Issues](https://github.com/your-org/NowYouSeeMe/issues) or ask the [community](https://discord.gg/nowyouseeme).

## 🚨 Quick Diagnosis

### System Health Check
```bash
# Run the system health check
python -m src.diagnostics.system_check

# Expected output:
# ✅ Camera: Connected
# ✅ WiFi CSI: Available
# ✅ GPU: CUDA available
# ✅ Memory: Sufficient
# ✅ Storage: Sufficient
```

### Performance Check
```bash
# Check real-time performance
python -m src.diagnostics.performance_monitor

# Expected metrics:
# - Latency: <20ms
# - Accuracy: <10cm
# - Frame Rate: 30-60 FPS
# - CSI Rate: ≥100 pkt/s
```

## 🔧 Common Issues

### Camera Problems

#### Camera Not Detected
**Symptoms**: Camera not found, black screen, or "No camera available" error

**Diagnosis**:
```bash
# Check camera devices
ls /dev/video*

# Test camera with OpenCV
python -c "import cv2; cap = cv2.VideoCapture(0); print('Camera working:', cap.isOpened())"
```

**Solutions**:
1. **Check permissions**:
   ```bash
   sudo usermod -a -G video $USER
   # Log out and back in
   ```

2. **Verify camera connection**:
   ```bash
   # Check USB devices
   lsusb | grep -i camera
   
   # Check kernel modules
   lsmod | grep uvcvideo
   ```

3. **Install missing drivers**:
   ```bash
   # Ubuntu/Debian
   sudo apt-get install v4l-utils
   
   # Test camera
   v4l2-ctl --list-devices
   ```

4. **Update camera configuration**:
   ```json
   // config/camera_config.json
   {
     "camera": {
       "device_id": 0,  // Try different device IDs
       "width": 1280,
       "height": 720,
       "fps": 30
     }
   }
   ```

#### Poor Camera Quality
**Symptoms**: Blurry images, low resolution, poor tracking

**Solutions**:
1. **Adjust camera settings**:
   ```bash
   # Set camera parameters
   v4l2-ctl --set-ctrl=exposure_auto=1
   v4l2-ctl --set-ctrl=exposure_time_absolute=1000
   v4l2-ctl --set-ctrl=focus_auto=0
   ```

2. **Improve lighting**:
   - Ensure adequate lighting
   - Avoid direct sunlight
   - Use diffuse lighting

3. **Update calibration**:
   ```bash
   # Recalibrate camera
   python -m src.calibration.calibrate_camera --force
   ```

### WiFi CSI Issues

#### CSI Not Capturing
**Symptoms**: No RF data, "CSI unavailable" error

**Diagnosis**:
```bash
# Check WiFi interface
iwconfig

# Check Nexmon installation
lsmod | grep nexmon

# Test CSI capture
sudo ./tools/test_csi.sh
```

**Solutions**:
1. **Install Nexmon** (if not installed):
   ```bash
   # Follow Nexmon installation guide
   # https://github.com/seemoo-lab/nexmon
   
   # Build for your kernel version
   cd nexmon
   source setup_env.sh
   make
   ```

2. **Configure WiFi interface**:
   ```bash
   # Set interface to monitor mode
   sudo ifconfig wlan0 down
   sudo iw dev wlan0 set type monitor
   sudo ifconfig wlan0 up
   
   # Set channel
   sudo iw dev wlan0 set channel 6
   ```

3. **Update CSI configuration**:
   ```json
   // config/csi_config.json
   {
     "csi": {
       "interface": "wlan0",  // Use correct interface
       "channel": 6,
       "bandwidth": 20,
       "packet_rate": 100
     }
   }
   ```

#### Low CSI Packet Rate
**Symptoms**: CSI rate <100 pkt/s, poor RF tracking

**Solutions**:
1. **Optimize WiFi settings**:
   ```bash
   # Increase packet rate
   sudo iw dev wlan0 set txpower fixed 2000
   
   # Check for interference
   sudo iwlist wlan0 scan | grep -i channel
   ```

2. **Change WiFi channel**:
   ```bash
   # Try different channels
   sudo iw dev wlan0 set channel 1
   # or
   sudo iw dev wlan0 set channel 11
   ```

### Performance Issues

#### High Latency (>20ms)
**Symptoms**: Laggy interface, delayed tracking

**Diagnosis**:
```bash
# Check system resources
htop
nvidia-smi  # If using GPU
```

**Solutions**:
1. **Reduce processing load**:
   ```json
   // config/slam_config.json
   {
     "slam": {
       "max_features": 1000,  // Reduce from default
       "min_features": 100,
       "update_rate": 20  // Reduce from 30
     }
   }
   ```

2. **Optimize GPU usage**:
   ```bash
   # Check GPU memory
   nvidia-smi
   
   # Reduce GPU memory usage
   export CUDA_VISIBLE_DEVICES=0
   ```

3. **Close unnecessary applications**:
   ```bash
   # Free up system resources
   killall chrome firefox  # Close browsers
   ```

#### Low Accuracy (>10cm)
**Symptoms**: Poor tracking accuracy, drift

**Solutions**:
1. **Recalibrate sensors**:
   ```bash
   # Full recalibration
   python -m src.calibration.calibrate_camera --full
   python -m src.calibration.calibrate_rf --full
   ```

2. **Improve environment**:
   - Add more visual features
   - Improve lighting
   - Reduce WiFi interference

3. **Adjust fusion parameters**:
   ```json
   // config/fusion_config.json
   {
     "fusion": {
       "vision_weight": 0.7,  // Increase vision weight
       "rf_weight": 0.3,
       "ekf_process_noise": 0.1
     }
   }
   ```

### Application Crashes

#### Segmentation Fault
**Symptoms**: Application crashes with "Segmentation fault"

**Diagnosis**:
```bash
# Check system logs
dmesg | tail -20

# Run with debugger
gdb python
(gdb) run -m src.ui.holodeck_ui
```

**Solutions**:
1. **Check memory usage**:
   ```bash
   # Monitor memory
   free -h
   
   # Check for memory leaks
   valgrind python -m src.ui.holodeck_ui
   ```

2. **Update dependencies**:
   ```bash
   # Update all dependencies
   pip install -U -r requirements.txt
   
   # Rebuild C++ components
   ./tools/build.sh --clean
   ```

3. **Check GPU drivers**:
   ```bash
   # Update NVIDIA drivers
   sudo apt-get update
   sudo apt-get install nvidia-driver-470
   ```

#### Python Exceptions
**Symptoms**: Python errors, traceback output

**Common Solutions**:
1. **Import errors**:
   ```bash
   # Install missing dependencies
   pip install -r requirements.txt
   
   # Check Python path
   python -c "import sys; print(sys.path)"
   ```

2. **OpenCV errors**:
   ```bash
   # Reinstall OpenCV
   pip uninstall opencv-python
   pip install opencv-python-headless
   ```

3. **PyQt6 errors**:
   ```bash
   # Reinstall PyQt6
   pip uninstall PyQt6
   pip install PyQt6
   ```

### Build Issues

#### CMake Errors
**Symptoms**: Build fails with CMake errors

**Solutions**:
1. **Install missing dependencies**:
   ```bash
   # Ubuntu/Debian
   sudo apt-get install build-essential cmake libopencv-dev libeigen3-dev
   
   # macOS
   brew install cmake opencv eigen
   ```

2. **Clear build cache**:
   ```bash
   # Clean build directory
   rm -rf build/
   mkdir build
   cd build
   cmake ..
   make -j$(nproc)
   ```

3. **Check CMake version**:
   ```bash
   # Update CMake
   cmake --version
   # Should be >= 3.16
   ```

#### Python Build Errors
**Symptoms**: pip install fails

**Solutions**:
1. **Update pip and setuptools**:
   ```bash
   pip install --upgrade pip setuptools wheel
   ```

2. **Install build dependencies**:
   ```bash
   # Ubuntu/Debian
   sudo apt-get install python3-dev
   
   # macOS
   xcode-select --install
   ```

3. **Use virtual environment**:
   ```bash
   python -m venv venv
   source venv/bin/activate
   pip install -e .
   ```

## 🔍 Advanced Debugging

### Debug Mode
```bash
# Run with debug logging
python -m src.ui.holodeck_ui --debug

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

### Performance Profiling
```bash
# Profile CPU usage
python -m cProfile -o profile.stats src/ui/holodeck_ui.py

# Analyze profile
python -c "import pstats; p = pstats.Stats('profile.stats'); p.sort_stats('cumulative').print_stats(20)"
```

### Memory Profiling
```bash
# Install memory profiler
pip install memory-profiler

# Profile memory usage
python -m memory_profiler src/ui/holodeck_ui.py
```

### Network Debugging
```bash
# Check network connectivity
ping 8.8.8.8

# Check WiFi interface
iwconfig wlan0

# Monitor network traffic
sudo tcpdump -i wlan0 -w capture.pcap
```

## 📊 System Requirements Check

### Hardware Requirements
```bash
# Check CPU
lscpu | grep "Model name"

# Check RAM
free -h

# Check GPU
nvidia-smi  # or lspci | grep -i vga

# Check storage
df -h
```

### Software Requirements
```bash
# Check Python version
python --version  # Should be >= 3.8

# Check CUDA version
nvcc --version  # If using GPU

# Check OpenCV
python -c "import cv2; print(cv2.__version__)"

# Check PyQt6
python -c "import PyQt6; print(PyQt6.__version__)"
```

## 🚨 Emergency Recovery

### Reset Configuration
```bash
# Backup current config
cp -r config/ config_backup/

# Reset to defaults
cp config/defaults/* config/

# Restart application
python -m src.ui.holodeck_ui
```

### Clean Installation
```bash
# Remove all data
rm -rf data/ logs/ build/

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

# Rebuild
./tools/build.sh --clean
```

### System Reset
```bash
# Reset calibration data
rm -rf data/calibration/

# Reset logs
rm -rf logs/

# Reset configuration
cp config/defaults/* config/
```

## 📞 Getting Help

### Before Asking for Help
1. **Check this guide** for your specific issue
2. **Search existing issues** on GitHub
3. **Run diagnostics** and include output
4. **Provide system information**:
   ```bash
   # System info
   uname -a
   python --version
   nvidia-smi  # if applicable
   ```

### Where to Get Help
- **📖 Documentation**: [docs/](docs/) - Comprehensive guides
- **🐛 GitHub Issues**: [Issues](https://github.com/your-org/NowYouSeeMe/issues) - Bug reports
- **💬 Discord**: [Discord Server](https://discord.gg/nowyouseeme) - Real-time help
- **📧 Email**: support@nowyouseeme.dev - Direct support
- **💡 Discussions**: [GitHub Discussions](https://github.com/your-org/NowYouSeeMe/discussions) - General questions

### What to Include
When asking for help, please include:
- **Error messages** (full traceback)
- **System information** (OS, Python version, hardware)
- **Steps to reproduce** the issue
- **What you've tried** already
- **Expected vs actual behavior**

---

**Still having issues?** Check our [FAQ](faq.md) or ask the [community](https://discord.gg/nowyouseeme)!