# UAV-UGV Simulation

A ROS 2 simulation environment for UAV and UGV development using GPS-denied navigation with vision-based localization, while maintaining GPS-based geofencing for safety.

## Features

- **GPS-Denied Navigation**: Visual odometry, optical flow, and EKF sensor fusion
- **GPS-Based Geofencing**: Safety boundaries using GPS (navigation remains GPS-free)
- **ArUco Marker Search**: Spiral, lawnmower, and Lévy walk search algorithms
- **Multi-Vehicle Support**: Coordinated UAV and UGV operations
- **ArduPilot SITL**: Full flight controller simulation
- **Gazebo Harmonic**: Modern physics simulation
- **ROS 2 Integration**: Full ROS 2 Humble/Jazzy support

## Requirements

- Ubuntu 22.04 or 24.04 (WSL2 supported)
- 16GB RAM recommended
- 50GB disk space
- NVIDIA GPU recommended (software rendering available)

## Installation

```bash
git clone <repository-url> ~/sim/uav_ugv_simulation
cd ~/sim/uav_ugv_simulation
bash setup.sh
```

Installation takes 20-40 minutes (builds ArduPilot from source).

## Quick Start

```bash
cd ~/sim/uav_ugv_simulation
source activate_venv.sh

# Spiral search (default)
bash scripts/run_autonomous.sh --search spiral

# Lawnmower search
bash scripts/run_autonomous.sh --search lawnmower

# Lévy walk search
bash scripts/run_autonomous.sh --search levy

# WSL/Software rendering
bash scripts/run_autonomous.sh --software-render --search spiral
```

### Manual Mode (MAVProxy)

```bash
bash scripts/run_simulation.sh
# Wait for EKF initialization (~15 seconds), then:
# mode guided
# arm throttle force
# takeoff 5
```

### ROS 2 Mode

```bash
source /opt/ros/humble/setup.bash
ros2 launch uav_ugv_simulation full_simulation.launch.py
```

## Search Algorithms

| Algorithm | Description |
|-----------|-------------|
| `spiral` | Expanding square spiral from current position |
| `lawnmower` | Systematic back-and-forth lane coverage |
| `levy` | Random walk with Lévy-distributed step lengths |

All search algorithms continuously scan for ArUco markers using the downward camera during flight. Detected markers are logged with their ID, position, and distance.

## GPS-Denied Navigation

**Navigation** uses only relative positioning:
- Visual odometry from cameras
- Optical flow sensors
- IMU integration
- Local coordinate frames (NED)

**GPS is ONLY used for geofencing** (safety boundaries), NOT for navigation or position control.

## Speed Limits

Speed and acceleration are capped to prevent aggressive tilting in simulation. Defaults are applied automatically via `configure_speed_limits()` in `setup_ardupilot()`.

| Parameter | Default | Unit |
|-----------|---------|------|
| `WPNAV_SPEED` | 150 | cm/s |
| `WPNAV_ACCEL` | 100 | cm/s² |
| `WPNAV_SPEED_UP` | 100 | cm/s |
| `WPNAV_SPEED_DN` | 75 | cm/s |
| `WPNAV_ACCEL_Z` | 75 | cm/s² |
| `LOIT_SPEED` | 150 | cm/s |

Override in code:

```python
ctrl.configure_speed_limits(wpnav_speed=200, wpnav_accel=150)
```

## Project Structure

```
uav_ugv_simulation/
├── setup.sh                    # Installation script
├── scripts/
│   ├── run_autonomous.sh       # Autonomous simulation
│   ├── run_simulation.sh       # Manual simulation
│   └── kill_simulation.sh      # Cleanup
├── src/
│   ├── main.py                 # Entry point
│   ├── control/                # UAV controller, search algorithms
│   ├── vision/                 # ArUco detector, visual odometry, optical flow
│   ├── localization/           # EKF sensor fusion
│   ├── navigation/             # Path planning
│   └── safety/                 # Geofencing, failsafe
├── config/
│   ├── search.yaml             # Search algorithm parameters
│   ├── uav.yaml                # UAV configuration
│   └── ugv.yaml                # UGV configuration
├── launch/                     # ROS 2 launch files
├── models/                     # Gazebo models
└── worlds/                     # Gazebo worlds
```

## Commands

| Command | Description |
|---------|-------------|
| `bash scripts/run_autonomous.sh` | Run autonomous search |
| `bash scripts/run_simulation.sh` | Run manual simulation |
| `bash scripts/kill_simulation.sh` | Kill all processes |
| `bash scripts/uninstall.sh` | Uninstall ArduPilot |

## Documentation

- [Setup Guide](docs/setup_guide.md)
- [Usage Guide](docs/usage.md)
- [Architecture](docs/architecture.md)
- [GPS-Denied Navigation](docs/gps_denied_navigation.md)
- [WSL Setup](docs/wsl_setup_guide.md)
- [Troubleshooting](docs/troubleshooting.md)

## License

MIT License