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>
* Initial changes
* index fix
* gz index fix2
* gz index fix 3
* updates
* Run prettier
* zsh env
removed gz classic
* Corrections 2
* Cleanups
* Update docs/en/dev_setup/dev_env_mac.md
* Apply suggestions from code review
* Minor subedit and prettier
* small correction
* cleanups gz harmonic brew formula
* fix(macos.sh): invert px4-sim install condition for --sim-tools
The condition checked if px4-sim WAS installed before running
brew install, meaning it would never install on a fresh system.
Add the missing negation so it installs when NOT already present.
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
* docs: rewrite macOS dev environment setup guide
- Add Xcode Command Line Tools as prerequisite
- Default to ~/.zshrc (macOS default since Catalina)
- Explain why ulimit change is needed and why in startup file
- Add reminder to open new terminal after shell config changes
- Remove broken pip3 alias workaround
- Split git clone into clone + submodule update (canonical form)
- Recommend --sim-tools flag since first build uses gz_x500
- Document what macos.sh installs and its --reinstall flag
- Clarify Gazebo comes from --sim-tools / px4-sim formula
- Add XQuartz requirement for Gazebo display
- Add verification section with key tool checks and smoke test
- Remove outdated video guide comment block
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
* conventions
---------
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
Co-authored-by: Ramon Roche <mrpollo@gmail.com>
- Update "Failed to import Python packages" section to reference
gz_x500 instead of jmavsim, and point to Tools/setup/requirements.txt
instead of listing individual packages
- Fix :::info admonition spacing in Ubuntu dev env docs
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
The new px4-dev container replaces the old per-distro container
hierarchy from PX4/PX4-containers. It is:
- Multi-architecture (linux/amd64 + linux/arm64)
- Based on Ubuntu 24.04
- Built from the in-tree Dockerfile via GitHub Actions
- Published to both ghcr.io and Docker Hub
- Tagged with PX4 versions (e.g. px4-dev:v1.16.0)
Mark the legacy per-distro containers (px4-dev-nuttx-jammy,
px4-dev-ros2-humble, etc.) as deprecated, note that px4-sim
is planned for simulation workflows.
Update all examples to use px4-dev instead of legacy containers.
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
docker.md:
- Update container hierarchy from focal to jammy
- Replace ROS Noetic/Foxy references with ROS 2 Humble
- Update docker run example to use humble container
- Update SITL example from gazebo-classic to gz_x500
- Update VM tested version from Ubuntu 14.04 to 22.04
vscode.md:
- Remove "Ubuntu 18.04" from inotify troubleshooting header
(this issue is not Ubuntu-version-specific)
dev_env_linux_centos.md:
- Update GCC warning to reference current Ubuntu LTS toolchain
instead of old Focal Docker file
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
- Replace "older version" collapsible with info block stating
supported versions: Ubuntu 24.04 (primary) and 22.04
- Remove Gazebo Classic references (Ubuntu 22.04 section, install step)
- Note that GCC version comes from Ubuntu package manager
- Clarify that GCC version depends on Ubuntu release
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
- Remove Ubuntu 18.04 troubleshooting sections (compile errors,
VSCode inotify) — Ubuntu 18.04 is no longer supported
- Remove Gazebo Classic SITL dropdown from first build section
- Update FMUv2 flash warning to reference gcc-arm-none-eabi from
current Ubuntu LTS instead of vague "CI/docker" reference
- Update flash overflow guidance to point at Ubuntu LTS toolchain
- Simplify "too many open files" error example (remove old GCC 7.2.1
path from 2017)
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
* Fix formatting and capitalization in dev_env_mac.md
Updated formatting and capitalization for consistency in the macOS development environment documentation.
* Correct 'Mac OS' to 'macOS' in documentation
* Fix capitalization of 'macOS' in documentation
* Update dev_env_windows_wsl.md
Add info about enabling broadcasting or streaming to work with PX4 SITL on WSL and QGC on Windows.
* Update dev_env_windows_wsl.md
Fix links
* Update dev_env_windows_wsl.md
moved troubleshooting section at the bottom of WSL2<>Windows section.
* Move under troubleshooting
---------
Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
Note: Some files are autogenerated and I did not yet
go through each source of generation to fix it there.
Instead I adjusted the filter to only exclude those
such that we can fix things in steps.
* Add vitepress tree
* Update existing workflows so they dont trigger on changes in the docs path
* Add nojekyll, package.json, LICENCE etc
* Add crowdin docs upload/download scripts
* Add docs flaw checker workflows
* Used docs prefix for docs workflows
* Crowdin obvious fixes
* ci: docs move to self hosted runner
runs on a beefy server for faster builds
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
* ci: don't run build action for docs or ci changes
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
* ci: update runners
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
* Add docs/en
* Add docs assets and scripts
* Fix up editlinks to point to PX4 sources
* Download just the translations that are supported
* Add translation sources for zh, uk, ko
* Update latest tranlsation and uorb graphs
* update vitepress to latest
---------
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Ramon Roche <mrpollo@gmail.com>
Ramon Roche
Hamish Willee
Farhang
PX4BuildBot
Connor Denihan
SolderSyntax
Daan Smienk
Matthias Grob