simulation/docs/troubleshooting.md

Troubleshooting Guide

Common Issues

1. Gazebo Won't Start

Symptoms: Gazebo window doesn't open, or crashes immediately

Solutions:

# Kill any existing Gazebo processes
killall gzserver gzclient

# Check for port conflicts
lsof -i :11345

# Try software rendering
export LIBGL_ALWAYS_SOFTWARE=1
gazebo

2. ArduPilot SITL Connection Failed

Symptoms: MAVROS can't connect to ArduPilot

Solutions:

# Check if SITL is running
ps aux | grep ArduCopter

# Check port availability
lsof -i :14550

# Start SITL manually first
cd ~/ardupilot/ArduCopter
sim_vehicle.py -v ArduCopter -f gazebo-iris --console

# Then start MAVROS
ros2 run mavros mavros_node --ros-args -p fcu_url:=udp://:14550@127.0.0.1:14555

3. Visual Odometry Not Working

Symptoms: No pose output, high drift

Solutions:

• Ensure camera is publishing:

  ros2 topic hz /uav/camera/forward/image_raw
  

• Check for sufficient visual features in scene
• Adjust feature detection parameters in config/uav_params.yaml
• Add visual markers to the world

4. Vehicle Won't Arm

Symptoms: Arm command fails

Solutions:

# Check MAVROS state
ros2 topic echo /uav/mavros/state

# Check for prearm errors
ros2 topic echo /uav/mavros/statustext/recv

# Force arm (use with caution)
ros2 service call /uav/mavros/cmd/arming mavros_msgs/srv/CommandBool "{value: true}"

5. Geofence Immediately Triggers

Symptoms: Vehicle triggers geofence breach on startup

Solutions:

• Check GPS coordinates in config/geofence_params.yaml
• Ensure Gazebo world has correct spherical_coordinates
• Verify MAVROS is receiving GPS:

  ros2 topic echo /uav/mavros/global_position/global
  

6. High CPU/Memory Usage

Symptoms: System becomes slow during simulation

Solutions:

• Reduce camera resolution in model SDF files
• Lower Gazebo real-time factor
• Disable unnecessary visualizations
• Use headless mode:

  gazebo --headless
  

7. ROS 2 Package Not Found

Symptoms: Package 'uav_ugv_simulation' not found

Solutions:

# Rebuild the package
cd ~/ros2_ws
colcon build --packages-select uav_ugv_simulation

# Source the workspace
source install/setup.bash

# Verify installation
ros2 pkg list | grep uav_ugv

8. Python Import Errors

Symptoms: ModuleNotFoundError: No module named 'xxx'

Solutions:

# Activate virtual environment
source activate_venv.sh

# Reinstall requirements
pip install -r requirements.txt

9. Camera Images Are Black

Symptoms: Camera topic publishes but images are empty

Solutions:

• Check lighting in Gazebo world
• Verify camera plugin is loaded:

  ros2 topic info /uav/camera/forward/image_raw
  

• Check camera is within clip range

10. Vehicle Drifts Excessively

Symptoms: Position estimate diverges from actual position

Solutions:

• Increase visual features in environment
• Add ArUco markers for landmark tracking
• Tune EKF covariances in config/uav_params.yaml
• Check optical flow height compensation

Debug Commands

# View all ROS nodes
ros2 node list

# Check topic connections
ros2 topic info /topic_name

# View parameter values
ros2 param dump /node_name

# Echo topic data
ros2 topic echo /topic_name --once

# View TF tree
ros2 run tf2_tools view_frames

Log Files

• Gazebo: ~/.gazebo/log/
• ROS 2: ~/.ros/log/
• ArduPilot: Check console window

Getting Help

1. Check ROS 2 logs: ros2 launch --debug ...
2. Enable verbose Gazebo: gazebo --verbose
3. Check ArduPilot parameters: Use MAVProxy console