# Architecture Overview

GPS-denied drone landing simulation with multiple operation modes.

## Operation Modes

### Standalone Mode (Windows/Simple)

All-in-one simulation - no ROS 2 or external dependencies:

```
┌────────────────────────────────────────┐
│      standalone_simulation.py          │
│  ┌──────────────────────────────────┐  │
│  │  PyBullet Physics Engine         │  │
│  │  ┌────────┐  ┌────────────────┐  │  │
│  │  │ Drone  │  │ Landing Pad    │  │  │
│  │  └────────┘  └────────────────┘  │  │
│  ├──────────────────────────────────┤  │
│  │  Built-in Controller             │  │
│  │  • Landing algorithm             │  │
│  │  • Rover movement patterns       │  │
│  └──────────────────────────────────┘  │
└────────────────────────────────────────┘
```

### Full Mode (Linux + ROS 2)

Modular architecture for development and testing:

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         Simulation System                               │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────────┐                    ┌──────────────────────────┐   │
│  │ simulation_host  │◄── UDP:5555 ──────►│    ros_bridge.py         │   │
│  │   (PyBullet)     │                    │    (UDP ↔ ROS Bridge)    │   │
│  └──────────────────┘                    └────────────┬─────────────┘   │
│          OR                                           │                 │
│  ┌──────────────────┐                    ┌────────────┴─────────────┐   │
│  │     Gazebo       │◄── ROS Topics ────►│    gazebo_bridge.py      │   │
│  │   (Linux only)   │                    │    (Gazebo ↔ ROS Bridge) │   │
│  └──────────────────┘                    └────────────┬─────────────┘   │
│                                                       │                 │
│                                          ┌────────────▼─────────────┐   │
│                                          │    controllers.py        │   │
│                                          │  ┌─────────────────────┐ │   │
│                                          │  │  DroneController    │ │   │
│                                          │  │  RoverController    │ │   │
│                                          │  └─────────────────────┘ │   │
│                                          └──────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
```

## Components

### Standalone

| Component | Description |
|-----------|-------------|
| **standalone_simulation.py** | Complete simulation with built-in controller |

### Full Mode

| Component | Description |
|-----------|-------------|
| **PyBullet** (`simulation_host.py`) | Physics engine, UDP networking, camera |
| **Gazebo** | Full robotics simulator (Linux only) |
| **ros_bridge.py** | Connects PyBullet ↔ ROS 2 via UDP |
| **gazebo_bridge.py** | Connects Gazebo ↔ ROS 2 |
| **controllers.py** | Runs drone + rover controllers |
| **drone_controller.py** | GPS-denied landing logic |
| **rover_controller.py** | Moving landing pad patterns |

## ROS Topics (Full Mode)

| Topic | Type | Publisher | Subscriber |
|-------|------|-----------|------------|
| `/cmd_vel` | `Twist` | DroneController | Bridge |
| `/drone/telemetry` | `String` | Bridge | DroneController |
| `/rover/telemetry` | `String` | RoverController | DroneController |

## GPS-Denied Sensor Flow

```
Simulator                Bridge                  DroneController
    │                       │                          │
    │  Render Camera        │                          │
    │  Compute Physics      │                          │
    │──────────────────────►│                          │
    │                       │  GPS-Denied Sensors:     │
    │                       │  - IMU                   │
    │                       │  - Altimeter             │
    │                       │  - Velocity              │
    │                       │  - Camera Image          │
    │                       │  - Landing Pad Detection │
    │                       │─────────────────────────►│
    │                       │      /cmd_vel            │
    │◄──────────────────────│◄─────────────────────────│
```

## Platform Support

| Mode | Windows | Linux | macOS |
|------|---------|-------|-------|
| Standalone | ✅ | ✅ | ✅ |
| Full (ROS 2) | ⚠️ | ✅ | ⚠️ |
| Gazebo | ❌ | ✅ | ❌ |

## UDP Protocol (Full Mode)

| Port | Direction | Content |
|------|-----------|---------|
| 5555 | Bridge → Simulator | Command JSON |
| 5556 | Simulator → Bridge | Telemetry JSON |