# Troubleshooting Guide

## Common Issues

### 1. Gazebo Won't Start

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

**Solutions**:
```bash
# 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**:
```bash
# 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:
  ```bash
  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**:
```bash
# 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:
  ```bash
  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:
  ```bash
  gazebo --headless
  ```

### 7. ROS 2 Package Not Found

**Symptoms**: `Package 'uav_ugv_simulation' not found`

**Solutions**:
```bash
# 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**:
```bash
# 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:
  ```bash
  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

```bash
# 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