mirror of
https://github.com/PX4/PX4-Autopilot.git
synced 2026-07-27 00:48:23 +08:00
96e760a782
* docs(docs): Add missing uorb topics sidebar * docs(docs): discontinue cuav v5 plus/nano * docs(docs): Fix 404 and 303 status HTTP links * docs(docs): more link fixes * update(drivers): Docs fix to fix up link * docs(docs): Fix up all remaining broken links and add exclusions
298 lines
10 KiB
Markdown
298 lines
10 KiB
Markdown
# 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-started/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
|
|
```
|