diff --git a/.github/actions/build-deb/action.yml b/.github/actions/build-deb/action.yml index df07515050..ca774a53b4 100644 --- a/.github/actions/build-deb/action.yml +++ b/.github/actions/build-deb/action.yml @@ -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 diff --git a/.github/workflows/build_deb_package.yml b/.github/workflows/build_deb_package.yml index 24a3d109b0..44599cc081 100644 --- a/.github/workflows/build_deb_package.yml +++ b/.github/workflows/build_deb_package.yml @@ -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 diff --git a/README.md b/README.md index 7ecf3baecd..2e439ecb15 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,17 @@ PX4 is an open-source autopilot stack for drones and unmanned vehicles. It suppo …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 full airframe reference. -## 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 diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index ef7fc12489..b90c2635a2 100644 --- a/docs/en/SUMMARY.md +++ b/docs/en/SUMMARY.md @@ -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) diff --git a/docs/en/dev_setup/dev_env.md b/docs/en/dev_setup/dev_env.md index 5d4810e00a..e9e249864e 100644 --- a/docs/en/dev_setup/dev_env.md +++ b/docs/en/dev_setup/dev_env.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) diff --git a/docs/en/dev_setup/getting_started.md b/docs/en/dev_setup/getting_started.md index ade246eef9..d76f28a52a 100644 --- a/docs/en/dev_setup/getting_started.md +++ b/docs/en/dev_setup/getting_started.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) diff --git a/docs/en/index.md b/docs/en/index.md index 4f465f1fcc..eff027780f 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -21,11 +21,13 @@ Documented changes since the stable release are captured in the evolving [releas +## 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 diff --git a/docs/en/sim_sih/index.md b/docs/en/sim_sih/index.md index ca7d4cb1c5..c8a429a429 100644 --- a/docs/en/sim_sih/index.md +++ b/docs/en/sim_sih/index.md @@ -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. diff --git a/docs/en/simulation/index.md b/docs/en/simulation/index.md index be25fe4149..39db89d5a8 100644 --- a/docs/en/simulation/index.md +++ b/docs/en/simulation/index.md @@ -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

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.

Supported Vehicles: 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.

**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`).

**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.

**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 | diff --git a/docs/en/simulation/px4_simulation_quickstart.md b/docs/en/simulation/px4_simulation_quickstart.md new file mode 100644 index 0000000000..7a314741f4 --- /dev/null +++ b/docs/en/simulation/px4_simulation_quickstart.md @@ -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). + +::: diff --git a/docs/en/simulation/px4_sitl_prebuilt_packages.md b/docs/en/simulation/px4_sitl_prebuilt_packages.md new file mode 100644 index 0000000000..4371c22551 --- /dev/null +++ b/docs/en/simulation/px4_sitl_prebuilt_packages.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:` | SIH (headless) | +| `px4io/px4-sitl-gazebo:` | 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// # 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 +```