Files
PX4-Autopilot/docs/uk/simulation/px4_sitl_prebuilt_packages.md
T

20 KiB

Pre-built SITL Packages

Pre-built packages let you run PX4 SITL simulation without setting up a build environment.

This is very useful if you don't need to modify PX4 itself. For example, if you want to write drone apps using MAVSDK or ROS 2, or you just want to fly with PX4.

:::tip See PX4 Simulation QuickStart for a one-line instruction to run the SIH package in a container. :::

What's Available

Two simulators are packaged, each available as a .deb package (Ubuntu) or a Docker container (any OS):

Симулятор Format Package / Image Розмір
SIH .deb px4 ~10 MB
container px4io/px4-sitl ~100 MB
Gazebo Harmonic .deb px4-gazebo ~30 MB
container px4io/px4-sitl-gazebo ~2 GB

SIH is a lightweight, headless simulator built into PX4 with no external dependencies. Gazebo provides full 3D simulation with camera, LiDAR, and custom worlds. Sizes are approximate and vary between releases.

For help choosing between simulators, see the simulator comparison table.

Versions and Releases

Packages and images are versioned to match PX4 tags (e.g. v1.17.0, v1.17.0~beta1). .deb packages are built for Ubuntu 22.04 (Jammy) and 24.04 (Noble), on both amd64 and arm64. Container images support amd64 and arm64. Stable releases and pre-releases are published on the PX4 Releases page.

.deb Packages (Ubuntu)

Download the .deb file for your Ubuntu version and architecture from the PX4 Releases page, then install as shown below. After installation the binary is added to the default Ubuntu system paths, and can be run from anywhere.

px4 (SIH)

No extra repositories are required:

sudo apt install ./px4_*.deb

px4-gazebo (Gazebo Harmonic)

The package depends on Gazebo Harmonic runtime libraries from the OSRF repository. Add the repository first, then install:

# Add OSRF Gazebo repository (one-time setup)
sudo curl -fsSL https://packages.osrfoundation.org/gazebo.gpg \
  -o /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] \
  http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null
sudo apt update

# Install (resolves Gazebo dependencies automatically)
sudo apt install ./px4-gazebo_*.deb

Uninstalling

sudo apt remove px4          # SIH package
sudo apt remove px4-gazebo   # Gazebo package

Container Images

Container images are built using the same .deb packages described above, packaged into minimal Docker images. They are published to Docker Hub on every tagged release. You will need to install Docker.

Зображення Симулятор
px4io/px4-sitl:<tag> SIH (headless)
px4io/px4-sitl-gazebo:<tag> Gazebo Harmonic

Tags follow PX4 versions (e.g. v1.17.0).

Запуск

On Docker Desktop (macOS/Windows), the containers automatically send MAVLink to the host using host.docker.internal. Run QGroundControl, MAVSDK or Hawkeye on the host without publishing their listening ports with Docker -p.

# SIH
docker run --rm -it px4io/px4-sitl:latest

# Gazebo (headless)
docker run --rm -it -e HEADLESS=1 px4io/px4-sitl-gazebo:latest

For a visible Gazebo window on Linux or Windows/WSLg, use the Gazebo Container GUI instructions. On macOS, run Gazebo headlessly or use a Linux desktop VM.

Pass environment variables with -e:

docker run --rm -it \
  -e PX4_SIM_MODEL=sihsim_airplane \
  px4io/px4-sitl:latest

The default destination ports are:

Порт Протокол Used by
14550 UDP QGroundControl
14540 UDP MAVSDK / offboard API
8888 UDP uXRCE-DDS agent (ROS 2)
7447 TCP Zenoh router (ROS 2, when Zenoh is selected)
19410 UDP Hawkeye SIH visualisation

On Linux, add --network host:

docker run --rm -it --network host px4io/px4-sitl:latest

Alternatively, use bridged networking with --add-host=host.docker.internal:host-gateway. When that hostname is unavailable, PX4 retains its localhost defaults. The runtime images also target the host for DDS and Zenoh; the ROS development images keep the middleware inside the container.

Hawkeye Visualisation

Both px4io/px4-sitl and px4io/px4-sitl-ros2 automatically stream SIH state to the host on UDP 19410. After starting PX4, launch Hawkeye on the host:

hawkeye -udp 19410

Use the platform-specific networking options above; no manual MAVLink stream commands or ROS bridge are needed. Do not publish port 19410 with Docker -p, because Hawkeye must bind that port on the host.

ROS 2 Development Images

The ROS development variants add ROS 2 Jazzy, Micro XRCE-DDS Agent v2.4.3, the rmw_zenoh_cpp middleware and router, px4_msgs, and the PX4 ROS 2 Interface Library, including its examples and development tools. They also include PX4 source-build dependencies for SITL, without installing the NuttX toolchain. They support amd64 and arm64, with the same version tags as the runtime images. The ROS message definitions match the packaged PX4 firmware.

Зображення Симулятор
px4io/px4-sitl-ros2:<tag> SIH, without Gazebo dependencies
px4io/px4-sitl-gazebo-ros2:<tag> Gazebo Harmonic

Unlike the runtime images, these open a shell with ROS and the workspace at /opt/px4_ros2 already sourced. PX4 and the DDS Agent (or Zenoh router) are started explicitly and communicate inside the same container.

# Terminal 1: open the development environment and start the Agent.
docker run --rm -it --name px4-ros2 \
  -e ROS_DOMAIN_ID=83 \
  -v "$PWD:/workspace" px4io/px4-sitl-ros2:latest
MicroXRCEAgent udp4 -p 8888

# Terminal 2: start the packaged SIH simulator.
docker exec -it px4-ros2 /usr/local/bin/ros2-entrypoint.sh px4

# Terminal 3: inspect the ROS topics.
docker exec -it px4-ros2 /usr/local/bin/ros2-entrypoint.sh ros2 topic list

To use Zenoh instead, start ros2 run rmw_zenoh_cpp rmw_zenohd in terminal 1, run PX4 with env PX4_ROS2_MIDDLEWARE=zenoh px4, and set RMW_IMPLEMENTATION=rmw_zenoh_cpp for the ROS commands (for example docker exec -it -e RMW_IMPLEMENTATION=rmw_zenoh_cpp px4-ros2 ...).

For headless Gazebo, use px4io/px4-sitl-gazebo-ros2 and replace px4 with env HEADLESS=1 px4-gazebo. For a visible window, configure the container's display using Gazebo Container GUI and leave HEADLESS unset. Host ROS nodes require additional DDS networking configuration; the example keeps ROS, the Agent and PX4 together and does not require host networking.

When testing modified PX4 firmware, rebuild the ROS workspace against its message definitions rather than using the bundled library. Use --entrypoint /bin/bash and source /opt/ros/jazzy/setup.bash to start without the bundled workspace. For source builds and selecting an interface-library commit, see Testing A PX4 Checkout With ROS. The standalone ghcr.io/px4/px4-dev-ros2 toolchain provides Ubuntu 22.04/ROS Humble (main-humble) and Ubuntu 24.04/ROS Jazzy (main-jazzy) variants for amd64 and arm64, without bundled source checkouts, firmware or a compiled workspace. It is also available on Docker Hub as px4io/px4-dev-ros2, with matching distro-qualified tags in both registries. Release tags retain the Git tag and ROS suffix, for example v1.18.0-humble and v1.18.0-jazzy; release publication does not move the manually published main-* tags. Humble support is limited to this standalone toolchain; the packaged SIH/Gazebo ROS images above remain Jazzy-only. ROS integration CI uses this toolchain, builds PX4 from the pull request, and regenerates messages from that checkout.

Go-To Example

With the Agent and PX4 running as above, start the bundled example from a host terminal:

docker exec -it px4-ros2 /usr/local/bin/ros2-entrypoint.sh \
  ros2 run example_mode_goto_cpp example_mode_goto

Wait for the example to register and for PX4 to report Ready for takeoff!. At the PX4 pxh> prompt, start a simulated take-off:

commander takeoff

Once the vehicle is hovering, activate the example:

commander mode ext1

With only this example registered, ext1 selects Go-to Example, which flies a triangular path. Take off before selecting it: the example prevents arming while its mode is active. Hawkeye can visualise this flight without changing the ROS setup.

To land, enter commander mode auto:land at the PX4 prompt. To stop the container, run docker stop px4-ros2 from the host. Use a different ROS_DOMAIN_ID for each independent ROS simulation to avoid cross-talk.

For local builds, publishing, cache behaviour and SBOMs, see Building SITL Containers.

Налаштування

These options apply to both .deb packages and containers. Note that after the first section below we only show how to use them with the deb packages (the pattern for using the options doesn't change).

Vehicle Selection

Set PX4_SIM_MODEL to choose a vehicle.

SIH:

# Deb package
PX4_SIM_MODEL=sihsim_airplane px4

# Container
docker run --rm -it -e PX4_SIM_MODEL=sihsim_airplane px4io/px4-sitl:latest

Gazebo:

# Deb package
PX4_SIM_MODEL=gz_x500 px4-gazebo

# Container
docker run --rm -it -e HEADLESS=1 -e PX4_SIM_MODEL=gz_x500 px4io/px4-sitl-gazebo:latest

See SIH Supported Vehicles and Gazebo Vehicles for the full lists.

World Selection (Gazebo only)

PX4_GZ_WORLD=baylands PX4_SIM_MODEL=gz_x500 px4-gazebo

See Gazebo Worlds for available worlds.

Environment Variables

Змінні Опис Default
PX4_SIM_MODEL Vehicle model (e.g. gz_x500, sihsim_quadx) (required)
PX4_GZ_WORLD Gazebo world name, without .sdf (e.g. baylands) default
HEADLESS Set to 1 to disable Gazebo GUI (unset)
PX4_ROS2_MIDDLEWARE ROS 2 middleware: uxrce_dds, zenoh or none (see ROS 2 Integration) (unset: ZENOH_ENABLE decides)
PX4_UXRCE_DDS_PORT uXRCE-DDS agent UDP port 8888
PX4_UXRCE_DDS_NS uXRCE-DDS ROS namespace (none)
PX4_ZENOH_LOCATOR Zenoh router locator (e.g. tcp/192.168.1.5:7447) stored config, tcp/127.0.0.1:7447
XDG_DATA_HOME Base directory for per-instance working data (parameters, dataman) $HOME/.local/share

Multi-Instance

Multiple simulated vehicles can run simultaneously by passing the -i flag with an instance number. Each instance must be started in a separate terminal (or container). This works with both simulators.

# Terminal 1
PX4_SIM_MODEL=sihsim_quadx px4 -i 0

# Terminal 2
PX4_SIM_MODEL=sihsim_quadx px4 -i 1

MAVLink and uXRCE-DDS port numbers are automatically offset by the instance number. Zenoh does not support multiple instances yet: every instance publishes the same topics without a namespace, so use uXRCE-DDS for multi-vehicle ROS 2 setups.

Each package (px4 and px4-gazebo) is a standalone install. Do not mix instances from the two packages in the same session.

PX4 opens several MAVLink UDP ports on startup. QGroundControl auto-connects on UDP port 14550. You can also connect MAVSDK or any MAVLink-compatible tool.

Link Режим UDP Local Port UDP Remote Port Data Rate
GCS link Normal 18570 + instance 14550 4 Mbps
API/Offboard link Onboard 14580 + instance 14540 + instance 4 Mbps
Onboard link to camera Onboard 14280 + instance 14030 + instance 4 kbps
Onboard link to gimbal Gimbal 13030 + instance 13280 + instance 400 kbps
SIH display (SIH only) Custom 19450 + instance 19410 + instance 400 kbps

By default, MAVLink only listens on localhost. Set parameter MAV_{i}_BROADCAST = 1 to enable network access.

ROS 2 Integration

PX4 includes both the uXRCE-DDS and the Zenoh clients; only one of them runs. uXRCE-DDS is the default. Select the middleware with PX4_ROS2_MIDDLEWARE:

Значення Effect
uxrce_dds Start uxrce_dds_client; sets ZENOH_ENABLE to 0
zenoh Start zenoh; sets ZENOH_ENABLE to 1
none Start neither

The value is stored in ZENOH_ENABLE, so it persists for later runs of the same instance. Without the variable, ZENOH_ENABLE decides: 1 starts Zenoh, 0 starts uXRCE-DDS.

uXRCE-DDS

The uxrce_dds_client module connects to a Micro XRCE-DDS Agent over UDP. Run the agent before starting PX4:

MicroXRCEAgent udp4 -p 8888
Налаштування Default
Transport UDP
Agent IP 127.0.0.1
Agent Port 8888

Environment variables PX4_UXRCE_DDS_PORT and PX4_UXRCE_DDS_NS override the corresponding PX4 parameters (UXRCE_DDS_PRT, UXRCE_DDS_NS_IDX) at runtime without modifying stored parameters:

PX4_UXRCE_DDS_PORT=9999 PX4_UXRCE_DDS_NS=drone1 PX4_SIM_MODEL=sihsim_quadx px4

Zenoh

The zenoh module connects as a client to a Zenoh router over TCP and is compatible with ROS 2 Jazzy and later through rmw_zenoh_cpp. Start the router, then PX4:

# Terminal 1: Zenoh router
ros2 run rmw_zenoh_cpp rmw_zenohd

# Terminal 2: PX4
PX4_ROS2_MIDDLEWARE=zenoh PX4_SIM_MODEL=sihsim_quadx px4

# Terminal 3: ROS 2
RMW_IMPLEMENTATION=rmw_zenoh_cpp ros2 topic list
Налаштування Default
Transport TCP
Router locator tcp/127.0.0.1:7447

Set PX4_ZENOH_LOCATOR to reach a router elsewhere, for example PX4_ZENOH_LOCATOR=tcp/192.168.1.5:7447. The locator is written to the instance's Zenoh network configuration, so it persists for later runs. ROS_DOMAIN_ID, when set, is applied to ZENOH_DOMAIN_ID.

:::warning Zenoh does not yet synchronize time with ROS 2: PX4 publishes timestamps in its own boot time, and incoming timestamp_sample values are not translated. As a result, measurements sent through the PX4 ROS 2 Interface Library navigation interfaces (for example external vision) are not fused by EKF2. Use uXRCE-DDS for those. :::

With the runtime container images on Docker Desktop, PX4 connects to a router on the host automatically:

docker run --rm -it -e PX4_ROS2_MIDDLEWARE=zenoh px4io/px4-sitl:latest

Daemon Mode

Start PX4 without an interactive shell (useful for CI pipelines and automated testing):

PX4_SIM_MODEL=sihsim_quadx px4 -d

Installed File Layout

px4

/opt/px4/
  bin/
    px4           # PX4 binary
    px4-*         # Module symlinks
    px4-alias.sh  # Shell aliases
  etc/            # ROMFS (init scripts, mixers, airframes)
    init.d-posix/

/usr/bin/px4 -> /opt/px4/bin/px4

px4-gazebo

/opt/px4-gazebo/
  bin/
    px4           # PX4 binary
    px4-gazebo    # Gazebo wrapper (sets GZ_SIM_* env vars)
    px4-*         # Module symlinks
    px4-alias.sh  # Shell aliases
  etc/            # ROMFS (init scripts, mixers, airframes)
    init.d-posix/
  share/gz/
    models/       # Gazebo vehicle models
    worlds/       # Gazebo world files
    server.config
  lib/gz/plugins/ # PX4 Gazebo plugins

/usr/bin/px4-gazebo -> /opt/px4-gazebo/bin/px4-gazebo

Runtime directories (created on first run, per user)

$XDG_DATA_HOME/px4/rootfs/<instance>/      # filesystem root
$XDG_DATA_HOME/px4/rootfs/<instance>/fs/  # storage: parameters, dataman, logs, eeprom

Building .deb Files Locally

To build .deb files locally (e.g. to package a custom PX4 branch):

# SIH — produces px4_*.deb
make px4_sitl_sih
cd build/px4_sitl_sih && cpack -G DEB

# Gazebo — produces px4-gazebo_*.deb
make px4_sitl_default
cd build/px4_sitl_default && cpack -G DEB