simulation/docs/troubleshooting.md

Troubleshooting Guide

Common Issues

Arming Failed

Symptoms:

• "PreArm: Gyros inconsistent"
• "PreArm: Need Position Estimate"
• "Arm: Throttle too high"

Solution:

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

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

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

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

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

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

# Deactivate any active virtualenv
deactivate

# helper to install missing deps into venv
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.

source activate_venv.sh
pip install catkin_pkg

WSL-Specific Issues

Display Not Available

Symptoms:

• "cannot open display"
• GUI won't show

Solution:

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

# 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

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

# ArduPilot SITL
pgrep -a arducopter

# Gazebo
pgrep -a "gz sim"

View Logs

# ArduPilot logs
ls ~/.ardupilot/logs/

# ROS 2 logs
ros2 run rqt_console rqt_console

Check Topics

# 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

# 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

# Kill all processes
bash scripts/kill_simulation.sh

# Wait 5 seconds
sleep 5

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

Full Reset

# 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

# 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
• Usage Guide
• WSL Setup