px4xplane

PX4-XPlane

PX4-XPlane connects PX4 SITL to X-Plane. It sends PX4 actuator commands to writable X-Plane datarefs and returns simulated IMU, GPS, barometer, magnetometer, airspeed, and ground-truth data.

The current package is v4.2.1 with Windows, Linux, and macOS builds. It includes examples for Cessna 172, TB2, Ehang 184, Alia 250 and QuadTailsitter. The QuadTailsitter example needs its matching owner-provided model.

Latest Video

New v4 walkthrough videos are coming soon. The current thumbnail links to the project video archive and playlist; future videos will be added there.

Quick Start

1. Install X-Plane 11 or 12. Use the official X-Plane download and installation guide.

2. Install or update PX4 SITL. Follow the official PX4 development environment setup for your OS, WSL2, container, or remote Linux machine, then the PX4 X-Plane simulation guide. Use official PX4/PX4-Autopilot main for normal runs.

3. Download the latest px4xplane package for your OS from Releases.

4. Close X-Plane. If upgrading, back up custom configs and remove the existing px4xplane plugin folder; do not merge old and new package files. Extract the archive and copy its complete px4xplane folder into X-Plane’s Resources/plugins folder, for example X-Plane 12/Resources/plugins/px4xplane.

5. Copy any packaged X-Plane aircraft folders you want to test into an X-Plane aircraft directory, then start X-Plane and load the matching aircraft.

6. In X-Plane, choose Plugins > PX4 X-Plane > Airframes > ... and select the matching airframe, then click Plugins > PX4 X-Plane > Connect to SITL.

7. Start PX4 SITL from your official PX4 checkout:

cd ~/PX4-Autopilot
make px4_sitl_default xplane_alia250

Starting PX4 first can also work, but starting Connect to SITL in X-Plane first gives visible connection status. The first PX4 build can take longer than the plugin’s 60-second wait window; if the plugin times out, click Connect to SITL again after PX4 is running.

Available PX4 targets include xplane_alia250, xplane_cessna172, xplane_tb2, xplane_ehang184, and xplane_qtailsitter. See the official PX4 X-Plane simulation page for the current target list, running notes, and the custom-airframe integration path.

Optional Guided Setup

For guided host detection, checkout setup and airframe selection, run:

tmp=$(mktemp) && curl -fsSL -o "$tmp" https://raw.githubusercontent.com/alireza787b/px4xplane/master/setup/setup_px4_sitl.sh && bash "$tmp"

After installing the command, start future sessions with px4xplane. The launcher automatically prepares official PX4 main, reuses existing checkouts and preserves saved tuning in separate per-airframe state directories. Use --px4-path ~/PX4-Autopilot to select an existing checkout explicitly.

See the guided launcher guide for checkout safety, networking and explicit parameter resets, or Troubleshooting for connection problems.

Network Notes

PX4 connects to the px4xplane plugin on TCP port 4560. QGroundControl (QGC) uses a separate MAVLink connection, normally UDP 14550. A configured target address does not confirm that QGC is receiving telemetry.

If PX4 SITL and X-Plane run on the same Linux or macOS machine, the default localhost setup is normally enough.

If PX4 runs in WSL2, Docker, or another computer, set PX4_SIM_HOSTNAME in the PX4/SITL shell to the IP address of the machine running X-Plane before starting PX4:

export PX4_SIM_HOSTNAME=<xplane-host-ip>
make px4_sitl_default xplane_alia250

For WSL2, use localhost in mirrored networking mode and the current Windows host gateway in NAT-compatible modes:

if [[ "$(wslinfo --networking-mode 2>/dev/null)" == "mirrored" ]]; then
  export PX4_SIM_HOSTNAME=127.0.0.1
else
  export PX4_SIM_HOSTNAME=$(ip route | awk '/default/ {print $3; exit}')
fi

Run that export before the normal PX4 make px4_sitl_default xplane_* command in the same terminal session.

Also allow inbound TCP 4560 on the X-Plane host firewall. More detail is in the network setup guide. With the launcher, use --qgc-host <qgc-host-ip> when QGC is on another host. Direct MAVLink is the default; MAVLink Router is optional, not installed automatically.

Developer Validation

Normal launches use official PX4 without pending patches. To test only the open TECS altitude-reference proposal #27670:

px4xplane --validation

Custom PX4 repo, branch and checkout overrides remain available. See developer validation for details.

Status

PX4 X-Plane SITL support is merged in PX4-Autopilot PR #22493. Use official PX4/PX4-Autopilot main for normal SITL runs.

v4.2.1 uses bounded HIL sensor scheduling for uneven or low X-Plane frame rates. The plugin establishes actuator-feedback flow control, keeps at most one primary sample outstanding, and splits long frame intervals into bounded IMU substeps while preserving elapsed simulation time. It disconnects on a feedback, timestamp, or backlog fault instead of silently corrupting estimator timing. Legacy configs that explicitly selected async now migrate to the safe mode; unbounded developer comparisons require the explicit async_unsafe value. Existing airframe mappings and PX4 parameters are unchanged.

Common Paths

I want to…	Start here
Install and fly an included airframe	Quick Start and the matching flight-test card
Use guided PX4 setup	Guided launcher guide
Run PX4 in WSL2, Docker, or another computer	Network setup
Fix setup or connection errors	Troubleshooting
Create or edit a custom airframe mapping	Custom airframe guide
Use the browser config editor	Config editor guide
Build the plugin from source	Build guide
Work on the project or release process	Developer guide
See all packaged docs	Documentation index

Custom Airframes

The included examples are ready-to-test PX4 targets, not a hard vehicle-class limit. A new X-Plane model can be integrated when PX4 has a matching SITL-capable control path and px4xplane can map the needed actuator outputs to writable X-Plane datarefs.

Use the custom airframe guide for the config editor, schema, camera presets, actuator mappings, and validation workflow.

Maintenance

The launcher includes maintenance flags for syncing the selected PX4 checkout, resetting saved IP/config choices, and repairing the setup. See the documentation index for the operator and developer workflows.

License

MIT. See LICENSE.