# Architecture Overview

GPS-denied drone landing simulation with camera vision.

## System Diagram

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

## Components

### Simulators

| Component | Description |
|-----------|-------------|
| **PyBullet** (`simulation_host.py`) | Standalone physics, UDP networking, camera rendering |
| **Gazebo** | Full robotics simulator, native ROS 2 integration, camera sensor |

### Bridges

| Component | Description |
|-----------|-------------|
| **ros_bridge.py** | Connects PyBullet ↔ ROS 2 via UDP |
| **gazebo_bridge.py** | Connects Gazebo ↔ ROS 2, provides same interface |

### Controllers

| Component | Description |
|-----------|-------------|
| **controllers.py** | Runs drone + rover controllers together |
| **drone_controller.py** | GPS-denied landing logic |
| **rover_controller.py** | Moving landing pad patterns |

## ROS Topics

| Topic | Type | Publisher | Subscriber |
|-------|------|-----------|------------|
| `/cmd_vel` | `Twist` | DroneController | Bridge |
| `/drone/telemetry` | `String` | Bridge | DroneController |
| `/rover/telemetry` | `String` | RoverController | DroneController |
| `/rover/cmd_vel` | `Twist` | RoverController | (internal) |
| `/rover/position` | `Point` | RoverController | (debug) |

## GPS-Denied Sensor Flow

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

## Camera System

Both simulators provide a downward-facing camera:

| Property | Value |
|----------|-------|
| Resolution | 320 x 240 |
| FOV | 60 degrees |
| Format | Base64 JPEG |
| Update Rate | ~5 Hz |
| Direction | Downward |

## Data Flow

### PyBullet Mode
```
DroneController → /cmd_vel → ros_bridge → UDP:5555 → simulation_host
simulation_host → UDP:5556 → ros_bridge → /drone/telemetry → DroneController
```

### Gazebo Mode
```
DroneController → /cmd_vel → gazebo_bridge → /drone/cmd_vel → Gazebo
Gazebo → /model/drone/odometry → gazebo_bridge → /drone/telemetry → DroneController
Gazebo → /drone/camera → gazebo_bridge → (encoded in telemetry)
```

## UDP Protocol

| Port | Direction | Content |
|------|-----------|---------|
| 5555 | Bridge → Simulator | Command JSON |
| 5556 | Simulator → Bridge | Telemetry JSON (includes camera image) |