Initial Commit
This commit is contained in:
126
docs/architecture.md
Normal file
126
docs/architecture.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# Architecture Overview
|
||||
|
||||
## System Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ SIMULATION LAYER │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ ┌───────────────┐ │
|
||||
│ │ Gazebo World │ │ ArduPilot SITL │ │ MAVROS │ │
|
||||
│ │ (Physics, Viz) │ │ (Autopilot) │ │ (ROS Bridge) │ │
|
||||
│ └────────┬─────────┘ └────────┬─────────┘ └───────┬───────┘ │
|
||||
└───────────┼─────────────────────┼─────────────────────┼─────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ SENSOR LAYER │
|
||||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ │
|
||||
│ │ Forward │ │ Downward │ │ IMU │ │ Range- │ │
|
||||
│ │ Camera │ │ Camera │ │ │ │ finder │ │
|
||||
│ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └────┬─────┘ │
|
||||
└────────┼───────────────┼───────────────┼──────────────┼────────┘
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ PERCEPTION LAYER │
|
||||
│ ┌─────────────────────┐ ┌────────────────┐ ┌──────────────┐ │
|
||||
│ │ Visual Odometry │ │ Optical Flow │ │ Landmark │ │
|
||||
│ │ (ORB/SIFT/SURF) │ │ (Lucas-Kanade) │ │ Detection │ │
|
||||
│ └──────────┬──────────┘ └───────┬────────┘ └──────┬───────┘ │
|
||||
└─────────────┼─────────────────────┼──────────────────┼──────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ LOCALIZATION LAYER │
|
||||
│ ┌──────────────────────┐ │
|
||||
│ │ Position Estimator │ │
|
||||
│ │ (EKF Sensor Fusion)│ │
|
||||
│ └──────────┬───────────┘ │
|
||||
└───────────────────────────────┼─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ NAVIGATION LAYER │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Local Planner │ │ Obstacle │ │ Waypoint │ │
|
||||
│ │ │ │ Avoidance │ │ Follower │ │
|
||||
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
|
||||
└───────────┼────────────────────┼────────────────────┼───────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CONTROL LAYER │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ UAV Controller │ │ UGV Controller │ │ Mission Planner │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
|
||||
└───────────┼────────────────────┼────────────────────┼───────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ SAFETY LAYER │
|
||||
│ ┌─────────────────────────┐ ┌─────────────────────────────┐ │
|
||||
│ │ Geofence Monitor │ │ Failsafe Handler │ │
|
||||
│ │ (GPS-based only) │ │ (Vision loss, battery) │ │
|
||||
│ └─────────────────────────┘ └─────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Module Descriptions
|
||||
|
||||
### Vision Module (`src/vision/`)
|
||||
- **camera_processor.py**: Image preprocessing, undistortion
|
||||
- **visual_odometry.py**: Feature-based pose estimation
|
||||
- **optical_flow.py**: Velocity from image flow
|
||||
- **object_detector.py**: Landmark/obstacle detection
|
||||
- **visual_servoing.py**: Vision-based control
|
||||
|
||||
### Localization Module (`src/localization/`)
|
||||
- **position_estimator.py**: Sensor fusion for position
|
||||
- **ekf_fusion.py**: Extended Kalman Filter implementation
|
||||
- **landmark_tracker.py**: Track known visual features
|
||||
|
||||
### Navigation Module (`src/navigation/`)
|
||||
- **local_planner.py**: Path planning in local frame
|
||||
- **obstacle_avoidance.py**: Reactive obstacle avoidance
|
||||
- **waypoint_follower.py**: Sequential waypoint navigation
|
||||
|
||||
### Control Module (`src/control/`)
|
||||
- **uav_controller.py**: Quadcopter flight control
|
||||
- **ugv_controller.py**: Ground vehicle control
|
||||
- **mission_planner.py**: Multi-vehicle coordination
|
||||
|
||||
### Safety Module (`src/safety/`)
|
||||
- **geofence_monitor.py**: GPS-based boundary checking
|
||||
- **failsafe_handler.py**: Emergency procedures
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
Camera Image → Feature Detection → Feature Matching →
|
||||
Essential Matrix → Relative Pose → EKF Update →
|
||||
Local Position → Navigation Controller →
|
||||
Velocity Commands → MAVROS → ArduPilot
|
||||
```
|
||||
|
||||
## ROS 2 Topics
|
||||
|
||||
### Sensor Topics
|
||||
- `/uav/camera/forward/image_raw`
|
||||
- `/uav/camera/downward/image_raw`
|
||||
- `/uav/imu/data`
|
||||
- `/uav/rangefinder/range`
|
||||
|
||||
### Perception Topics
|
||||
- `/uav/visual_odometry/pose`
|
||||
- `/uav/optical_flow/velocity`
|
||||
|
||||
### Control Topics
|
||||
- `/uav/mavros/setpoint_position/local`
|
||||
- `/uav/mavros/setpoint_velocity/cmd_vel`
|
||||
- `/ugv/cmd_vel`
|
||||
|
||||
### Safety Topics
|
||||
- `/geofence/status`
|
||||
- `/failsafe/active`
|
||||
|
||||
198
docs/gps_denied_navigation.md
Normal file
198
docs/gps_denied_navigation.md
Normal file
@@ -0,0 +1,198 @@
|
||||
# GPS-Denied Navigation
|
||||
|
||||
## Overview
|
||||
|
||||
This project implements **GPS-denied navigation** for UAV and UGV vehicles. Instead of relying on GPS for position estimation and waypoint navigation, the system uses vision-based sensors and local coordinate frames.
|
||||
|
||||
## Why GPS-Denied?
|
||||
|
||||
GPS-denied navigation is critical for scenarios where GPS is:
|
||||
|
||||
1. **Unavailable**: Indoor environments, underground, tunnels
|
||||
2. **Unreliable**: Urban canyons with multipath errors
|
||||
3. **Jammed/Spoofed**: Electronic warfare, contested environments
|
||||
4. **Degraded**: Under bridges, heavy foliage, near tall structures
|
||||
|
||||
## Navigation Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ VISION SENSORS │
|
||||
│ • Forward Camera (640x480, 30Hz) │
|
||||
│ • Downward Camera (320x240, 30Hz) │
|
||||
│ • Optional: Depth Camera, LiDAR │
|
||||
└───────────────────┬─────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ VISUAL ODOMETRY MODULE │
|
||||
│ • Feature detection (ORB/SIFT/SURF) │
|
||||
│ • Feature matching between frames │
|
||||
│ • Essential matrix estimation │
|
||||
│ • Relative pose computation │
|
||||
└───────────────────┬─────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ OPTICAL FLOW MODULE │
|
||||
│ • Lucas-Kanade optical flow │
|
||||
│ • Velocity estimation from flow vectors │
|
||||
│ • Height compensation using rangefinder │
|
||||
└───────────────────┬─────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ POSITION ESTIMATOR (EKF) │
|
||||
│ Fuses: │
|
||||
│ • Visual odometry (weight: 0.6) │
|
||||
│ • Optical flow (weight: 0.3) │
|
||||
│ • IMU integration (weight: 0.1) │
|
||||
│ Output: Local position/velocity estimate │
|
||||
└───────────────────┬─────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ NAVIGATION CONTROLLER │
|
||||
│ • Waypoints in LOCAL frame (x, y, z meters) │
|
||||
│ • Path planning using relative coordinates │
|
||||
│ • Obstacle avoidance using depth/camera │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Coordinate Frames
|
||||
|
||||
### LOCAL_NED Frame
|
||||
- **Origin**: Vehicle starting position
|
||||
- **X**: North (forward)
|
||||
- **Y**: East (right)
|
||||
- **Z**: Down
|
||||
|
||||
### Body Frame
|
||||
- **X**: Forward
|
||||
- **Y**: Right
|
||||
- **Z**: Down
|
||||
|
||||
## GPS Usage: Geofencing Only
|
||||
|
||||
While navigation is GPS-denied, GPS is still used for **geofencing** (safety boundaries):
|
||||
|
||||
```yaml
|
||||
geofence:
|
||||
enabled: true
|
||||
use_gps: true # GPS ONLY for geofence check
|
||||
|
||||
polygon_points:
|
||||
- {lat: 47.397742, lon: 8.545594}
|
||||
- {lat: 47.398242, lon: 8.545594}
|
||||
- {lat: 47.398242, lon: 8.546094}
|
||||
- {lat: 47.397742, lon: 8.546094}
|
||||
|
||||
action_on_breach: "RTL" # Return to LOCAL origin
|
||||
```
|
||||
|
||||
## Example: Relative Waypoint Mission
|
||||
|
||||
```python
|
||||
# All waypoints are in LOCAL frame (meters from origin)
|
||||
waypoints = [
|
||||
{"x": 0, "y": 0, "z": 5}, # Takeoff to 5m
|
||||
{"x": 10, "y": 0, "z": 5}, # 10m forward
|
||||
{"x": 10, "y": 10, "z": 5}, # 10m right
|
||||
{"x": 0, "y": 0, "z": 5}, # Return to origin
|
||||
{"x": 0, "y": 0, "z": 0}, # Land
|
||||
]
|
||||
```
|
||||
|
||||
## Sensor Fusion Details
|
||||
|
||||
### Extended Kalman Filter State
|
||||
|
||||
```
|
||||
State vector x = [px, py, pz, vx, vy, vz, ax, ay, az]
|
||||
|
||||
Where:
|
||||
- px, py, pz = position (meters)
|
||||
- vx, vy, vz = velocity (m/s)
|
||||
- ax, ay, az = acceleration (m/s²)
|
||||
```
|
||||
|
||||
### Measurement Sources
|
||||
|
||||
| Source | Measures | Update Rate | Noise |
|
||||
|-----------------|----------------|-------------|-------|
|
||||
| Visual Odometry | Position | 30 Hz | 0.05m |
|
||||
| Optical Flow | Velocity | 60 Hz | 0.1m/s|
|
||||
| IMU | Acceleration | 200 Hz | 0.2m/s²|
|
||||
| Rangefinder | Altitude | 30 Hz | 0.02m |
|
||||
|
||||
## Drift Mitigation
|
||||
|
||||
GPS-denied navigation accumulates drift over time. Mitigation strategies:
|
||||
|
||||
1. **Visual Landmarks**: Detect and track known markers (ArUco)
|
||||
2. **Loop Closure**: Recognize previously visited locations
|
||||
3. **Ground Truth Reset**: Periodic reset in simulation
|
||||
4. **Multi-Sensor Fusion**: Reduce individual sensor drift
|
||||
|
||||
## Configuration Parameters
|
||||
|
||||
### Visual Odometry
|
||||
|
||||
```yaml
|
||||
visual_odometry:
|
||||
method: "ORB" # or "SIFT", "SURF"
|
||||
min_features: 100
|
||||
max_features: 500
|
||||
feature_quality: 0.01
|
||||
```
|
||||
|
||||
### Optical Flow
|
||||
|
||||
```yaml
|
||||
optical_flow:
|
||||
method: "Lucas-Kanade"
|
||||
window_size: 15
|
||||
max_level: 3
|
||||
min_altitude: 0.3 # meters
|
||||
```
|
||||
|
||||
### Position Estimator
|
||||
|
||||
```yaml
|
||||
position_estimator:
|
||||
fusion_method: "EKF"
|
||||
weights:
|
||||
visual_odometry: 0.6
|
||||
optical_flow: 0.3
|
||||
imu: 0.1
|
||||
```
|
||||
|
||||
## Testing GPS-Denied Navigation
|
||||
|
||||
### Indoor Warehouse World
|
||||
```bash
|
||||
bash scripts/run_simulation.sh worlds/indoor_warehouse.world
|
||||
```
|
||||
|
||||
### Urban Canyon World
|
||||
```bash
|
||||
bash scripts/run_simulation.sh worlds/urban_canyon.world
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### High Position Drift
|
||||
- Check camera exposure/focus
|
||||
- Ensure sufficient visual features in environment
|
||||
- Increase feature count in visual odometry
|
||||
- Add visual markers to environment
|
||||
|
||||
### Vision Loss
|
||||
- The failsafe handler triggers after 5 seconds of no visual odometry
|
||||
- Action: HOLD (hover in place) by default
|
||||
- Configure with `action_on_vision_loss` parameter
|
||||
|
||||
### Geofence Breach
|
||||
- Vehicle returns to LOCAL origin (not GPS home)
|
||||
- RTL uses the same local coordinate system
|
||||
|
||||
144
docs/setup_guide.md
Normal file
144
docs/setup_guide.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Setup Guide
|
||||
|
||||
## System Requirements
|
||||
|
||||
- **OS**: Ubuntu 22.04 LTS (Jammy Jellyfish)
|
||||
- **Python**: 3.10.x (native to Ubuntu 22.04)
|
||||
- **ROS 2**: Humble Hawksbill
|
||||
- **Gazebo**: Classic 11
|
||||
- **RAM**: 8GB minimum, 16GB recommended
|
||||
- **GPU**: NVIDIA GPU recommended for better performance
|
||||
|
||||
## Installation Steps
|
||||
|
||||
### 1. Install ROS 2 Humble
|
||||
|
||||
```bash
|
||||
# Add ROS 2 repository
|
||||
sudo apt update && sudo apt install curl gnupg lsb-release
|
||||
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
|
||||
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
|
||||
|
||||
# Install ROS 2 Humble
|
||||
sudo apt update
|
||||
sudo apt install ros-humble-desktop
|
||||
|
||||
# Source ROS 2
|
||||
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
### 2. Install Gazebo Classic
|
||||
|
||||
```bash
|
||||
sudo apt install gazebo11 libgazebo11-dev ros-humble-gazebo-ros-pkgs
|
||||
```
|
||||
|
||||
### 3. Install ArduPilot SITL
|
||||
|
||||
```bash
|
||||
# Clone ArduPilot
|
||||
cd ~
|
||||
git clone https://github.com/ArduPilot/ardupilot.git
|
||||
cd ardupilot
|
||||
git submodule update --init --recursive
|
||||
|
||||
# Install dependencies
|
||||
Tools/environment_install/install-prereqs-ubuntu.sh -y
|
||||
. ~/.profile
|
||||
|
||||
# Build SITL
|
||||
./waf configure --board sitl
|
||||
./waf copter
|
||||
```
|
||||
|
||||
### 4. Install ardupilot_gazebo Plugin
|
||||
|
||||
```bash
|
||||
cd ~
|
||||
git clone https://github.com/ArduPilot/ardupilot_gazebo.git
|
||||
cd ardupilot_gazebo
|
||||
mkdir build && cd build
|
||||
cmake ..
|
||||
make -j4
|
||||
sudo make install
|
||||
|
||||
# Add to environment
|
||||
echo 'export GAZEBO_MODEL_PATH=$HOME/ardupilot_gazebo/models:$GAZEBO_MODEL_PATH' >> ~/.bashrc
|
||||
echo 'export GAZEBO_RESOURCE_PATH=$HOME/ardupilot_gazebo/worlds:$GAZEBO_RESOURCE_PATH' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
### 5. Setup This Project
|
||||
|
||||
```bash
|
||||
# Clone to ROS 2 workspace
|
||||
cd ~/ros2_ws/src
|
||||
git clone <your-repo-url> uav_ugv_simulation
|
||||
cd uav_ugv_simulation
|
||||
|
||||
# Run automated setup
|
||||
bash setup.sh
|
||||
|
||||
# Reload environment
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
### Test ROS 2
|
||||
```bash
|
||||
ros2 topic list
|
||||
```
|
||||
|
||||
### Test Gazebo
|
||||
```bash
|
||||
gazebo --verbose
|
||||
```
|
||||
|
||||
### Test ArduPilot SITL
|
||||
```bash
|
||||
cd ~/ardupilot/ArduCopter
|
||||
sim_vehicle.py -v ArduCopter -f gazebo-iris --console --map
|
||||
```
|
||||
|
||||
### Test Python Environment
|
||||
```bash
|
||||
cd ~/ros2_ws/src/uav_ugv_simulation
|
||||
source activate_venv.sh
|
||||
python -c "import cv2; import numpy; import rclpy; print('OK')"
|
||||
```
|
||||
|
||||
## Running the Simulation
|
||||
|
||||
```bash
|
||||
cd ~/ros2_ws/src/uav_ugv_simulation
|
||||
source activate_venv.sh
|
||||
bash scripts/run_simulation.sh
|
||||
```
|
||||
|
||||
## NVIDIA GPU Setup (Optional)
|
||||
|
||||
For better Gazebo performance with NVIDIA GPU:
|
||||
|
||||
```bash
|
||||
bash scripts/setup_gazebo_nvidia.sh
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Package not found" error
|
||||
```bash
|
||||
cd ~/ros2_ws
|
||||
colcon build --packages-select uav_ugv_simulation
|
||||
source install/setup.bash
|
||||
```
|
||||
|
||||
### Gazebo crashes
|
||||
- Check GPU drivers: `nvidia-smi`
|
||||
- Try software rendering: `export LIBGL_ALWAYS_SOFTWARE=1`
|
||||
|
||||
### MAVROS connection failed
|
||||
- Ensure ArduPilot SITL is running first
|
||||
- Check port availability: `lsof -i :14550`
|
||||
|
||||
178
docs/troubleshooting.md
Normal file
178
docs/troubleshooting.md
Normal file
@@ -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
|
||||
|
||||
151
docs/usage.md
Normal file
151
docs/usage.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# Usage Guide
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# 1. Navigate to project
|
||||
cd ~/ros2_ws/src/uav_ugv_simulation
|
||||
|
||||
# 2. Activate environment
|
||||
source activate_venv.sh
|
||||
|
||||
# 3. Run simulation
|
||||
bash scripts/run_simulation.sh
|
||||
```
|
||||
|
||||
## Launch Options
|
||||
|
||||
### Full Simulation (UAV + UGV)
|
||||
```bash
|
||||
ros2 launch uav_ugv_simulation full_simulation.launch.py
|
||||
```
|
||||
|
||||
### UAV Only
|
||||
```bash
|
||||
ros2 launch uav_ugv_simulation uav_only.launch.py
|
||||
```
|
||||
|
||||
### UGV Only
|
||||
```bash
|
||||
ros2 launch uav_ugv_simulation ugv_only.launch.py
|
||||
```
|
||||
|
||||
### Different Worlds
|
||||
```bash
|
||||
# Indoor warehouse (GPS-denied)
|
||||
bash scripts/run_simulation.sh worlds/indoor_warehouse.world
|
||||
|
||||
# Urban canyon (GPS-degraded)
|
||||
bash scripts/run_simulation.sh worlds/urban_canyon.world
|
||||
```
|
||||
|
||||
## Interacting with Vehicles
|
||||
|
||||
### UAV Commands
|
||||
```bash
|
||||
# Arm the vehicle
|
||||
ros2 topic pub /uav/controller/command std_msgs/String "data: 'arm'"
|
||||
|
||||
# Takeoff
|
||||
ros2 topic pub /uav/controller/command std_msgs/String "data: 'takeoff'"
|
||||
|
||||
# Go to waypoint (local coordinates)
|
||||
ros2 topic pub /uav/setpoint_position geometry_msgs/PoseStamped \
|
||||
"{header: {frame_id: 'odom'}, pose: {position: {x: 10.0, y: 5.0, z: 5.0}}}"
|
||||
|
||||
# Land
|
||||
ros2 topic pub /uav/controller/command std_msgs/String "data: 'land'"
|
||||
```
|
||||
|
||||
### UGV Commands
|
||||
```bash
|
||||
# Go to goal (local coordinates)
|
||||
ros2 topic pub /ugv/goal_pose geometry_msgs/PoseStamped \
|
||||
"{header: {frame_id: 'odom'}, pose: {position: {x: 5.0, y: 3.0, z: 0.0}}}"
|
||||
|
||||
# Stop
|
||||
ros2 topic pub /ugv/controller/command std_msgs/String "data: 'stop'"
|
||||
```
|
||||
|
||||
## Mission Planner
|
||||
|
||||
### Load Demo Mission
|
||||
```bash
|
||||
ros2 topic pub /mission/command std_msgs/String "data: 'load'"
|
||||
```
|
||||
|
||||
### Start Mission
|
||||
```bash
|
||||
ros2 topic pub /mission/command std_msgs/String "data: 'start'"
|
||||
```
|
||||
|
||||
### Pause/Resume
|
||||
```bash
|
||||
ros2 topic pub /mission/command std_msgs/String "data: 'pause'"
|
||||
ros2 topic pub /mission/command std_msgs/String "data: 'resume'"
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### View Topics
|
||||
```bash
|
||||
# List all topics
|
||||
ros2 topic list
|
||||
|
||||
# UAV status
|
||||
ros2 topic echo /uav/controller/status
|
||||
|
||||
# Visual odometry pose
|
||||
ros2 topic echo /uav/visual_odometry/pose
|
||||
|
||||
# Geofence status
|
||||
ros2 topic echo /geofence/status
|
||||
```
|
||||
|
||||
### View Camera Feeds
|
||||
```bash
|
||||
# Using rqt_image_view
|
||||
ros2 run rqt_image_view rqt_image_view
|
||||
|
||||
# Select topics:
|
||||
# /uav/camera/forward/image_raw
|
||||
# /uav/camera/downward/image_raw
|
||||
```
|
||||
|
||||
### Visualization
|
||||
```bash
|
||||
# RViz
|
||||
rviz2
|
||||
|
||||
# Add displays for:
|
||||
# - TF
|
||||
# - Camera
|
||||
# - Path
|
||||
# - Marker (geofence)
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Modify Parameters
|
||||
|
||||
Edit YAML files in `config/` directory:
|
||||
|
||||
- `uav_params.yaml` - UAV settings
|
||||
- `geofence_params.yaml` - Safety boundaries
|
||||
- `mavros_params.yaml` - MAVROS connection
|
||||
|
||||
### Runtime Parameter Changes
|
||||
```bash
|
||||
ros2 param set /uav/visual_odom_node max_features 500
|
||||
```
|
||||
|
||||
## Stopping the Simulation
|
||||
|
||||
```bash
|
||||
# Graceful shutdown
|
||||
Ctrl+C
|
||||
|
||||
# Force kill all processes
|
||||
bash scripts/kill_simulation.sh
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user