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 or ask the community.

🚨 Quick Diagnosis

System Health Check

# 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

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

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

   sudo usermod -a -G video $USER
   # Log out and back in
   

2. Verify camera connection:

   # Check USB devices
   lsusb | grep -i camera
   
   # Check kernel modules
   lsmod | grep uvcvideo
   

3. Install missing drivers:

   # Ubuntu/Debian
   sudo apt-get install v4l-utils
   
   # Test camera
   v4l2-ctl --list-devices
   

4. Update camera configuration:

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

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

   # Recalibrate camera
   python -m src.calibration.calibrate_camera --force
   

WiFi CSI Issues

CSI Not Capturing

Symptoms: No RF data, "CSI unavailable" error

Diagnosis:

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

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

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

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

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

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

# Check system resources
htop
nvidia-smi  # If using GPU

Solutions:

1. Reduce processing load:

   // config/slam_config.json
   {
     "slam": {
       "max_features": 1000,  // Reduce from default
       "min_features": 100,
       "update_rate": 20  // Reduce from 30
     }
   }
   

2. Optimize GPU usage:

   # Check GPU memory
   nvidia-smi
   
   # Reduce GPU memory usage
   export CUDA_VISIBLE_DEVICES=0
   

3. Close unnecessary applications:

   # Free up system resources
   killall chrome firefox  # Close browsers
   

Low Accuracy (>10cm)

Symptoms: Poor tracking accuracy, drift

Solutions:

1. Recalibrate sensors:

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

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

# Check system logs
dmesg | tail -20

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

Solutions:

1. Check memory usage:

   # Monitor memory
   free -h
   
   # Check for memory leaks
   valgrind python -m src.ui.holodeck_ui
   

2. Update dependencies:

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

3. Check GPU drivers:

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

   # Install missing dependencies
   pip install -r requirements.txt
   
   # Check Python path
   python -c "import sys; print(sys.path)"
   

2. OpenCV errors:

   # Reinstall OpenCV
   pip uninstall opencv-python
   pip install opencv-python-headless
   

3. PyQt6 errors:

   # Reinstall PyQt6
   pip uninstall PyQt6
   pip install PyQt6
   

Build Issues

CMake Errors

Symptoms: Build fails with CMake errors

Solutions:

1. Install missing dependencies:

   # Ubuntu/Debian
   sudo apt-get install build-essential cmake libopencv-dev libeigen3-dev
   
   # macOS
   brew install cmake opencv eigen
   

2. Clear build cache:

   # Clean build directory
   rm -rf build/
   mkdir build
   cd build
   cmake ..
   make -j$(nproc)
   

3. Check CMake version:

   # Update CMake
   cmake --version
   # Should be >= 3.16
   

Python Build Errors

Symptoms: pip install fails

Solutions:

1. Update pip and setuptools:

   pip install --upgrade pip setuptools wheel
   

2. Install build dependencies:

   # Ubuntu/Debian
   sudo apt-get install python3-dev
   
   # macOS
   xcode-select --install
   

3. Use virtual environment:

   python -m venv venv
   source venv/bin/activate
   pip install -e .
   

🔍 Advanced Debugging

Debug Mode

# Run with debug logging
python -m src.ui.holodeck_ui --debug

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

Performance Profiling

# 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

# Install memory profiler
pip install memory-profiler

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

Network Debugging

# 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

# 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

# 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

# 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

# Remove all data
rm -rf data/ logs/ build/

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

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

System Reset

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

   # System info
   uname -a
   python --version
   nvidia-smi  # if applicable
   

Where to Get Help

• 📖 Documentation: docs/ - Comprehensive guides
• 🐛 GitHub Issues: Issues - Bug reports
• 💬 Discord: Discord Server - Real-time help
• 📧 Email: support@nowyouseeme.dev - Direct support
• 💡 Discussions: GitHub 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 or ask the community!