enhance installation guides, add environment setup, and expand troubleshooting for all platforms.

docs/ardupilot.md

@@ -1,13 +1,23 @@
 # ArduPilot + Gazebo Simulation
 
+## Prerequisites
+
+Before running, ensure your environment is set up:
+
+```bash
+source activate.sh
+# or
+source ~/.ardupilot_env && source ~/venv-ardupilot/bin/activate
+```
+
 ## Quick Start (2 Terminals)
 
-**Terminal 1:**
+**Terminal 1 - Start Gazebo:**
 ```bash
 ./scripts/run_ardupilot_sim.sh runway
 ```
 
-**Terminal 2:**
+**Terminal 2 - Start Controller:**
 ```bash
 ./scripts/run_ardupilot_controller.sh
 ```
@@ -21,33 +31,41 @@
 └─────────────────┘     └─────────────────┘     └─────────────────┘
 ```
 
+**Communication:**
+- Gazebo ↔ SITL: JSON sensor data over UDP (port 9002)
+- SITL ↔ Your Code: MAVLink over TCP (port 5760)
+
 ## World Options
 
 ```bash
-./scripts/run_ardupilot_sim.sh runway     # Default
-./scripts/run_ardupilot_sim.sh warehouse  # Indoor
-./scripts/run_ardupilot_sim.sh zephyr     # Fixed-wing
+./scripts/run_ardupilot_sim.sh runway     # Default (outdoor runway)
+./scripts/run_ardupilot_sim.sh warehouse  # Indoor warehouse
+./scripts/run_ardupilot_sim.sh gimbal     # With camera gimbal
+./scripts/run_ardupilot_sim.sh zephyr     # Fixed-wing aircraft
+./scripts/run_ardupilot_sim.sh custom     # Your custom world
+./scripts/run_ardupilot_sim.sh my_world   # gazebo/worlds/my_world.sdf
 ```
 
 ## GPS-Denied Mode
 
-The simulation runs in GPS-denied mode by default.
+The simulation runs in GPS-denied mode by default. The controller disables GPS checks and uses visual navigation.
 
 For manual debugging with MAVProxy:
 ```bash
 sim_vehicle.py -v ArduCopter -f gazebo-iris --model JSON --console
 
-# In MAVProxy:
+# In MAVProxy console:
 param set ARMING_CHECK 0
 mode stabilize
 arm throttle force
+rc 3 1500  # Throttle up
 ```
 
 ## Controller Options
 
 ```bash
 ./scripts/run_ardupilot_controller.sh                 # Auto takeoff
-./scripts/run_ardupilot_controller.sh --no-takeoff    # Manual
+./scripts/run_ardupilot_controller.sh --no-takeoff    # Manual control
 ./scripts/run_ardupilot_controller.sh -a 10           # 10m altitude
 ```
 
@@ -55,18 +73,130 @@ arm throttle force
 
 | File | Purpose |
 |------|---------|
-| `scripts/run_ardupilot_sim.sh` | Gazebo + GPU detection |
-| `scripts/run_ardupilot_controller.sh` | SITL + Controller |
-| `scripts/run_ardupilot.py` | MAVLink interface |
-| `src/drone_controller.py` | Your algorithm |
+| `scripts/run_ardupilot_sim.sh` | Gazebo launcher with GPU detection |
+| `scripts/run_ardupilot_controller.sh` | SITL + Controller launcher |
+| `scripts/run_ardupilot.py` | MAVLink interface script |
+| `src/drone_controller.py` | Your landing algorithm |
+
+## Environment Variables
+
+The scripts automatically set these, but for manual runs:
+
+```bash
+# ArduPilot tools
+export PATH=$PATH:~/ardupilot/Tools/autotest
+
+# ArduPilot venv (has empy, pymavlink, etc.)
+source ~/venv-ardupilot/bin/activate
+
+# Gazebo plugin paths
+export GZ_SIM_SYSTEM_PLUGIN_PATH=~/ardupilot_gazebo/build:$GZ_SIM_SYSTEM_PLUGIN_PATH
+export GZ_SIM_RESOURCE_PATH=~/ardupilot_gazebo/models:~/ardupilot_gazebo/worlds:$GZ_SIM_RESOURCE_PATH
+```
 
 ## Troubleshooting
 
-### "No JSON sensor message"
-Start Gazebo (Terminal 1) before the controller.
+### "No JSON sensor message" or "No heartbeat"
 
-### Drone doesn't respond
-Check mode is GUIDED in MAVProxy.
+**Cause:** Gazebo isn't running or ArduPilot plugin isn't loaded.
 
-### Simulation laggy
-Check GPU: `glxinfo | grep "OpenGL renderer"`
+**Fix:**
+1. Start Gazebo first (Terminal 1)
+2. Wait for world to fully load
+3. Then start controller (Terminal 2)
+
+### "sim_vehicle.py not found"
+
+**Cause:** ArduPilot tools not in PATH.
+
+**Fix:**
+```bash
+source ~/.ardupilot_env
+# or
+export PATH=$PATH:~/ardupilot/Tools/autotest
+```
+
+### "empy not found" during waf build
+
+**Cause:** Wrong Python environment.
+
+**Fix:**
+```bash
+source ~/venv-ardupilot/bin/activate
+pip install empy==3.3.4
+cd ~/ardupilot
+./waf configure --board sitl
+./waf copter
+```
+
+### Drone doesn't respond to commands
+
+**Possible causes:**
+1. Not in GUIDED mode - check MAVProxy: `mode`
+2. Not armed - run: `arm throttle force`
+3. Pre-arm checks failing - run: `param set ARMING_CHECK 0`
+
+### Drone immediately crashes in Gazebo
+
+**Cause:** Usually a physics/plugin issue.
+
+**Fix:**
+```bash
+# Rebuild the ArduPilot Gazebo plugin
+cd ~/ardupilot_gazebo/build
+cmake .. -DCMAKE_BUILD_TYPE=Release
+make -j4
+```
+
+### Simulation is laggy
+
+**Cause:** Software rendering or GPU not detected.
+
+**Check:**
+```bash
+glxinfo | grep "OpenGL renderer"
+```
+
+Should show your GPU name, not "llvmpipe" or "software".
+
+**Fix for WSL:**
+- Install NVIDIA drivers for WSL: https://developer.nvidia.com/cuda/wsl
+- Ensure WSLg is enabled (Windows 11)
+
+### MAVProxy console not opening
+
+**Cause:** Missing `--console` flag or display issues.
+
+**Fix:**
+```bash
+# Run directly
+sim_vehicle.py -v ArduCopter -f gazebo-iris --model JSON --console --map
+
+# If display errors:
+export DISPLAY=:0  # Linux/WSL with X server
+```
+
+## Advanced: Custom Takeoff
+
+To customize the takeoff behavior, edit `scripts/run_ardupilot.py`:
+
+```python
+# Change altitude
+TAKEOFF_ALTITUDE = 15  # meters
+
+# Change timeout
+CONNECTION_TIMEOUT = 60  # seconds
+```
+
+## Logs
+
+ArduPilot logs are saved to:
+```
+~/ardupilot/logs/
+~/ardupilot/build/sitl/logs/
+```
+
+View with:
+```bash
+mavlogdump.py --types GPS,ATT ~/ardupilot/logs/LASTLOG.BIN
+```