simulation/docs/troubleshooting.md

# Troubleshooting Guide

## Common Issues

### Arming Failed

**Symptoms:**
- "PreArm: Gyros inconsistent"
- "PreArm: Need Position Estimate"
- "Arm: Throttle too high"

**Solution:**
```bash
# Wait for EKF initialization (15+ seconds)
# Look for these messages:
#   EKF3 IMU0 initialised
#   EKF3 IMU1 initialised
#   AHRS: EKF3 active

# Then force arm:
mode guided
arm throttle force
takeoff 5
```

### Gazebo Won't Start

**Symptoms:**
- "libGL error"
- Black screen
- Segmentation fault

**Solution (WSL/No GPU):**
```bash
# Use software rendering
bash scripts/run_autonomous.sh --software-render

# Or set manually:
export LIBGL_ALWAYS_SOFTWARE=1
export GALLIUM_DRIVER=llvmpipe
```

### ArduPilot SITL Won't Connect

**Symptoms:**
- "Waiting for heartbeat"
- Connection timeout
- "No MAVLink heartbeat"

**Solution:**
```bash
# Kill existing processes
bash scripts/kill_simulation.sh

# Check if port is in use
lsof -i :5760

# Restart simulation
bash scripts/run_autonomous.sh --search spiral
```

### MAVROS Connection Failed

**Symptoms:**
- "FCU connection lost"
- MAVROS not publishing topics

**Solution:**
```bash
# Verify SITL is running
pgrep -a arducopter

# Check connection URL
# Should be tcp://127.0.0.1:5760

# Restart MAVROS
ros2 run mavros mavros_node --ros-args -p fcu_url:=tcp://127.0.0.1:5760
```

### Drone Drifts / Unstable

**Symptoms:**
- Position drift after takeoff
- Oscillations
- Won't hold position

**Causes:**
1. Visual odometry not providing updates
2. EKF not using external nav
3. Poor camera data

**Solution:**
```bash
# Verify VO is publishing
ros2 topic hz /uav/visual_odometry/pose

# Check EKF source
# In MAVProxy:
param show EK3_SRC1_POSXY  # Should be 6

# Verify camera is working
ros2 topic hz /uav/camera/forward/image_raw
```

### Module Not Found

**Symptoms:**
- "ModuleNotFoundError: No module named 'pymavlink'"
- "ImportError: No module named 'cv2'"

**Solution:**
```bash
# Activate virtual environment
source activate_venv.sh

# Reinstall dependencies
pip install -r requirements.txt
```

### Build Failed (Missing pexpect/future)

**Symptoms:**
- "you need to install pexpect with 'python3 -m pip install pexpect'"
- "ModuleNotFoundError: No module named 'future'"
- `install-prereqs-ubuntu.sh` fails with "Can not perform a '--user' install"

**Solution:**
This usually happens if the virtual environment is active during the build process but lacks dependencies.

```bash
# Deactivate any active virtualenv
deactivate

# helper to install missing deps into venv
source activate_venv.sh
pip install pexpect future
```

source activate_venv.sh
pip install pexpect future
```

### Build Failed (Missing catkin_pkg)

**Symptoms:**
- `ModuleNotFoundError: No module named 'catkin_pkg'` within `package_xml_2_cmake.py`
- CMake configuration error at `ament_package_xml.cmake`

**Solution:**
This occurs when the virtual environment is missing ROS 2 build dependencies that are normally present in the system python but not in the venv.

```bash
source activate_venv.sh
pip install catkin_pkg
```

## WSL-Specific Issues

### Display Not Available

**Symptoms:**
- "cannot open display"
- GUI won't show

**Solution:**
```bash
# Install VcXsrv on Windows, then:
export DISPLAY=:0

# Or use WSLg (Windows 11)
# Should work automatically
```

### Graphics Performance

**Symptoms:**
- Very slow rendering
- Low FPS in Gazebo

**Solution:**
```bash
# Use software rendering
export LIBGL_ALWAYS_SOFTWARE=1
export GALLIUM_DRIVER=llvmpipe

# Or reduce visual quality
# In Gazebo, disable shadows and effects
```

## Debugging Commands

### Check Running Processes

```bash
# All simulation processes
pgrep -a "gz|ardupilot|mavros|ros2"

# ArduPilot SITL
pgrep -a arducopter

# Gazebo
pgrep -a "gz sim"
```

### View Logs

```bash
# ArduPilot logs
ls ~/.ardupilot/logs/

# ROS 2 logs
ros2 run rqt_console rqt_console
```

### Check Topics

```bash
# List all topics
ros2 topic list

# Check topic rate
ros2 topic hz /uav/mavros/state

# View topic data
ros2 topic echo /uav/mavros/local_position/pose
```

### Check Services

```bash
# List services
ros2 service list

# Call arming service
ros2 service call /uav/mavros/cmd/arming mavros_msgs/srv/CommandBool "{value: true}"
```

## Reset Procedures

### Soft Reset

```bash
# Kill all processes
bash scripts/kill_simulation.sh

# Wait 5 seconds
sleep 5

# Restart
bash scripts/run_autonomous.sh --search spiral
```

### Full Reset

```bash
# Kill everything
bash scripts/kill_simulation.sh
pkill -9 -f python
pkill -9 -f ros2

# Clear ArduPilot eeprom
rm -rf ~/.ardupilot/eeprom.bin

# Restart
bash scripts/run_autonomous.sh --search spiral
```

### Reinstall

```bash
# Uninstall
bash scripts/uninstall.sh --all

# Reinstall
bash setup.sh
```

## Getting Help

1. Check the logs in the terminal
2. Verify all processes are running
3. Check ROS 2 topics are publishing
4. Ensure EKF is initialized before arming
5. Use `--software-render` on WSL/no GPU

## Related Documentation

- [Setup Guide](setup_guide.md)
- [Usage Guide](usage.md)
- [WSL Setup](wsl_setup_guide.md)