# Troubleshooting

Common issues and solutions.

## Installation Issues

### ROS 2 packages not found

```
E: Unable to locate package ros-humble-ros-base
```

Check Ubuntu version matches ROS distro:
- Ubuntu 22.04 → ROS 2 Humble
- Ubuntu 24.04 → ROS 2 Jazzy

Re-run setup:
```bash
bash setup.sh
```

### Gazebo cmake error (gz-cmake3 not found)

```
Could not find a package configuration file provided by "gz-cmake3"
```

Install Gazebo development packages:
```bash
sudo apt install libgz-cmake3-dev libgz-sim8-dev libgz-plugin2-dev
```

### ArduPilot build fails

```bash
cd ~/ardupilot
./waf clean
./waf configure --board sitl
./waf copter
```

### ardupilot_gazebo build fails

Ensure Gazebo dev packages are installed:
```bash
sudo apt install gz-harmonic libgz-cmake3-dev libgz-sim8-dev \
    libgz-plugin2-dev libgz-common5-dev libgz-physics7-dev \
    libgz-sensors8-dev rapidjson-dev
```

Rebuild:
```bash
cd ~/ardupilot_gazebo
rm -rf build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
```

## Runtime Issues

### Gazebo won't start

Check Gazebo installation:
```bash
gz sim --version
```

Check plugin path:
```bash
echo $GZ_SIM_SYSTEM_PLUGIN_PATH
ls ~/ardupilot_gazebo/build/libArduPilotPlugin.so
```

### Black screen in Gazebo (WSL)

Use software rendering:
```bash
export LIBGL_ALWAYS_SOFTWARE=1
bash scripts/run_simulation.sh
```

Or use the flag:
```bash
bash scripts/run_simulation.sh --software-render
```

### Gazebo crashes with OpenGL error

```bash
export MESA_GL_VERSION_OVERRIDE=3.3
export MESA_GLSL_VERSION_OVERRIDE=330
export LIBGL_ALWAYS_SOFTWARE=1
```

### sim_vehicle.py not found

```bash
export PATH=$PATH:$HOME/ardupilot/Tools/autotest
```

Or source the activation script:
```bash
source activate_venv.sh
```

### MAVProxy not found

```bash
pip3 install --user mavproxy pymavlink
export PATH=$PATH:$HOME/.local/bin
```

### Drone doesn't respond to commands

1. Check ArduPilot is running:
```bash
ps aux | grep arducopter
```

2. Check connection:
```
# In MAVProxy console
status
```

3. Ensure GUIDED mode:
```
mode guided
```

4. Arm the drone:
```
arm throttle
```

### Drone immediately disarms

Usually means pre-arm checks failing:
```
# In MAVProxy console
arm check
```

Common fixes:
```
# Disable GPS check for GPS-denied operation
param set ARMING_CHECK 0
```

### Drone drifts or flips on takeoff

Check EKF is using vision/external nav:
```
# In MAVProxy console
param show EK3_SRC*
```

## WSL-Specific Issues

### DISPLAY not set

For WSLg (Windows 11):
```bash
export DISPLAY=:0
```

For VcXsrv (Windows 10):
```bash
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0
```

### VcXsrv connection refused

1. Ensure XLaunch is running
2. Disable access control in XLaunch
3. Check Windows Firewall allows VcXsrv

### Slow graphics performance

```bash
# Use software rendering
bash scripts/run_simulation.sh --software-render

# Or set environment
export LIBGL_ALWAYS_SOFTWARE=1
```

## Logs and Debugging

### Gazebo verbose output

```bash
gz sim -v4 ~/ardupilot_gazebo/worlds/iris_runway.sdf
```

### ArduPilot logs

Logs are saved in:
```
~/ardupilot/logs/
```

### Check ROS topics

```bash
source activate_venv.sh
ros2 topic list
ros2 topic echo /mavros/state
```

## Reset Everything

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

# Clean rebuild of ArduPilot
cd ~/ardupilot
./waf clean
./waf copter

# Clean rebuild of plugin
cd ~/ardupilot_gazebo
rm -rf build
mkdir build && cd build
cmake ..
make -j$(nproc)
```

## Full Reinstall

```bash
bash scripts/uninstall.sh
bash setup.sh
```