mirror of
https://github.com/PX4/PX4-Autopilot.git
synced 2026-05-26 09:26:25 +08:00
docs(sim): add Try PX4 quick-start and pre-built packages reference (#26957)
Adds documentation for the SITL containers and .deb packages introduced in #26495. The containers are now live on Docker Hub: [`px4io/px4-sitl:latest`](https://hub.docker.com/r/px4io/px4-sitl) and [`px4io/px4-sitl-gazebo:latest`](https://hub.docker.com/r/px4io/px4-sitl-gazebo). The main addition is a [Try PX4 Simulation](https://docs.px4.io/main/en/dev_setup/try_px4) page that leads with a single `docker run` command and gets someone flying in under a minute. It lives in Getting Started, right after Recommended Hardware/Setup, so it's one of the first things new users see. The existing `.deb` package reference has been moved from `packaging/px4_sitl_deb.md` to `simulation/px4_sitl.md` and expanded to cover both containers and `.deb` packages on one page. Sections are ordered by how people use them: what's available, install, configure, connect QGC/MAVSDK, connect ROS 2. Other changes: - README now has a "Try PX4" section with the docker one-liner above "Build from Source" - Landing page (`index.md`) reworked to lead with "Try PX4" before "For Developers" - Toolchain page (`dev_env.md`) gets a tip redirecting simulation-only users to pre-built packages - `getting_started.md` and `SUMMARY.md` updated with links to the new pages - Simulation index tip updated to mention containers alongside `.deb` packages The SIH container image is published as `px4io/px4-sitl` (renamed from `px4io/px4-sitl-sih`) so the default lightweight option carries the simplest name. The Gazebo image remains `px4io/px4-sitl-gazebo`. Also upgrades all GitHub Actions in the SITL workflow to Node.js 24 compatible versions (`actions/checkout@v6`, `actions/cache@v5`, `actions/upload-artifact@v7`, `actions/download-artifact@v8`, `docker/setup-buildx-action@v4`, `docker/build-push-action@v7`) to fix the Node.js 20 deprecation warning ahead of the June 2026 deadline. --------- Signed-off-by: Ramon Roche <mrpollo@gmail.com> Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
This commit is contained in:
Ramon Roche
GitHub
@@ -27,11 +27,15 @@ See [PX4-Autopilot#23602](https://github.com/PX4/PX4-Autopilot/issues/23602) for
|
||||
| Simulator | Description |
|
||||
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [Gazebo](../sim_gazebo_gz/index.md) | Gazebo supersedes [Gazebo Classic](../sim_gazebo_classic/index.md), featuring more advanced rendering, physics and sensor models. It is the only version of Gazebo available from Ubuntu Linux 22.04<br><br>A powerful 3D simulation environment that is particularly suitable for testing object-avoidance and computer vision. It can also be used for [multi-vehicle simulation](../simulation/multi-vehicle-simulation.md) and is commonly used with [ROS](../simulation/ros_interface.md), a collection of tools for automating vehicle control. <br><br><strong>Supported Vehicles:</strong> Quad, VTOL (Standard, Tailsitter, Tiltroter), Plane, Rovers |
|
||||
| [Gazebo Classic](../sim_gazebo_classic/index.md) | A powerful 3D simulation environment that is particularly suitable for testing object-avoidance and computer vision. It can also be used for [multi-vehicle simulation](../simulation/multi-vehicle-simulation.md) and is commonly used with [ROS](../simulation/ros_interface.md), a collection of tools for automating vehicle control.<br><br>**Supported Vehicles:** Quad ([Iris](../airframes/airframe_reference.md#copter_quadrotor_x_generic_quadcopter)), Hex (Typhoon H480), [Generic Standard VTOL (QuadPlane)](../airframes/airframe_reference.md#vtol_standard_vtol_generic_standard_vtol), Tailsitter, Plane, Rover, Submarine |
|
||||
| [SIH](../sim_sih/index.md) | A lightweight, headless simulator that runs physics directly inside PX4 as a C++ module (no external dependencies). Headless by default for fastest iteration. Supports ROS 2 via uXRCE-DDS. Can also run on flight controller hardware (`SYS_HITL=2`).<br><br>**Supported Vehicles:** Quad, Hex, Plane, Tailsitter, Standard VTOL, Rover |
|
||||
| [Gazebo Classic](../sim_gazebo_classic/index.md) | A powerful 3D simulation environment that is particularly suitable for testing object-avoidance and computer vision. It can also be used for [multi-vehicle simulation](../simulation/multi-vehicle-simulation.md) and is commonly used with [ROS](../simulation/ros_interface.md), a collection of tools for automating vehicle control.<br><br>**Supported Vehicles:** Quad ([Iris](../airframes/airframe_reference.md#copter_quadrotor_x_generic_quadcopter)), Hex (Typhoon H480), [Generic Standard VTOL (QuadPlane)](../airframes/airframe_reference.md#vtol_standard_vtol_generic_standard_vtol), Tailsitter, Plane, Rover, Submarine |
|
||||
|
||||
There are also a number of [Community Supported Simulators](../simulation/community_supported_simulators.md).
|
||||
|
||||
:::tip
|
||||
To run PX4 SITL without setting up a build environment, [pre-built packages and containers](px4_sitl_prebuilt_packages.md) are available.
|
||||
:::
|
||||
|
||||
### Simulator Comparison
|
||||
|
||||
| Feature | Gazebo | SIH |
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
# PX4 Simulation QuickStart
|
||||
|
||||
First install [Docker](https://docs.docker.com/get-docker/) (a free tool that runs containers).
|
||||
|
||||
The following command will then run a PX4 quadrotor simulation that you can connect to [QGroundControl](https://qgroundcontrol.com), [MAVSDK](https://mavsdk.mavlink.io/) or [ROS 2](../ros2/user_guide.md) (on Linux, macOS, and Windows):
|
||||
|
||||
```sh
|
||||
docker run --rm -it -p 14550:14550/udp px4io/px4-sitl:latest
|
||||
```
|
||||
|
||||
That's it — open [QGroundControl](https://qgroundcontrol.com) and fly!
|
||||
|
||||
::: tip
|
||||
|
||||
To try [other vehicle types](../sim_sih/#supported-vehicle-types) append the corresponding line below to the command:
|
||||
|
||||
```sh
|
||||
-e PX4_SIM_MODEL=sihsim_airplane # Plane
|
||||
-e PX4_SIM_MODEL=sihsim_standard_vtol # Standard VTOL
|
||||
-e PX4_SIM_MODEL=sihsim_rover # Ackermann rover
|
||||
```
|
||||
|
||||
For more information and options see [Container Images](../simulation/px4_sitl_prebuilt_packages.md#container-images) (in _Pre-built SITL Packages_) and [SIH Simulation](../sim_sih/index.md).
|
||||
|
||||
:::
|
||||
@@ -0,0 +1,297 @@
|
||||
# Pre-built SITL Packages
|
||||
|
||||
Pre-built packages let you run [PX4 SITL simulation](index.md) 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](https://mavsdk.mavlink.io) or [ROS 2](../ros2/user_guide.md), or you just want to fly with PX4.
|
||||
|
||||
::: tip
|
||||
See [PX4 Simulation QuickStart](px4_simulation_quickstart.md) 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](#container-images) (any OS):
|
||||
|
||||
| Simulator | Format | Package / Image | Size |
|
||||
| -------------------------------------------- | --------- | ----------------------- | ------- |
|
||||
| [SIH](../sim_sih/index.md) | .deb | `px4` | ~10 MB |
|
||||
| | container | `px4io/px4-sitl` | ~100 MB |
|
||||
| [Gazebo Harmonic](../sim_gazebo_gz/index.md) | .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](index.md#simulator-comparison).
|
||||
|
||||
### 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](https://github.com/PX4/PX4-Autopilot/releases) page.
|
||||
|
||||
## .deb Packages (Ubuntu)
|
||||
|
||||
Download the `.deb` file for your Ubuntu version and architecture from the [PX4 Releases](https://github.com/PX4/PX4-Autopilot/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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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](https://hub.docker.com/u/px4io) on every tagged release.
|
||||
You will need to [install Docker](https://docs.docker.com/get-docker/).
|
||||
|
||||
| Image | Simulator |
|
||||
| ----------------------------- | --------------- |
|
||||
| `px4io/px4-sitl:<tag>` | SIH (headless) |
|
||||
| `px4io/px4-sitl-gazebo:<tag>` | Gazebo Harmonic |
|
||||
|
||||
Tags follow PX4 versions (e.g. `v1.17.0`).
|
||||
|
||||
### Running
|
||||
|
||||
```bash
|
||||
# SIH
|
||||
docker run --rm -it -p 14550:14550/udp px4io/px4-sitl:latest
|
||||
|
||||
# Gazebo
|
||||
docker run --rm -it -p 14550:14550/udp px4io/px4-sitl-gazebo:latest
|
||||
```
|
||||
|
||||
Pass environment variables with `-e`:
|
||||
|
||||
```bash
|
||||
docker run --rm -it -p 14550:14550/udp \
|
||||
-e PX4_SIM_MODEL=sihsim_airplane \
|
||||
px4io/px4-sitl:latest
|
||||
```
|
||||
|
||||
The quick-start command above only exposes the QGroundControl port.
|
||||
To use MAVSDK, uXRCE-DDS (ROS 2), or MAVSim Viewer, expose the additional ports:
|
||||
|
||||
```bash
|
||||
docker run --rm -it \
|
||||
-p 14550:14550/udp \
|
||||
-p 14540:14540/udp \
|
||||
-p 8888:8888/udp \
|
||||
-p 19410:19410/udp \
|
||||
px4io/px4-sitl:latest
|
||||
```
|
||||
|
||||
| Port | Protocol | Used by |
|
||||
| ----- | -------- | --------------------------- |
|
||||
| 14550 | UDP | QGroundControl |
|
||||
| 14540 | UDP | MAVSDK / offboard API |
|
||||
| 8888 | UDP | uXRCE-DDS agent (ROS 2) |
|
||||
| 19410 | UDP | SIH display (MAVSim Viewer) |
|
||||
|
||||
On Linux, you can skip individual port flags and use `--network host` instead:
|
||||
|
||||
```bash
|
||||
docker run --rm -it --network host px4io/px4-sitl:latest
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
# Deb package
|
||||
PX4_SIM_MODEL=sihsim_airplane px4
|
||||
|
||||
# Container
|
||||
docker run --rm -it -p 14550:14550/udp px4io/px4-sitl:latest -e PX4_SIM_MODEL=sihsim_airplane
|
||||
```
|
||||
|
||||
Gazebo:
|
||||
|
||||
```
|
||||
# Deb package
|
||||
PX4_SIM_MODEL=gz_x500 px4-gazebo
|
||||
|
||||
# Container
|
||||
docker run --rm -it -p 14550:14550/udp px4io/px4-sitl-gazebo:latest -e PX4_SIM_MODEL=gz_x500
|
||||
```
|
||||
|
||||
See [SIH Supported Vehicles](../sim_sih/index.md#supported-vehicle-types) and [Gazebo Vehicles](../sim_gazebo_gz/vehicles.md) for the full lists.
|
||||
|
||||
### World Selection (Gazebo only)
|
||||
|
||||
```sh
|
||||
PX4_GZ_WORLD=baylands PX4_SIM_MODEL=gz_x500 px4-gazebo
|
||||
```
|
||||
|
||||
See [Gazebo Worlds](../sim_gazebo_gz/worlds.md) for available worlds.
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | 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_UXRCE_DDS_PORT` | uXRCE-DDS agent UDP port | `8888` |
|
||||
| `PX4_UXRCE_DDS_NS` | uXRCE-DDS ROS namespace | (none) |
|
||||
| `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.
|
||||
|
||||
```sh
|
||||
# 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.
|
||||
|
||||
Each package (`px4` and `px4-gazebo`) is a standalone install. Do not mix instances from the two packages in the same session.
|
||||
|
||||
## MAVLink and QGroundControl
|
||||
|
||||
PX4 opens several MAVLink UDP ports on startup.
|
||||
[QGroundControl](https://qgroundcontrol.com) auto-connects on UDP port 14550.
|
||||
You can also connect [MAVSDK](https://mavsdk.mavlink.io) or any MAVLink-compatible tool.
|
||||
|
||||
| Link | Mode | 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
|
||||
|
||||
The `uxrce_dds_client` module starts automatically and connects to a Micro XRCE-DDS Agent over UDP.
|
||||
Run the agent before starting PX4:
|
||||
|
||||
```sh
|
||||
MicroXRCEAgent udp4 -p 8888
|
||||
```
|
||||
|
||||
| Setting | 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](../advanced_config/parameter_reference.md#UXRCE_DDS_PRT), [UXRCE_DDS_NS_IDX](../advanced_config/parameter_reference.md#UXRCE_DDS_NS_IDX)) at runtime without modifying stored parameters:
|
||||
|
||||
```sh
|
||||
PX4_UXRCE_DDS_PORT=9999 PX4_UXRCE_DDS_NS=drone1 PX4_SIM_MODEL=sihsim_quadx px4
|
||||
```
|
||||
|
||||
## Daemon Mode
|
||||
|
||||
Start PX4 without an interactive shell (useful for CI pipelines and automated testing):
|
||||
|
||||
```sh
|
||||
PX4_SIM_MODEL=sihsim_quadx px4 -d
|
||||
```
|
||||
|
||||
## Installed File Layout
|
||||
|
||||
### px4
|
||||
|
||||
```txt
|
||||
/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
|
||||
|
||||
```txt
|
||||
/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)
|
||||
|
||||
```sh
|
||||
$XDG_DATA_HOME/px4/rootfs/<instance>/ # parameters, dataman, eeprom
|
||||
```
|
||||
|
||||
## Building .deb Files Locally
|
||||
|
||||
To build `.deb` files locally (e.g. to package a custom PX4 branch):
|
||||
|
||||
```sh
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user