# Architecture Overview

GPS-denied drone landing simulation with multiple operation modes.

## Operation Modes

### 1. Standalone Mode (Any Platform)

Single-process simulation - no ROS 2 or networking required:

```
┌────────────────────────────────────────┐
│      standalone_simulation.py          │
│  ┌──────────────────────────────────┐  │
│  │  PyBullet Physics + Camera       │  │
│  │  Built-in Landing Controller     │  │
│  │  Rover Movement Patterns         │  │
│  └──────────────────────────────────┘  │
└────────────────────────────────────────┘
```

### 2. PyBullet + ROS 2 Mode (2 Terminals)

```
Terminal 1                    Terminal 2
┌──────────────────┐         ┌──────────────────────────┐
│ simulation_host  │◄─UDP───►│      run_bridge.py       │
│   (PyBullet)     │         │  ┌────────────────────┐  │
│   Port 5555      │         │  │ ROS2SimulatorBridge│  │
│                  │         │  │ DroneController    │  │
│                  │         │  │ RoverController    │  │
└──────────────────┘         │  └────────────────────┘  │
                             └──────────────────────────┘
```

### 3. Gazebo + ROS 2 Mode (2 Terminals, Linux Only)

```
Terminal 1                    Terminal 2
┌──────────────────┐         ┌──────────────────────────┐
│     Gazebo       │◄─ROS───►│      run_gazebo.py       │
│  (gz sim ...)    │         │  ┌────────────────────┐  │
│                  │         │  │ GazeboBridge       │  │
│                  │         │  │ DroneController    │  │
│                  │         │  │ RoverController    │  │
└──────────────────┘         │  └────────────────────┘  │
                             └──────────────────────────┘
```

## Components

| File | Description |
|------|-------------|
| `standalone_simulation.py` | All-in-one simulation |
| `simulation_host.py` | PyBullet physics server (UDP) |
| `run_bridge.py` | PyBullet bridge + controllers |
| `run_gazebo.py` | Gazebo bridge + controllers |
| `drone_controller.py` | Landing algorithm |
| `rover_controller.py` | Moving landing pad |
| `gazebo/launch/drone_landing.launch.py` | ROS 2 launch file for Gazebo |

## ROS Topics

| Topic | Type | Description |
|-------|------|-------------|
| `/cmd_vel` | `Twist` | Drone velocity commands |
| `/drone/telemetry` | `String` | GPS-denied sensor data |
| `/rover/telemetry` | `String` | Rover position (internal) |

## Network Configuration

All components default to `0.0.0.0` for network accessibility.

### Remote Setup

**Machine 1 (with display):**
```bash
python simulation_host.py  # Listens on 0.0.0.0:5555
```

**Machine 2 (headless controller):**
```bash
python run_bridge.py --host 192.168.1.100
```

### UDP Ports

| Port | Direction | Content |
|------|-----------|---------|
| 5555 | Bridge → Simulator | Commands |
| 5556 | Simulator → Bridge | Telemetry |

## GPS-Denied Sensors

All modes provide the same sensor data:

| Sensor | Data |
|--------|------|
| IMU | Orientation, angular velocity |
| Altimeter | Altitude, vertical velocity |
| Velocity | Estimated from optical flow |
| Camera | 320x240 downward JPEG |
| Landing Pad | Relative position (when visible) |

## Platform Support

| Mode | Ubuntu | Arch | macOS | Windows | WSL2 |
|------|--------|------|-------|---------|------|
| Standalone | ✅ | ✅ | ✅ | ✅ | ✅ |
| PyBullet+ROS | ✅ | ⚠️ | ❌ | ❌ | ✅ |
| Gazebo+ROS | ✅ | ⚠️ | ❌ | ❌ | ✅ |