Initial Attempt

docs/pybullet.md

@@ -0,0 +1,140 @@
+# PyBullet Simulation
+
+Running the GPS-denied drone simulation with PyBullet.
+
+## Quick Start
+
+**Terminal 1 - Simulator:**
+```bash
+source activate.sh
+python simulation_host.py
+```
+
+**Terminal 2 - ROS Bridge:**
+```bash
+source activate.sh
+python ros_bridge.py
+```
+
+**Terminal 3 - Controllers:**
+```bash
+source activate.sh
+python controllers.py --pattern circular --speed 0.3
+```
+
+## Remote Setup
+
+Run simulator on one machine, controllers on another.
+
+**Machine 1 (with display):**
+```bash
+python simulation_host.py
+```
+
+**Machine 2 (headless):**
+```bash
+source activate.sh
+python ros_bridge.py --host <MACHINE_1_IP>
+python controllers.py
+```
+
+## Simulation Parameters
+
+| Parameter | Value |
+|-----------|-------|
+| Physics Rate | 240 Hz |
+| Telemetry Rate | 24 Hz |
+| Drone Mass | 1.0 kg |
+| Gravity | -9.81 m/s² |
+
+## GPS-Denied Sensors
+
+The simulator provides:
+
+| Sensor | Description |
+|--------|-------------|
+| IMU | Orientation (roll, pitch, yaw), angular velocity |
+| Altimeter | Barometric altitude, vertical velocity |
+| Velocity | Optical flow estimate (x, y, z) |
+| Camera | 320x240 downward JPEG image |
+| Landing Pad | Vision-based relative position (60° FOV, 10m range) |
+
+## Camera System
+
+PyBullet renders a camera image from the drone's perspective:
+
+| Property | Value |
+|----------|-------|
+| Resolution | 320 x 240 |
+| FOV | 60 degrees |
+| Format | Base64 encoded JPEG |
+| Update Rate | ~5 Hz |
+| Direction | Downward-facing |
+
+The image is included in telemetry as `camera.image`.
+
+## World Setup
+
+| Object | Position | Description |
+|--------|----------|-------------|
+| Ground | z = 0 | Infinite plane |
+| Rover | (0, 0, 0.15) | 1m × 1m landing pad |
+| Drone | (0, 0, 5) | Starting position |
+
+## UDP Communication
+
+| Port | Direction | Data |
+|------|-----------|------|
+| 5555 | Bridge → Sim | Commands (JSON) |
+| 5556 | Sim → Bridge | Telemetry (JSON with camera) |
+
+## ROS Bridge Options
+
+```bash
+python ros_bridge.py --help
+
+Options:
+  --host, -H    Simulator IP (default: 127.0.0.1)
+  --port, -p    Simulator port (default: 5555)
+```
+
+## Building Executable
+
+Create standalone executable:
+
+```bash
+source activate.sh
+python build_exe.py
+```
+
+Output: `dist/simulation_host` (or `.exe` on Windows)
+
+## Troubleshooting
+
+### "Cannot connect to X server"
+
+PyBullet requires a display:
+- Run on machine with monitor
+- Use X11 forwarding: `ssh -X user@host`
+- Virtual display: `xvfb-run python simulation_host.py`
+
+### Drone flies erratically
+
+Reduce control gains:
+```python
+Kp = 0.3
+Kd = 0.2
+```
+
+### No telemetry received
+
+1. Check simulator is running
+2. Verify firewall allows UDP 5555-5556
+3. Check IP address in ros_bridge.py
+
+### Camera image not appearing
+
+Ensure PIL/Pillow is installed:
+```bash
+pip install pillow
+```