254 lines
8.6 KiB
Markdown
254 lines
8.6 KiB
Markdown
# UAV-UGV Gazebo SITL Simulation
|
|
## GPS-Denied Navigation with Geofencing
|
|
|
|
A complete simulation environment for UAV (drone) and UGV (ground vehicle) development using **GPS-denied navigation** with vision-based localization, while maintaining GPS-based geofencing for safety.
|
|
|
|
## Key Feature: GPS-Denied Navigation
|
|
|
|
**Navigation Mode**: All vehicles navigate using **relative positioning** only:
|
|
- Visual odometry from cameras
|
|
- Optical flow sensors
|
|
- IMU integration
|
|
- Visual landmark tracking
|
|
- Local coordinate frames
|
|
|
|
**GPS Usage**: GPS is ONLY used for:
|
|
- Geofencing (safety boundaries)
|
|
- Initial position reference (optional)
|
|
- NOT used for waypoint navigation
|
|
- NOT used for position control
|
|
|
|
This simulates real-world GPS-denied environments like:
|
|
- Indoor spaces
|
|
- Urban canyons
|
|
- GPS-jammed areas
|
|
- Under bridges/tunnels
|
|
|
|
## Features
|
|
|
|
- **Iris quadcopter** with dual cameras (forward + downward)
|
|
- **Ground vehicle (UGV)** with vision sensors
|
|
- **Visual odometry** - camera-based position estimation
|
|
- **Optical flow** - velocity estimation from downward camera
|
|
- **Landmark navigation** - visual feature tracking
|
|
- **GPS geofencing** - safety boundaries only
|
|
- **Single command launch** - everything runs from one script
|
|
- **NVIDIA GPU acceleration** support
|
|
- **Python virtual environment** for isolated dependencies
|
|
- **GPS-denied worlds** - indoor and urban environments
|
|
|
|
## System Requirements
|
|
|
|
- **Ubuntu 22.04 LTS** (or 24.04 with ROS 2 Jazzy)
|
|
- **Python 3.10+**
|
|
- **ROS 2 Humble** (or Jazzy for Ubuntu 24.04)
|
|
- 8GB RAM minimum (16GB recommended)
|
|
- NVIDIA GPU recommended
|
|
|
|
### WSL2 Support (Windows)
|
|
|
|
This project supports **Windows Subsystem for Linux (WSL2)**:
|
|
- Windows 10 (21H2+) or Windows 11
|
|
- WSL2 with Ubuntu 22.04
|
|
- GUI support via WSLg (Windows 11) or VcXsrv (Windows 10)
|
|
- See [WSL Setup Guide](docs/wsl_setup_guide.md) for detailed instructions
|
|
|
|
## Quick Start
|
|
|
|
### Linux (Native)
|
|
|
|
```bash
|
|
# 1. Clone repository
|
|
cd ~/ros2_ws/src
|
|
git clone https://git.sirblob.co/SirBlob/simulation.git uav_ugv_simulation
|
|
cd uav_ugv_simulation
|
|
|
|
# 2. Run setup (installs everything)
|
|
bash setup.sh
|
|
|
|
# 3. Restart terminal or reload bash
|
|
source ~/.bashrc
|
|
|
|
# 4. Activate virtual environment and run
|
|
source activate_venv.sh
|
|
bash scripts/run_simulation.sh
|
|
```
|
|
|
|
### WSL2 (Windows)
|
|
|
|
```bash
|
|
# 1. Clone repository
|
|
cd ~
|
|
git clone https://git.sirblob.co/SirBlob/simulation.git uav_ugv_simulation
|
|
cd uav_ugv_simulation
|
|
|
|
# 2. Run WSL-specific setup
|
|
bash scripts/setup_wsl.sh
|
|
|
|
# 3. Restart terminal
|
|
exit
|
|
# Reopen WSL terminal
|
|
|
|
# 4. Run simulation
|
|
cd ~/uav_ugv_simulation
|
|
source activate_venv.sh
|
|
bash scripts/run_simulation.sh
|
|
|
|
# If graphics are slow, use software rendering:
|
|
bash scripts/run_simulation.sh --software-render
|
|
```
|
|
|
|
## GPS-Denied Navigation Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Vision Sensors │
|
|
│ Forward Camera + Downward Camera + Optical Flow │
|
|
└─────────────────┬───────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Visual Odometry & Feature Tracking │
|
|
│ Estimates relative position from camera motion │
|
|
└─────────────────┬───────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Position Estimator (EKF Fusion) │
|
|
│ Fuses: Visual Odom + Optical Flow + IMU │
|
|
│ Output: Local position estimate (relative) │
|
|
└─────────────────┬───────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Navigation Controller │
|
|
│ Commands: "Move 5m forward, 3m right" │
|
|
│ (Relative coordinates only, NO GPS waypoints) │
|
|
└─────────────────────────────────────────────────────┘
|
|
|
|
SEPARATE SAFETY LAYER (GPS-based):
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Geofence Monitor │
|
|
│ GPS position → Check against boundaries │
|
|
│ If outside: Emergency RTL or hold │
|
|
└─────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Navigation Modes
|
|
|
|
### 1. **Vision-Only Mode** (Default)
|
|
- Uses camera for all position estimates
|
|
- Suitable for structured environments
|
|
- Requires good lighting and visual features
|
|
|
|
### 2. **Optical Flow Mode**
|
|
- Uses downward camera for velocity
|
|
- Works well at low altitudes
|
|
- Good for hovering and slow flight
|
|
|
|
### 3. **Hybrid Mode**
|
|
- Combines visual odometry + optical flow + IMU
|
|
- Most robust approach
|
|
- Recommended for complex missions
|
|
|
|
## Geofencing Configuration
|
|
|
|
Edit `config/geofence_params.yaml`:
|
|
|
|
```yaml
|
|
geofence:
|
|
enabled: true
|
|
use_gps: true # GPS ONLY for geofence
|
|
|
|
# Define boundaries (GPS coordinates)
|
|
fence_type: "polygon" # or "circle"
|
|
|
|
# Polygon fence (lat/lon points)
|
|
polygon_points:
|
|
- {lat: 47.397742, lon: 8.545594} # Point 1
|
|
- {lat: 47.398242, lon: 8.545594} # Point 2
|
|
- {lat: 47.398242, lon: 8.546094} # Point 3
|
|
- {lat: 47.397742, lon: 8.546094} # Point 4
|
|
|
|
# Or circle fence
|
|
center_lat: 47.397742
|
|
center_lon: 8.545594
|
|
radius_meters: 100
|
|
|
|
# Actions on breach
|
|
action: "RTL" # Return to launch
|
|
max_altitude: 50 # meters
|
|
```
|
|
|
|
## Example Mission (Relative Coordinates)
|
|
|
|
```python
|
|
# Example: Navigate to visual landmark
|
|
|
|
# Define mission in RELATIVE coordinates
|
|
mission_waypoints = [
|
|
{"x": 0, "y": 0, "z": 5}, # Takeoff to 5m
|
|
{"x": 10, "y": 0, "z": 5}, # Move 10m forward
|
|
{"x": 10, "y": 5, "z": 5}, # Move 5m right
|
|
{"x": 0, "y": 5, "z": 5}, # Return to start (offset)
|
|
{"x": 0, "y": 0, "z": 5}, # Back to takeoff point
|
|
{"x": 0, "y": 0, "z": 0}, # Land
|
|
]
|
|
|
|
# GPS is NEVER used for these waypoints
|
|
# Position estimated from visual odometry
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
- `launch/` - ROS 2 launch files
|
|
- `worlds/` - Gazebo world files (indoor, urban)
|
|
- `models/` - Robot models (Iris with cameras, UGV)
|
|
- `src/vision/` - Visual odometry, optical flow
|
|
- `src/localization/` - Position estimation, sensor fusion
|
|
- `src/navigation/` - Path planning (relative coordinates)
|
|
- `src/safety/` - Geofencing (GPS-based)
|
|
- `config/` - Configuration files
|
|
|
|
## Documentation
|
|
|
|
- [Setup Guide](docs/setup_guide.md) - Linux installation
|
|
- [WSL Setup Guide](docs/wsl_setup_guide.md) - Windows WSL2 installation
|
|
- [Usage Guide](docs/usage.md)
|
|
- [Architecture Overview](docs/architecture.md)
|
|
- [GPS-Denied Navigation](docs/gps_denied_navigation.md)
|
|
- [Troubleshooting](docs/troubleshooting.md)
|
|
|
|
## Key Differences from GPS Navigation
|
|
|
|
| Aspect | GPS Navigation | This Project (GPS-Denied) |
|
|
|--------|---------------|---------------------------|
|
|
| Position Source | GPS satellites | Visual odometry + sensors |
|
|
| Waypoint Type | GPS coordinates | Relative coordinates (x,y,z) |
|
|
| Reference Frame | Global (lat/lon) | Local (relative to start) |
|
|
| Indoor Capability | No | Yes |
|
|
| Drift | Minimal | Accumulates over time |
|
|
| Geofencing | GPS-based | GPS-based (safety only) |
|
|
| Use Cases | Outdoor, open sky | Indoor, urban, GPS-jammed |
|
|
|
|
## Running Different Scenarios
|
|
|
|
```bash
|
|
# Indoor warehouse (no GPS available)
|
|
bash scripts/run_simulation.sh --world worlds/indoor_warehouse.world
|
|
|
|
# Urban canyon (degraded GPS)
|
|
bash scripts/run_simulation.sh --world worlds/urban_canyon.world
|
|
|
|
# Open outdoor (GPS available but not used for nav)
|
|
bash scripts/run_simulation.sh --world worlds/empty_custom.world
|
|
```
|
|
|
|
## License
|
|
|
|
MIT License
|
|
|
|
## Contributing
|
|
|
|
Contributions welcome! Please ensure all navigation remains GPS-denied (except geofencing).
|