simulation/README.md

# UAV-UGV Gazebo SITL Simulation
## GPS-Denied Navigation with Geofencing

A production-ready 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)
- NOT used for waypoint navigation
- NOT used for position control

## System Requirements

- **Ubuntu 22.04 LTS** (or 24.04)
- **16GB RAM** recommended (8GB minimum)
- **50GB disk space** (for ArduPilot + Gazebo)
- NVIDIA GPU recommended but not required

### Supported Platforms
- Native Ubuntu Linux
- Windows WSL2 with Ubuntu 22.04

## Installation (One Command)

```bash
# Clone the repository
git clone https://git.sirblob.co/SirBlob/simulation.git
cd simulation

# Run the complete setup (installs everything)
bash setup.sh
```

The setup script installs:
- ROS 2 Humble
- Gazebo 11
- ArduPilot SITL
- ardupilot_gazebo plugin
- MAVROS
- Python dependencies

**Note**: Full installation takes 20-40 minutes depending on your internet speed.

## Quick Start

```bash
# Navigate to project
cd ~/simulation  # or wherever you cloned it

# Activate environment (sets up ROS 2, Gazebo, ArduPilot, Python)
source activate_venv.sh

# Run simulation
bash scripts/run_simulation.sh

# For WSL (if graphics issues):
bash scripts/run_simulation.sh --software-render
```

## Controlling the UAV

Once the simulation is running, control via ROS 2:

```bash
# Arm the drone
ros2 service call /mavros/cmd/arming mavros_msgs/srv/CommandBool "{value: true}"

# Set GUIDED mode (allows position control)
ros2 service call /mavros/set_mode mavros_msgs/srv/SetMode "{custom_mode: 'GUIDED'}"

# Takeoff to 5 meters
ros2 service call /mavros/cmd/takeoff mavros_msgs/srv/CommandTOL "{altitude: 5}"

# Fly to position (LOCAL coordinates - no GPS!)
ros2 topic pub /mavros/setpoint_position/local geometry_msgs/PoseStamped \
  "{header: {frame_id: 'map'}, pose: {position: {x: 10, y: 5, z: 5}}}"

# Land
ros2 service call /mavros/cmd/land mavros_msgs/srv/CommandTOL "{}"
```

## 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
- **GPS geofencing** - safety boundaries only
- **ArduPilot SITL** - real flight controller firmware
- **MAVROS** - ROS 2 interface for MAVLink
- **Multiple worlds** - indoor warehouse, urban canyon

## 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)         │
└─────────────────┬───────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────┐
│         ArduPilot Flight Controller                 │
│  Receives position via MAVROS (external nav)       │
│  Controls motors based on local setpoints           │
└─────────────────────────────────────────────────────┘
```

## Project Structure

```
simulation/
├── setup.sh                 # One-command installation
├── activate_venv.sh         # Environment activation
├── scripts/
│   ├── run_simulation.sh    # Launch full simulation
│   └── kill_simulation.sh   # Stop all processes
├── worlds/                  # Gazebo world files
├── models/                  # UAV and UGV models
├── src/
│   ├── vision/              # Visual odometry, optical flow
│   ├── localization/        # EKF sensor fusion
│   ├── navigation/          # Path planning
│   ├── control/             # UAV/UGV controllers
│   └── safety/              # Geofencing
├── config/                  # Configuration files
└── docs/                    # Documentation
```

## Documentation

- [Setup Guide](docs/setup_guide.md) - Detailed installation
- [WSL Setup Guide](docs/wsl_setup_guide.md) - Windows WSL2
- [Usage Guide](docs/usage.md) - How to use
- [Architecture](docs/architecture.md) - System design
- [GPS-Denied Navigation](docs/gps_denied_navigation.md) - Navigation approach
- [Troubleshooting](docs/troubleshooting.md) - Common issues

## Simulation Options

```bash
# Default (ArduPilot Iris world)
bash scripts/run_simulation.sh

# Custom world
bash scripts/run_simulation.sh --world worlds/indoor_warehouse.world

# Rover instead of copter
bash scripts/run_simulation.sh --vehicle rover

# Software rendering (WSL/no GPU)
bash scripts/run_simulation.sh --software-render
```

## 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) |