Initial Commit

docs/troubleshooting.md

@@ -0,0 +1,178 @@
+# 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
+