mirror of
https://gitee.com/mirrors_PX4/PX4-Autopilot.git
synced 2026-04-14 10:07:39 +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
parent
e34cb8ccb5
commit
9adda29da2
6
.github/actions/build-deb/action.yml
vendored
6
.github/actions/build-deb/action.yml
vendored
@ -20,7 +20,7 @@ runs:
|
||||
steps:
|
||||
- name: Restore ccache
|
||||
id: ccache-restore
|
||||
uses: actions/cache/restore@v4
|
||||
uses: actions/cache/restore@v5
|
||||
with:
|
||||
path: ~/.ccache
|
||||
key: ${{ inputs.ccache-key-prefix }}-${{ github.ref_name }}-${{ github.sha }}
|
||||
@ -52,7 +52,7 @@ runs:
|
||||
run: ccache -s
|
||||
|
||||
- name: Save ccache
|
||||
uses: actions/cache/save@v4
|
||||
uses: actions/cache/save@v5
|
||||
if: always()
|
||||
with:
|
||||
path: ~/.ccache
|
||||
@ -108,7 +108,7 @@ runs:
|
||||
echo "PASS: gazebo package validation successful"
|
||||
|
||||
- name: Upload .deb artifacts
|
||||
uses: actions/upload-artifact@v4
|
||||
uses: actions/upload-artifact@v7
|
||||
with:
|
||||
name: ${{ inputs.artifact-name }}
|
||||
path: build/px4_sitl_${{ inputs.target }}/*.deb
|
||||
|
||||
8
.github/workflows/build_deb_package.yml
vendored
8
.github/workflows/build_deb_package.yml
vendored
@ -40,7 +40,7 @@ jobs:
|
||||
should_push: ${{ steps.push.outputs.should_push }}
|
||||
steps:
|
||||
- uses: runs-on/action@v2
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/checkout@v6
|
||||
with:
|
||||
fetch-tags: true
|
||||
submodules: false
|
||||
@ -93,7 +93,7 @@ jobs:
|
||||
apt-get update && apt-get install -y git
|
||||
git config --global --add safe.directory $(realpath .)
|
||||
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/checkout@v6
|
||||
with:
|
||||
fetch-depth: 0
|
||||
fetch-tags: true
|
||||
@ -103,7 +103,7 @@ jobs:
|
||||
run: ./Tools/ci/use_aws_apt_mirror.sh
|
||||
|
||||
- name: Cache apt packages
|
||||
uses: actions/cache@v4
|
||||
uses: actions/cache@v5
|
||||
with:
|
||||
path: /var/cache/apt/archives
|
||||
key: apt-${{ matrix.target }}-${{ matrix.codename }}-${{ matrix.arch }}-${{ hashFiles('Tools/setup/ubuntu.sh') }}
|
||||
@ -136,7 +136,7 @@ jobs:
|
||||
- { image: gazebo, repo: px4-sitl-gazebo, target: default, arch: arm64, runner: arm64, platform: "linux/arm64", dockerfile: Dockerfile.gazebo }
|
||||
steps:
|
||||
- uses: runs-on/action@v2
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/checkout@v6
|
||||
with:
|
||||
submodules: false
|
||||
fetch-depth: 1
|
||||
|
||||
12
README.md
12
README.md
@ -70,7 +70,17 @@ PX4 is an open-source autopilot stack for drones and unmanned vehicles. It suppo
|
||||
|
||||
<sub>…and many more: helicopters, autogyros, airships, submarines, boats, and other experimental platforms. These frames have basic support but are not part of the regular flight-test program. See the <a href="https://docs.px4.io/main/en/airframes/airframe_reference.html">full airframe reference</a>.</sub>
|
||||
|
||||
## Quick Start
|
||||
## Try PX4
|
||||
|
||||
Run PX4 in simulation with a single command. No build tools, no dependencies beyond Docker:
|
||||
|
||||
```bash
|
||||
docker run --rm -it -p 14550:14550/udp px4io/px4-sitl:latest
|
||||
```
|
||||
|
||||
Open [QGroundControl](https://qgroundcontrol.com) and fly. See [PX4 Simulation Quickstart](../dev_setup/px4_simulation_quickstart.md) for more options.
|
||||
|
||||
## Build from Source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/PX4/PX4-Autopilot.git --recursive
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
- [Introduction](index.md)
|
||||
- [Basic Concepts](getting_started/px4_basic_concepts.md)
|
||||
|
||||
- [Try PX4 (Simulation)](simulation/px4_simulation_quickstart.md)
|
||||
- [Multicopters](frames_multicopter/index.md)
|
||||
- [Features](features_mc/index.md)
|
||||
- [Flight Modes](flight_modes_mc/index.md)
|
||||
@ -474,6 +474,7 @@
|
||||
- [Worlds](sim_gazebo_classic/worlds.md)
|
||||
- [Multi-Vehicle Sim](sim_gazebo_classic/multi_vehicle_simulation.md)
|
||||
- [Simulate Failsafes](simulation/failsafes.md)
|
||||
- [Pre-built Packages](simulation/px4_sitl_prebuilt_packages.md)
|
||||
- [Hardware](hardware/index.md)
|
||||
- [Flight Controller Reference Design](hardware/reference_design.md)
|
||||
- [Manufacturer’s Board Support Guide](hardware/board_support_guide.md)
|
||||
|
||||
@ -1,5 +1,10 @@
|
||||
# Setting up a Developer Environment (Toolchain)
|
||||
|
||||
::: tip
|
||||
You only need a toolchain if you want to **modify and build** PX4 from source.
|
||||
If you just want to run PX4 simulation without changing the code, use a pre-built [Docker container or .deb package](../simulation/px4_sitl_prebuilt_packages.md) instead.
|
||||
:::
|
||||
|
||||
The _supported platforms_ for PX4 development are:
|
||||
|
||||
- [Ubuntu Linux (24.04/22.04)](../dev_setup/dev_env_linux_ubuntu.md)
|
||||
|
||||
@ -2,6 +2,7 @@
|
||||
|
||||
This section contains topics about getting started with PX4 development:
|
||||
|
||||
- [PX4 Simulation QuickStart](../simulation/px4_simulation_quickstart.md) — Try PX4 in simulation without a build environment!
|
||||
- [Initial Setup](../dev_setup/config_initial.md)
|
||||
- [Toolchain Installation](../dev_setup/dev_env.md)
|
||||
- [Building the Code](../dev_setup/building_px4.md)
|
||||
|
||||
@ -21,11 +21,13 @@ Documented changes since the stable release are captured in the evolving [releas
|
||||
|
||||
</div>
|
||||
|
||||
## Try PX4
|
||||
|
||||
No hardware needed. Run PX4 in simulation with a single command using [Docker or a .deb package](simulation/px4_simulation_quickstart.md). Connect [QGroundControl](https://qgroundcontrol.com), [MAVSDK](https://mavsdk.mavlink.io/), or [ROS 2](ros2/index.md) and start flying immediately.
|
||||
|
||||
## For Developers
|
||||
|
||||
:::tip
|
||||
Building on PX4 or extending the platform? Start here: [Development Guide](development/development.md). Set up your [dev environment](dev_setup/config_initial.md), [build from source](dev_setup/building_px4.md), run [SITL simulation](simulation/index.md), or integrate via [ROS 2](ros2/index.md) and [MAVSDK](https://mavsdk.mavlink.io/).
|
||||
:::
|
||||
Want to modify PX4 or build from source? Start with the [Development Guide](development/development.md): set up your [dev environment](dev_setup/dev_env.md), [build the code](dev_setup/building_px4.md), and run [SITL simulation](simulation/index.md).
|
||||
|
||||
## Getting Started
|
||||
|
||||
|
||||
@ -6,6 +6,11 @@ SIH (Simulation-In-Hardware) is a lightweight, headless simulator with zero exte
|
||||
No GUI, no external processes, no rendering overhead — just PX4 running a C++ physics model.
|
||||
This makes it the fastest way to iterate on flight code.
|
||||
|
||||
::: tip
|
||||
SIH is also available as a [prebuilt Docker container or .deb package](../simulation/px4_sitl_prebuilt_packages.md), which is useful if you don't need to modify PX4 itself.
|
||||
See [PX4 Simulation QuickStart](px4_simulation_quickstart.md) for a one-line instruction on how this is used.
|
||||
:::
|
||||
|
||||
## Overview
|
||||
|
||||
SIH runs as a PX4 module that replaces real sensor and actuator hardware with a simulated physics model.
|
||||
|
||||
@ -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 |
|
||||
|
||||
25
docs/en/simulation/px4_simulation_quickstart.md
Normal file
25
docs/en/simulation/px4_simulation_quickstart.md
Normal file
@ -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).
|
||||
|
||||
:::
|
||||
297
docs/en/simulation/px4_sitl_prebuilt_packages.md
Normal file
297
docs/en/simulation/px4_sitl_prebuilt_packages.md
Normal file
@ -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
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user