simulation/docs/troubleshooting.md

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 setup.sh

Gazebo cmake error (gz-cmake3 not found)

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

Install Gazebo development packages:

sudo apt install libgz-cmake3-dev libgz-sim8-dev libgz-plugin2-dev

ArduPilot build fails

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

ardupilot_gazebo build fails

Ensure Gazebo dev packages are installed:

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:

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:

gz sim --version

Check plugin path:

echo $GZ_SIM_SYSTEM_PLUGIN_PATH
ls ~/ardupilot_gazebo/build/libArduPilotPlugin.so

Black screen in Gazebo (WSL)

Use software rendering:

export LIBGL_ALWAYS_SOFTWARE=1
bash scripts/run_simulation.sh

Or use the flag:

bash scripts/run_simulation.sh --software-render

Gazebo crashes with OpenGL error

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

sim_vehicle.py not found

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

Or source the activation script:

source activate_venv.sh

MAVProxy not found

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

Drone doesn't respond to commands

1. Check ArduPilot is running:

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

export DISPLAY=:0

For VcXsrv (Windows 10):

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

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

# Or set environment
export LIBGL_ALWAYS_SOFTWARE=1

Logs and Debugging

Gazebo verbose output

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

ArduPilot logs

Logs are saved in:

~/ardupilot/logs/

Check ROS topics

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

Reset Everything

# 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 scripts/uninstall.sh
bash setup.sh