# 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         │  │
│  │  Configuration from config.py    │  │
│  └──────────────────────────────────┘  │
└────────────────────────────────────────┘
```

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

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

Data flow:
- RoverController publishes position → Bridge sends to Simulator
- Simulator moves rover visually AND sends back telemetry
- DroneController receives telemetry, publishes commands
- Bridge forwards commands to Simulator

### 3. Gazebo + ROS 2 Mode (Two Terminals, Linux/WSL2)

```
Terminal 1                          Terminal 2
┌───────────────────────────┐      ┌──────────────────────────┐
│ ros2 launch ... .launch.py│      │      run_gazebo.py       │
│  ┌─────────────────────┐  │      │  ┌────────────────────┐  │
│  │ Gazebo (ign gazebo) │  │      │  │ GazeboBridge       │  │
│  │  - Drone (vel ctrl) │  │◄────►│  │ DroneController    │  │
│  │  - Rover (vel ctrl) │  │ ROS  │  │ RoverController    │  │
│  ├─────────────────────┤  │      │  └────────────────────┘  │
│  │ ros_gz_bridge       │  │      └──────────────────────────┘
│  └─────────────────────┘  │
└───────────────────────────┘
```

Data flow:
- RoverController publishes to `/rover/cmd_vel` → Gazebo moves rover
- Gazebo publishes odometry → GazeboBridge converts to telemetry
- DroneController receives telemetry, publishes to `/cmd_vel`
- GazeboBridge forwards to `/drone/cmd_vel` → Gazebo moves drone

### 4. ArduPilot SITL + Gazebo Mode (Three Terminals, Linux/WSL2)

```
Terminal 1           Terminal 2              Terminal 3
┌──────────────┐    ┌─────────────────┐     ┌────────────────────────┐
│ Gazebo +     │    │ ArduPilot SITL  │     │   run_ardupilot.py     │
│ ArduPilot    │◄──►│ sim_vehicle.py  │     │  ┌──────────────────┐  │
│ Plugin       │JSON│  + MAVProxy     │◄───►│  │ MAVLinkBridge    │  │
│              │    │                 │ UDP │  │ DroneController  │  │
│ ardupilot_   │    │ Flight Control  │     │  │ RoverController  │  │
│ drone.sdf    │    │ + GCS           │     │  └──────────────────┘  │
└──────────────┘    └─────────────────┘     └────────────────────────┘
```

Data flow:
- ArduPilot SITL sends motor commands → Gazebo plugin controls drone
- Gazebo plugin sends sensor data → ArduPilot SITL for state estimation
- MAVProxy outputs telemetry → MAVLinkBridge converts to ROS telemetry
- DroneController receives telemetry, publishes velocity commands
- MAVLinkBridge sends MAVLink commands → ArduPilot SITL executes

Key differences from simple Gazebo mode:
- Full ArduPilot flight controller (EKF, stabilization, failsafes)
- Real MAVLink protocol for commands and telemetry
- Support for all ArduPilot flight modes (GUIDED, LAND, etc.)
- Arming checks and safety features
- Compatible with ground control stations (QGroundControl, Mission Planner)

## Components

| File | Description |
|------|-------------|
| `config.py` | Central configuration (positions, physics, gains) |
| `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 |
| `run_ardupilot.py` | **ArduPilot SITL** + MAVLink bridge |
| `mavlink_bridge.py` | MAVLink ↔ ROS 2 bridge |
| `drone_controller.py` | **Your landing algorithm** |
| `rover_controller.py` | Moving landing pad |
| `ros_bridge.py` | ROS-UDP bridge (used by run_bridge.py) |
| `gazebo_bridge.py` | Gazebo-ROS bridge (used by run_gazebo.py) |
| `gazebo/launch/drone_landing.launch.py` | ROS 2 launch file for Gazebo |
| `gazebo/launch/ardupilot_drone.launch.py` | ROS 2 launch file for ArduPilot |
| `gazebo/worlds/drone_landing.sdf` | Gazebo world with simple velocity control |
| `gazebo/worlds/ardupilot_drone.sdf` | Gazebo world with ArduPilot plugin |

## ROS 2 Topics

| Topic | Type | Description |
|-------|------|-------------|
| `/cmd_vel` | `Twist` | Drone commands from DroneController |
| `/drone/cmd_vel` | `Twist` | Drone commands to Gazebo |
| `/drone/telemetry` | `String` | GPS-denied sensor data (JSON) |
| `/rover/cmd_vel` | `Twist` | Rover velocity to simulator |
| `/rover/telemetry` | `String` | Rover position (JSON) |

## Network Configuration

All components default to `0.0.0.0` for network accessibility.

### Remote Setup (PyBullet mode)

**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 (JSON) |
| 5556 | Simulator → Bridge | Telemetry (JSON) |

## GPS-Denied Sensors

All modes provide the same sensor data:

| Sensor | Data |
|--------|------|
| **IMU** | Orientation (roll, pitch, yaw), angular velocity |
| **Altimeter** | Altitude above ground, vertical velocity |
| **Velocity** | Estimated velocity (x, y, z) |
| **Camera** | 320x240 downward JPEG (base64) |
| **Landing Pad** | Relative position (x, y, distance) when visible |

## Configuration (config.py)

| Section | Parameters |
|---------|------------|
| `DRONE` | mass, size, color, start_position, thrust/torque scales |
| `ROVER` | size, color, start_position, default_pattern, default_speed |
| `CAMERA` | width, height, fov, jpeg_quality |
| `PHYSICS` | gravity, timestep, telemetry_rate |
| `CONTROLLER` | Kp_z, Kd_z, Kp_xy, Kd_xy, rate |
| `LANDING` | success_distance, success_velocity, height_threshold |
| `NETWORK` | host, command_port, telemetry_port |

## Platform Support

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