Initial Commit
This commit is contained in:
218
README.md
Normal file
218
README.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# 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
|
||||
- Python 3.10
|
||||
- ROS 2 Humble
|
||||
- 8GB RAM minimum (16GB recommended)
|
||||
- NVIDIA GPU recommended
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# 1. Clone repository
|
||||
cd ~/ros2_ws/src
|
||||
git clone <your-repo-url> 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
|
||||
```
|
||||
|
||||
## 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)
|
||||
- [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).
|
||||
Reference in New Issue
Block a user