# PyBullet Simulation Guide

Running the GPS-denied drone simulation with PyBullet physics engine.

## Standalone Mode (Single Terminal - Any Platform)

No ROS 2 required! Works on Windows, macOS, and Linux:

```bash
source activate.sh  # Linux/macOS
. .\activate.ps1    # Windows

python standalone_simulation.py --pattern circular --speed 0.3
```

### Options

```bash
python standalone_simulation.py --help

Options:
  --pattern, -p   stationary, linear, circular, square
  --speed, -s     Rover speed in m/s (default: 0.5)
  --amplitude, -a Movement amplitude in meters (default: 2.0)
```

---

## ROS 2 Mode (Two Terminals)

For distributed or remote simulation with ROS 2:

**Terminal 1 - Simulator:**
```bash
source activate.sh
python simulation_host.py
```

**Terminal 2 - Controllers:**
```bash
source activate.sh
python run_bridge.py --pattern circular --speed 0.3
```

### How It Works

1. `simulation_host.py` runs PyBullet physics and listens on UDP port 5555
2. `run_bridge.py` starts:
   - `ROS2SimulatorBridge` - connects ROS topics to UDP
   - `DroneController` - your landing algorithm
   - `RoverController` - moves the landing pad

The rover position is sent to the simulator, so both drone AND rover move!

### Remote Setup

Run simulator on one machine, controllers on another:

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

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

---

## Configuration

All parameters are configurable in `config.py`:

```python
DRONE = {
    "mass": 1.0,
    "start_position": (0.0, 0.0, 5.0),
    "thrust_scale": 15.0,
    ...
}

ROVER = {
    "start_position": (0.0, 0.0, 0.15),
    "default_pattern": "circular",
    "default_speed": 0.5,
    ...
}

CONTROLLER = {
    "Kp_z": 0.5,
    "Kd_z": 0.3,
    ...
}
```

---

## Simulation Parameters

| Parameter | Value |
|-----------|-------|
| Physics Rate | 240 Hz |
| Telemetry Rate | 24 Hz |
| Drone Mass | 1.0 kg (configurable) |
| Rover Mass | Static (kinematic) |
| UDP Port | 5555 (commands), 5556 (telemetry) |

## GPS-Denied Sensors

| Sensor | Description |
|--------|-------------|
| **IMU** | Orientation (roll, pitch, yaw), angular velocity |
| **Altimeter** | Altitude above ground, vertical velocity |
| **Velocity** | Estimated horizontal velocity (x, y, z) |
| **Camera** | 320x240 downward-facing JPEG image |
| **Landing Pad** | Vision-based relative position when in camera FOV |

## Troubleshooting

### "Cannot connect to X server"

PyBullet GUI requires a display:
```bash
# Use virtual display
xvfb-run python standalone_simulation.py

# Or use X11 forwarding
ssh -X user@host
```

### Drone flies erratically

Reduce control gains in `config.py`:
```python
CONTROLLER = {
    "Kp_z": 0.3,
    "Kd_z": 0.2,
    "Kp_xy": 0.2,
    "Kd_xy": 0.1,
}
```

### Camera image not appearing

Install Pillow:
```bash
pip install pillow numpy
```

### Rover not moving (ROS 2 mode)

Ensure `run_bridge.py` is used (not `ros_bridge.py` directly).
The rover controller must be running to send position updates.

### WSL2 GUI issues

Set display scaling:
```bash
export GDK_DPI_SCALE=1.0
export QT_SCALE_FACTOR=1.0
python standalone_simulation.py
```