diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index 123223ee90..2b2242c054 100644 --- a/docs/en/SUMMARY.md +++ b/docs/en/SUMMARY.md @@ -854,6 +854,7 @@ - [Windows VM Toolchain](dev_setup/dev_env_windows_vm.md) - [Windows Cygwin Toolchain](dev_setup/dev_env_windows_cygwin.md) - [Windows Cygwin Toolchain Maintenance](dev_setup/dev_env_windows_cygwin_packager_setup.md) + - [Windows Native (CMD/PowerShell)](dev_setup/dev_env_windows_native.md) - [Qt Creator IDE](dev_setup/qtcreator.md) - [Simulators](simulation/community_supported_simulators.md) - [FlightGear Simulation](sim_flightgear/index.md) diff --git a/docs/en/advanced/community_supported_dev_env.md b/docs/en/advanced/community_supported_dev_env.md index 01d6789140..aa96098065 100644 --- a/docs/en/advanced/community_supported_dev_env.md +++ b/docs/en/advanced/community_supported_dev_env.md @@ -18,6 +18,7 @@ Questions about these tools should be raised on the [discussion forums](../contr - [Windows VM Toolchain](../dev_setup/dev_env_windows_vm.md) — Ubuntu setup running in VM on Windows. - [Windows Cygwin Toolchain](../dev_setup/dev_env_windows_cygwin.md) — Windows setup only works to PX4 v1.12 - [Windows Cygwin Toolchain Maintenance](../dev_setup/dev_env_windows_cygwin_packager_setup.md) + - [Windows Native (CMD/PowerShell)](../dev_setup/dev_env_windows_native.md) — Native Windows 10/11 SITL build using MSVC or MinGW-w64. - IDEs - [Qt Creator IDE](../dev_setup/qtcreator.md) - [Simulators](../simulation/community_supported_simulators.md) — [Simulation-In-Hardware](../sim_sih/index.md), [FlightGear](../sim_flightgear/index.md), [JSBSim](../sim_jsbsim/index.md), [AirSim](../sim_airsim/index.md), [HITL](../simulation/hitl.md) diff --git a/docs/en/dev_setup/dev_env_windows_cygwin.md b/docs/en/dev_setup/dev_env_windows_cygwin.md index cc44511da3..75d37f39c0 100644 --- a/docs/en/dev_setup/dev_env_windows_cygwin.md +++ b/docs/en/dev_setup/dev_env_windows_cygwin.md @@ -5,7 +5,7 @@ This development environment is [community supported and maintained](../advanced It may or may not work with current versions of PX4. The toolchain was previously recommended, but does not work with PX4 v1.12 and later due to packaging issues. -The [Windows WSL2-Based Development Environment](../dev_setup/dev_env_windows_wsl.md) should be used by preference. +The [Windows WSL2-Based Development Environment](../dev_setup/dev_env_windows_wsl.md) should be used by preference, or the [Windows Native (CMD/PowerShell)](../dev_setup/dev_env_windows_native.md) toolchain for SIH SITL or NuttX hardware builds without WSL. See [Toolchain Installation](../dev_setup/dev_env.md) for information about the environments and tools supported by the core development team. ::: diff --git a/docs/en/dev_setup/dev_env_windows_native.md b/docs/en/dev_setup/dev_env_windows_native.md new file mode 100644 index 0000000000..ddbf2eeca6 --- /dev/null +++ b/docs/en/dev_setup/dev_env_windows_native.md @@ -0,0 +1,551 @@ +# Windows Native Development Environment (CMD/PowerShell) + +::: warning +This development environment is [community supported and maintained](../advanced/community_supported_dev_env.md). +It may or may not work with current versions of PX4. + +The [Windows WSL2-Based Development Environment](../dev_setup/dev_env_windows_wsl.md) should be used by preference for most developers. +The native toolchain is intended for contributors working on Windows-specific platform code, and for users who need to run [SIH](../sim_sih/index.md) without a Linux VM. + +See [Toolchain Installation](../dev_setup/dev_env.md) for information about the environments and tools supported by the core development team. +::: + +The following instructions explain how to set up a native (non-WSL) PX4 development environment on Windows 10 or 11, building directly from CMD or PowerShell. + +This environment can be used to build PX4 for: + +- [SIH SITL Simulation](../sim_sih/index.md) — the only simulator whose dynamics run **inside** `px4.exe`, so no external simulator process is needed on Windows. +- [Pixhawk and other NuttX-based hardware](../dev_setup/building_px4.md#nuttx-pixhawk-based-boards) (NuttX cross-toolchain installed separately). + +::: info +Gazebo, Gazebo Classic, and jMAVSim depend on a Linux host (or, for jMAVSim, a JDK + `ant` install) for the simulator process itself. +You can still drive any of them from a natively-built `px4.exe` by starting the simulator in [WSL2](../dev_setup/dev_env_windows_wsl.md) or on a remote Linux machine and pointing PX4 at that host with `PX4_SIM_HOSTNAME` (or `PX4_SIM_HOST_ADDR`) — `simulator_mavlink` will connect to the external simulator over TCP/UDP. +What is not wired up natively are the convenience targets that *spawn* the simulator for you (`make px4_sitl gz_x500`, `make px4_sitl jmavsim`, `make px4_sitl gazebo-classic_iris`); on Windows you launch the simulator yourself and then start `px4.exe`. +::: + +## Overview + +PX4 SITL is built natively on Windows by the same `make px4_sitl_default` entry point that is used on Linux and macOS. +Two compilers are supported: + +- _MSVC_ (Microsoft Visual C++ from Visual Studio 2022 or the Build Tools). + This is the path exercised by the [`Windows SITL build` CI workflow](https://github.com/PX4/PX4-Autopilot/blob/main/.github/workflows/compile_windows.yml) on every PR. +- _MinGW-w64_ (the GCC port shipped with [MSYS2](https://www.msys2.org/)). + Useful if you prefer a GCC-style toolchain or want to cross-build the same artifact you would get from a Linux MinGW cross-compile. + +Both produce a statically linked `build\px4_sitl_default\bin\px4.exe` that you launch directly from CMD or PowerShell. +Companion utilities (`px4-commander`, `px4-listener`, etc.) are produced as additional `.exe` files alongside `px4.exe`. + +::: warning +The PX4 daemon uses a local TCP socket (`127.0.0.1:14680 + instance_id`) on Windows instead of the Unix-domain socket used on Linux/macOS. At the time of writing only `px4-shutdown` is reliably functional; `px4-commander`, `px4-listener`, and the other client `.exe`s currently connect to the server but the server-to-client reply path over Windows TCP loopback does not return output to the caller. This is a known limitation being tracked — for now, drive PX4 from the interactive `pxh>` prompt and reserve the client wrappers for `px4-shutdown`. +::: + +## Installation + +### Before You Start + +You need: + +- _Windows 10_ (21H2 or newer) or _Windows 11_, with the [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/) command available (it ships with the OS as part of _App Installer_; if `winget` is not recognised in a fresh terminal, install _App Installer_ from the Microsoft Store). +- About **10 GB** of free disk space for the toolchain (the Visual Studio 2022 Build Tools install dominates). +- Administrator rights on the machine — the Build Tools installer writes to `C:\Program Files`. +- A first-time install takes roughly **30–60 minutes** end-to-end on a typical broadband connection, most of it unattended download time. + +The setup script lives inside the PX4 repository, so the source tree must be cloned **before** the toolchain script can be run. +A working `git` is the only prerequisite for the clone step; everything else (CMake, Ninja, Python, MSVC Build Tools, MSYS2) is installed by the script. + +### Choosing a Shell + +Windows ships several command-line shells. This guide uses two of them in different situations — the table below shows which to use for each task. + +| Task | Shell | How to open | +| ------------------------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| One-time toolchain install (`Tools\setup\windows.ps1`) | _Windows PowerShell_ **as Administrator** | Press _Start_, type _PowerShell_, right-click _Windows PowerShell_, choose _Run as administrator_. | +| Everyday `git`, MinGW builds, running SIH, `.ps1` launchers | _Windows PowerShell_ (regular, no Administrator) | Press _Start_, type _PowerShell_, press Enter. | +| MSVC builds (`make px4_sitl_default` with the MSVC compiler) | _x64 Native Tools Command Prompt for VS 2022_ (a _CMD_ variant) | After running the setup script: Start menu → _Visual Studio 2022_ → _Visual Studio Tools_ → _VC_ → _x64 Native Tools Command Prompt for VS 2022_. | + +::: info +You do **not** need _Git Bash_ or _MSYS2 MinGW64 Shell_ for this guide. +If you have _Git Bash_ installed (it ships with _Git for Windows_), it works for `git` but adds Unix-shell quirks (forward-slash paths, different quoting, no `$env:` syntax) that these instructions are not written against — stick with _PowerShell_ to avoid surprises. +The setup script generates wrapper `.cmd` shims for the MinGW toolchain so you can build from plain _PowerShell_ without ever opening the _MSYS2_ shell yourself. +::: + +### Get the PX4 Source Code + +Open a regular _PowerShell_ window (no Administrator needed for this step). + +If you do not yet have Git for Windows, install it first (the toolchain script will leave any existing install in place): + +```sh +winget install --id Git.Git -e --source winget +``` + +Close and reopen the _PowerShell_ window so the new `git` command is on `PATH`, then clone the repository in a directory of your choice (this guide assumes `C:\Users\\Documents`): + +```sh +cd $env:USERPROFILE\Documents +git clone https://github.com/PX4/PX4-Autopilot.git --recursive +cd PX4-Autopilot +``` + +`$env:USERPROFILE` is the PowerShell expression for your home directory (`C:\Users\`); `cd` does not print the new path on success — run `pwd` if you want to confirm where you landed. PX4 build commands accept either backslash (`C:\Users\...`) or forward-slash (`C:/Users/...`) paths interchangeably. + +::: warning +A few caveats about _where_ you clone on Windows 11: + +- **OneDrive sync conflict**: the default `Documents` folder is often synchronized by OneDrive, which will fight the build for hundreds of thousands of intermediate object files. Check for the OneDrive cloud icon next to `Documents` in File Explorer, or run `Get-Item $env:USERPROFILE\Documents | Select-Object Target` (a redirected `Documents` has a `Target` set). If yours is synced, clone into a local-only path like `C:\PX4` instead. +- **No spaces in path**: a few build tools have edge cases with quoted paths — `C:\Users\Some User\Documents\PX4-Autopilot` is risky, while `C:\PX4` or `D:\src\PX4-Autopilot` is safer. +- **MAX_PATH (260 chars)**: Windows still defaults to 260-char paths and PX4 generates deep nested directories (especially under `external/Install/...`), so keep the source tree shallow. + +::: + +::: info +PX4 ships a `.gitattributes` that pins line endings, so no `core.autocrlf` configuration is required. +If you have an existing global `core.autocrlf=true`, set it to `false` for this repository: + +```sh +git -C PX4-Autopilot config core.autocrlf false +``` + +::: + +### Install the Toolchain + +The recommended way to install the remaining build dependencies is the bundled setup script. +The script must be run from an **elevated** _PowerShell_ prompt — the Visual Studio 2022 Build Tools installer requires Administrator privileges to write to `C:\Program Files`, and `winget` will fail mid-script otherwise. +To open one: press _Start_, type _PowerShell_, then right-click _Windows PowerShell_ and choose _Run as administrator_. +(The script aborts immediately with an actionable error if it detects a non-elevated shell, so a wrong shell wastes no time.) + +From the elevated prompt, change into the freshly cloned `PX4-Autopilot` directory and run: + +```sh +cd PX4-Autopilot +Set-ExecutionPolicy -Scope Process Bypass +.\Tools\setup\windows.ps1 +``` + +`Set-ExecutionPolicy -Scope Process Bypass` is safe: `-Scope Process` confines the change to this PowerShell window and is forgotten when you close it, leaving the system-wide policy untouched. + +::: warning +The Visual Studio 2022 Build Tools installer downloads roughly 4 GB and runs **silently** for **10–15 minutes** — the script will look frozen during this stage but is working. Leave the window open until the script returns to the prompt; closing it mid-install can leave the Build Tools in a broken state that has to be repaired from _Add or remove programs_. +::: + +The script uses [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/) to install: + +- _Git for Windows_, _Python 3.11_, _CMake_, _Ninja_ +- _GNU make_ (via [Chocolatey](https://chocolatey.org/) if it is already installed, otherwise via [ezwinports](https://sourceforge.net/projects/ezwinports/)) +- _Visual Studio 2022 Build Tools_ with the `Desktop development with C++` workload and the Windows 11 SDK +- The Python build-time packages (`jinja2`, `pyyaml`, `toml`, `numpy`, `packaging`, `jsonschema`, `future`, `empy`, `pyros-genmsg`, `kconfiglib`) + +To install the MSYS2 / MinGW-w64 toolchain instead of (or alongside) MSVC: + +```sh +.\Tools\setup\windows.ps1 -Toolchain MinGW # MSYS2 only +.\Tools\setup\windows.ps1 -Toolchain Both # both compilers +``` + +::: tip +Re-running the script is safe — it skips packages that are already installed. +::: + +::: info +The script appends `C:\msys64\mingw64\bin` to your **user** `PATH` and also exposes it in the current PowerShell process, so the MinGW build works in the same shell that ran the setup script. +Any other shells you had open before running the script will not see the new `PATH` until they are closed and reopened. +::: + +### Verify the Install + +Open a **new** _PowerShell_ window (no need to elevate) so it picks up the `PATH` entries that the setup script registered, then check that the four commands the build relies on are all on `PATH`: + +```sh +git --version +python --version +cmake --version +make --version +``` + +Each command should print a version number. +If any of them prints _"is not recognized as the name of a cmdlet…"_, see [Common Pitfalls](#common-pitfalls) below. + +## Build PX4 SITL + +::: tip +If you are new to native Windows builds, use the **MSVC** path (the next subsection). +It is the toolchain exercised by [CI](https://github.com/PX4/PX4-Autopilot/blob/main/.github/workflows/compile_windows.yml) on every PR and the one the bundled setup script installs by default. +The MinGW-w64 build is offered for users who already prefer GCC, want to reproduce a Linux MinGW cross-compile, or are debugging Windows-specific platform code with `gdb`. +::: + +### MSVC Build + +Open the _x64 Native Tools Command Prompt for VS 2022_ (see the [shell table](#choosing-a-shell) above) — the MSVC compiler is only on `PATH` inside a Visual Studio developer shell. +If you prefer to keep working in _PowerShell_, you can source the developer environment into an existing window with `vcvars64.bat` instead (see [`cl.exe` Not Found](#cl-exe-not-found-msvc) below). + +From the repository root: + +```sh +cd PX4-Autopilot +set PATH=C:\Program Files\Git\usr\bin;C:\Program Files\Git\bin;%PATH% +make px4_sitl_default +``` + +The `set PATH=...` line prepends Git Bash's POSIX utilities (`sed`, `awk`, `dirname`, `[`, `ps`) to the dev-shell `PATH`; the PX4 Makefile invokes them and the MSVC dev shell alone does not provide them. Skip the line and the build aborts early with `'sed' is not recognized`. + +A successful **first** build takes 5–15 minutes depending on the machine and CMake stays silent for the first couple of minutes while it configures the project and downloads upstream dependencies — this is normal, not a hang. The build ends with a line of the form `[NNN/NNN] Linking CXX executable bin\px4.exe`. Subsequent rebuilds in the same shell are incremental and finish in seconds. + +::: warning +The _x64 Native Tools Command Prompt_ provides the MSVC compiler but **not** the POSIX utilities the PX4 Makefile depends on. The bundled setup script installs Git for Windows (which ships them under `C:\Program Files\Git\usr\bin`); either prepend that directory to `PATH` as shown above, or start from a shell that already has Git on `PATH` so `sed`, `awk`, `dirname`, `[`, and `ps` resolve. +::: + +::: info +The PX4 Makefile picks the Ninja generator when `ninja` is on `PATH` and lets CMake auto-detect `cl.exe` from the developer shell — no `-DCMAKE_TOOLCHAIN_FILE` flag is needed. +::: + +### MinGW-w64 Build + +Open a regular _PowerShell_ window (see the [shell table](#choosing-a-shell) above — _not_ the Visual Studio developer shell, and not _MSYS2 MinGW64 Shell_). +After the setup script finishes with `-Toolchain MinGW`, `C:\msys64\mingw64\bin` is on your user `PATH`, so plain _PowerShell_ can drive the MinGW toolchain through the wrapper `.cmd` shims the toolchain file generates: + +```sh +cd PX4-Autopilot +$env:CMAKE_ARGS = "-DCMAKE_TOOLCHAIN_FILE=Toolchain-mingw-w64-x86_64" +make px4_sitl_default +``` + +If you ran the setup script in a different window than the one you build from, **close and reopen** the build shell so it picks up the updated user `PATH`. + +The MinGW build statically links `libgcc`, `libstdc++`, and `winpthread`, so the resulting `px4.exe` has no MSYS2 runtime dependency. + +A successful first build takes 5–15 minutes depending on the machine and ends with a line of the form: + +```sh +[2/2] Linking CXX executable bin\px4.exe +``` + +The output is `build\px4_sitl_default\bin\px4.exe` plus the per-command client executables (`build\px4_sitl_default\bin\px4-commander.exe`, etc.). +Subsequent rebuilds in the same shell are incremental and finish in seconds. + +::: info +You only need to run `Tools\setup\windows.ps1` and pick the developer shell **once** per machine. +For day-to-day work, just open the developer shell, `cd PX4-Autopilot`, and run `make px4_sitl_default` (or any other make target) — there is no need to re-elevate or re-run the setup script. +::: + +## Run SIH on Native Windows + +[SIH](../sim_sih/index.md) runs entirely inside `px4.exe` — its rigid-body dynamics are compiled into the autopilot binary, so no external simulator process is required on Windows. + +The simplest way to launch a quadrotor instance is the same `make` target used on Linux/macOS, which sets `PX4_SIM_MODEL`/`PX4_SIMULATOR` and runs `px4.exe` for you: + +```sh +make px4_sitl_default sihsim_quadx +``` + +Other airframes are exposed as sibling targets. All SIH variants share the same Windows code path — physics run inside `px4.exe` and no Linux-only helper process is required — so anything that builds also launches natively: + +| Vehicle | Make target / `PX4_SIM_MODEL` | Status on Windows | +| ------------------------- | ----------------------------- | ---------------------------------------------------------------- | +| Quadrotor X | `sihsim_quadx` | Stable (the recommended starting point and CI-exercised target). | +| Hexarotor X | `sihsim_hex` | Experimental (same flight-dynamics caveats as on Linux/macOS). | +| Fixed-wing (airplane) | `sihsim_airplane` | Experimental. | +| Tailsitter VTOL | `sihsim_xvert` | Experimental. | +| Standard VTOL (QuadPlane) | `sihsim_standard_vtol` | Experimental. | +| Ackermann Rover | `sihsim_rover_ackermann` | Experimental. | + +::: info +The [SIH Simulation page](../sim_sih/index.md#supported-vehicle-types) lists the hexarotor target as `sihsim_hexa` and the rover target as `sihsim_rover` for brevity, but the actual airframe filenames (and therefore the values that `PX4_SIM_MODEL` and the make targets accept) are `sihsim_hex` and `sihsim_rover_ackermann`. Use the names from the table above when launching `px4.exe` directly. +::: + +The "Experimental" rating is inherited from the upstream SIH support matrix and refers to vehicle dynamics / controller maturity, not to the Windows port — if a SIH airframe builds it will boot and run on Windows the same way it does on Linux or macOS. + +If you would rather invoke `px4.exe` directly (e.g. from a shortcut, a debugger, or a script that does not have `make` on `PATH`), set the environment variable yourself. +You can do this from either _PowerShell_ or _CMD_ — both are shown below; pick whichever shell you already have open. +The relative paths assume your current directory is the `PX4-Autopilot` repository root (the same directory you ran `make px4_sitl_default` from); adjust them if you launch from elsewhere. + +From _PowerShell_: + +```sh +cd PX4-Autopilot +$env:PX4_SIM_MODEL = "sihsim_quadx" +build\px4_sitl_default\bin\px4.exe build\px4_sitl_default\etc +``` + +The same command from _CMD_: + +```sh +cd PX4-Autopilot +set PX4_SIM_MODEL=sihsim_quadx +build\px4_sitl_default\bin\px4.exe build\px4_sitl_default\etc +``` + +The path after `px4.exe` is the positional `` argument — the directory where the startup files and mixers live (see `px4.exe -h` for the full usage). +`px4.exe` then brings up an interactive `pxh>` prompt in the same console. +Type a command and press Enter to dispatch it; type `exit`, `shutdown`, or press **CTRL+C** to stop PX4. +If the prompt is unresponsive (or the instance was started with `-d` and has no prompt), shut it down from a second _PowerShell_ window with `build\px4_sitl_default\bin\px4-shutdown.exe`, or as a last resort `Get-Process px4 | Stop-Process -Force` to kill every running `px4.exe`. + +::: tip +Pass `-d` (daemon mode) before the rootfs path to suppress the `pxh>` prompt — useful when launching PX4 from a script or running multiple background instances. +::: + +::: info +The Windows console does not provide tab completion, history navigation with arrow keys, or ANSI line editing — those features rely on Unix terminal APIs that are not available in the native Windows shell loop. +::: + +A healthy first run prints the PX4 ASCII banner, then progresses through `INFO [px4] Startup script returned successfully`, opens the `pxh>` prompt, and starts emitting periodic `INFO [mavlink] partner IP: 127.0.0.1` lines once a ground station connects. +The repeating MAVLink _partner IP_ messages are the normal heartbeat exchange — they are not errors. + +Logs land in `log\\.ulg` **relative to the working directory** of the `px4.exe` process — if you launched it from the repository root, look for the `log\` folder at the repository root; if you used the multi-instance helper below, each instance writes into its own `build\px4_sitl_default\instance_\log\` tree. +To clean build artefacts, run `make clean` (per-board CMake clean) or `make distclean` (wipe the entire `build\` directory and reset submodules) from the repository root; deleting the `build\px4_sitl_default\` directory by hand has the same effect as the latter for a single board. Per-instance log/parameter directories under `build\px4_sitl_default\instance_\` are not touched by `make clean` — remove them manually when they grow stale. + +To launch multiple instances (e.g. for multi-vehicle testing) use the bundled PowerShell helper, which mirrors `Tools/simulation/sitl_multiple_run.sh`. +Run it from the `PX4-Autopilot` repository root so the relative `.\Tools\simulation\` path resolves: + +```sh +cd PX4-Autopilot +.\Tools\simulation\sitl_multiple_run.ps1 -SitlNum 3 -SimModel sihsim_quadx +``` + +::: info +Up to **3** concurrent instances are validated to run reliably on Windows today. Higher counts (5+) typically see most instances exit silently shortly after `rcS` finishes. This is being tracked in the multi-instance lifecycle work; until that lands, treat 3 as the supported envelope. +::: + +Pass any of the SIH model names from the [vehicle table above](#run-sih-on-native-windows) (e.g. `sihsim_airplane`, `sihsim_standard_vtol`, `sihsim_hex`, `sihsim_rover_ackermann`) via `-SimModel`. To stop every `px4.exe` started by the helper (e.g. when several backgrounded daemon instances are still running), invoke it with `-SitlNum 0`: + +```sh +.\Tools\simulation\sitl_multiple_run.ps1 -SitlNum 0 +``` + +### Tested Envelope + +What has been validated to work on native Windows today: + +- Single `px4.exe` instance at any `PX4_SIM_SPEED_FACTOR` (1x and accelerated). +- Mixed speed factors across instances (when running ≤3 of them). +- MAVLink heartbeat to QGroundControl on `127.0.0.1` (autoconnect). +- The interactive `pxh>` stdin prompt and `CTRL+C` / `shutdown` graceful exit. + +Known limitations (being tracked, not yet fixed): + +- `px4-*` client wrappers other than `px4-shutdown` connect but do not return server output (see the Overview admonition). +- 5+ concurrent instances via `sitl_multiple_run.ps1`; up to 3 is the supported envelope. + +## Connecting QGroundControl + +If you don't already have QGroundControl, install it first via the [QGroundControl Daily Build](../dev_setup/qgc_daily_build.md) page — the steps below assume it is already running on the same host. + +When PX4 SITL runs natively on Windows, [QGroundControl](https://qgroundcontrol.com) on the same host autoconnects out of the box — no manual comm-link setup is required (unlike the [WSL2 workflow](../dev_setup/dev_env_windows_wsl.md#qgroundcontrol-on-windows), which has to bridge across the WSL virtual machine). + +::: info +On the first launch of `px4.exe`, _Windows Defender Firewall_ raises a per-app prompt titled _Windows Security Alert_ with two checkboxes — _Private networks_ and _Public networks_. +Tick **Private networks** and click **Allow access** so MAVLink replies from QGC can reach PX4; if you dismiss the prompt, allow it after the fact under **Windows Security > Firewall & network protection > Allow an app through firewall**. +::: + +## ROS 2 Setup on Windows Native + +This section is only relevant if you want to drive PX4 SITL from [ROS 2](../ros2/user_guide.md) on the same Windows host (the agent build in the next section connects PX4 to whatever ROS 2 install you set up here). +If you only need SIH plus QGroundControl, you can skip this section and the next. + +Starting with **ROS 2 Jazzy**, the OSRF Windows binary release is distributed as a [Pixi](https://pixi.sh/) / `conda-forge` bundle rather than the legacy Visual Studio 2019 + Chocolatey install used for Humble and Iron. +PX4 ships a helper that wraps the Pixi-based install end-to-end: + +```powershell +cd PX4-Autopilot +.\Tools\setup\ros2_pixi_setup.ps1 # default: Jazzy LTS +.\Tools\setup\ros2_pixi_setup.ps1 -Distro rolling # ROS 2 Rolling +.\Tools\setup\ros2_pixi_setup.ps1 -Distro latest # newest non-prerelease release +``` + +Pick **Jazzy** for a stable LTS (recommended), **Rolling** for the latest features (less stable), or **latest** as a shorthand for whichever release OSRF tagged most recently. + +The script is idempotent and runs without Administrator privileges. It: + +- resolves the matching ROS 2 binary release zip from the [`ros2/ros2` GitHub releases](https://github.com/ros2/ros2/releases), downloads it to `$env:TEMP` (cached; pass `-Force` to re-download), and extracts it to `C:\opt\ros\\` (override with `-RosRoot`), +- installs `pixi` to `%USERPROFILE%\.pixi\bin` (no admin required), +- runs `pixi install` against the extracted distro, +- runs OSRF's `preinstall_setup_windows.py` post-install step (mandatory — over a thousand release `.py` files have build-time hardcoded shebangs that need rewriting to point at the Pixi env's `python.exe`), and +- emits a per-distro activation wrapper at `$env:TEMP\activate_ros2_.ps1` plus a generic `$env:TEMP\activate_ros2.ps1` alias pointing at the most recently installed distro. + +Dot-source the wrapper in any future _PowerShell_ session to put `ros2`, `colcon`, and `python` on `PATH`: + +```powershell +. $env:TEMP\activate_ros2.ps1 # most recently installed distro +. $env:TEMP\activate_ros2_jazzy.ps1 # specific distro +. $env:TEMP\activate_ros2.ps1 -WithVcvars # ros2 CLI + MSVC vcvars64 for `colcon build` +``` + +`-WithVcvars` is required when `colcon build` has to invoke `cl.exe` — `conda-forge` does not ship MSVC, so a `colcon build` without a sourced `vcvars64.bat` fails with `cl.exe is not recognized`. + +::: warning +When launching multi-instance PX4 from a session that has activated ROS 2, pass `-w ` to each `px4.exe` and pre-create an `etc` junction inside it; otherwise the instances collide on the shared rootfs. Pass YAML payloads that contain whitespace (e.g. to `Start-Process -ArgumentList`) as a single quoted string rather than an inline `{...}` literal — PowerShell flattens the latter and the agent rejects the malformed message. +::: + +Once ROS 2 is up, the [Micro XRCE-DDS Agent](#building-the-micro-xrce-dds-agent-optional-for-ros-2-dds-bridging) section below builds the bridge that connects PX4 SITL to your ROS 2 graph. See the [uXRCE-DDS middleware page](../middleware/uxrce_dds.md) for the wider workflow, message conventions, and `px4_msgs` setup. + +## Building the Micro-XRCE-DDS Agent (Optional — for ROS 2 / DDS bridging) + +This section is only relevant if you want to bridge PX4 SITL to ROS 2 (or any other DDS subscriber) via the [uXRCE-DDS middleware](../middleware/uxrce_dds.md). +The agent is a separate process that PX4's `uxrce_dds_client` connects to over UDP; without it, ROS 2 nodes have no way to see PX4's uORB topics. +If you only need SIH plus QGroundControl, you can safely skip this section. + +The upstream [eProsima Micro-XRCE-DDS-Agent](https://github.com/eProsima/Micro-XRCE-DDS-Agent) builds out of the box on Linux but hits two Windows-specific issues in its CMake superbuild that need a workaround. +The two-stage build below is a known-good recipe — it produces the same `MicroXRCEAgent.exe` binary you would get from the one-shot build on Linux. + +### Prerequisites + +- The same _Visual Studio 2022 Build Tools_ install you already use for `make px4_sitl_default` — no extra components required. +- A real `ninja-build` from `winget install Ninja-build.Ninja` (verified with 1.13.2 or newer). + + ::: warning + Do **not** use the `ninja` package from `pip install ninja`. + The pip-distributed Ninja triggers the recompaction issue described in [Known Limitations](#known-limitations) deterministically, even if the rest of the workaround is in place. + Run `where.exe ninja` from the build shell and confirm the resolved path is `C:\Program Files\Ninja\ninja.exe` (or wherever winget placed it) and **not** something under a Python `Scripts\` directory. + ::: + +- Git, CMake, and Python 3 — already on `PATH` from the main [Install the Toolchain](#install-the-toolchain) step above; nothing extra to install. + +All `cmake` commands below must be run from a shell where the MSVC environment is loaded — either the _x64 Native Tools Command Prompt for VS 2022_ or a regular _PowerShell_ window into which you have sourced `vcvars64.bat` (see [`cl.exe` Not Found (MSVC)](#cl-exe-not-found-msvc) for the exact one-liner). + +### Clone the Agent Repository + +Pick a directory outside the `PX4-Autopilot` tree (the agent is independent of PX4 and lives on its own release cadence). The rest of this section assumes `C:\Users\\Documents\Micro-XRCE-DDS-Agent`: + +```powershell +$agentRoot = "$env:USERPROFILE\Documents\Micro-XRCE-DDS-Agent" +git clone --recursive https://github.com/eProsima/Micro-XRCE-DDS-Agent.git $agentRoot +cd $agentRoot +``` + +### Stage 1 — Build the Dependencies + +The agent's CMake project ships a _superbuild_ that, in one configure step, fetches and builds its four direct dependencies (`foonathan_memory`, `fastcdr`, `spdlog`, `fastdds`) and then the agent itself. +On Windows the dependency phase succeeds, but the subsequent inner reconfigure of the `uagent` ExternalProject reuses the outer build directory and fails to recompact `build.ninja` while the parent `ninja` still has it open. +The pragmatic workaround is to let the superbuild install the four dependencies and then build the agent in a separate directory in [Stage 2](#stage-2-build-the-agent-standalone). + +From the agent root, in a shell with `vcvars64.bat` loaded: + +```powershell +cmake -G Ninja -S . -B build ` + -DCMAKE_BUILD_TYPE=Release ` + -DCMAKE_INSTALL_PREFIX="$agentRoot\install" ` + -DUAGENT_P2P_PROFILE=OFF ` + -DUAGENT_BUILD_EXECUTABLE=ON +cmake --build build --target install +``` + +`-DUAGENT_P2P_PROFILE=OFF` is required: the peer-to-peer profile pulls in the `microxrcedds_client` ExternalProject, whose own ninja recompaction step fails on Windows for the same reason. PX4's `uxrce_dds_client` does not use the P2P feature, so disabling it has no functional impact on the SITL ↔ ROS 2 use case. + +::: info +This stage takes around **10 minutes** on a typical workstation — most of it is fastdds, which compiles a large amount of generated IDL code. +::: + +The build will report success for the four dependencies and then fail when it reaches the `uagent` step with output similar to: + +``` +ninja: error: failed recompaction: Permission denied +``` + +**That failure is expected.** Confirm that the four dependency installs landed under `$agentRoot\install\` (`install\include\fastcdr\`, `install\lib\foonathan_memory\`, etc.) before moving on. If those directories are missing, the dependency phase did not actually succeed and re-running Stage 2 will not recover. + +### Stage 2 — Build the Agent Standalone + +With the dependencies installed under `$agentRoot\install`, configure a fresh build directory that points the agent's CMake at the now-prebuilt deps and skips the superbuild orchestration: + +```powershell +cmake -G Ninja -S . -B build_uagent ` + -DUAGENT_SUPERBUILD=OFF ` + -DCMAKE_PREFIX_PATH="$agentRoot\install" ` + -DCMAKE_INSTALL_PREFIX="$agentRoot\install" ` + -DUAGENT_BUILD_EXECUTABLE=ON +cmake --build build_uagent --target install +``` + +`-DUAGENT_SUPERBUILD=OFF` flips the agent's top-level `CMakeLists.txt` from "fetch + build everything" mode to "I have all the deps already — just build me", which sidesteps the inner ExternalProject reconfigure that hit `build.ninja` in Stage 1. +`CMAKE_PREFIX_PATH` is how Stage 2 finds the `fastcdr`, `fastdds`, `foonathan_memory`, and `spdlog` packages that Stage 1 installed. + +This stage takes under a minute on most machines. + +### Verifying a Successful Build + +When Stage 2 finishes, the install tree should contain: + +- `install\bin\MicroXRCEAgent.exe` — the agent itself. +- `install\bin\fastcdr-2.2.dll` and `install\bin\fastdds-3.6.dll` (or whatever the current upstream version numbers are) staged alongside the executable. These are loaded at startup by `MicroXRCEAgent.exe` and the agent will fail to launch with a Windows error dialog if they are missing. + +If the DLLs are not in `install\bin\`, copy them over from `install\lib\` — different upstream tags occasionally install them under `lib\` only. + +### Running the Agent for SITL + +Start the agent listening on UDP 8888 (the default that PX4's `uxrce_dds_client` connects to) from any _PowerShell_ window — `vcvars64` is **not** required for running, only for building: + +```powershell +& "$env:USERPROFILE\Documents\Micro-XRCE-DDS-Agent\install\bin\MicroXRCEAgent.exe" udp4 -p 8888 -v 6 +``` + +`-v 6` selects the most verbose log level, which is useful while you are first verifying that PX4 connects; lower it (`-v 4` or omit the flag) once everything is working. + +Then, in a separate _PowerShell_ window, launch PX4 SITL as usual (`make px4_sitl_default sihsim_quadx`). Within a few seconds, the agent window should print `create_client | session_id: 0x...` and the matching ROS 2 / DDS topics will appear in your DDS subscriber. + +For the wider ROS 2 / DDS workflow on top of this connection (workspace layout, `px4_msgs`, namespacing), see the [uXRCE-DDS bridge documentation](../middleware/uxrce_dds.md) — the agent built here is the same binary that those instructions assume, just compiled natively on Windows. + +### Known Limitations + +- **Two-stage build is mandatory on Windows.** The upstream superbuild reuses the outer build directory when reconfiguring the `uagent` ExternalProject, and the parent `ninja` process still holds `build.ninja` open at that point. Ninja then fails its recompaction step with `Permission denied` (Windows file-locking semantics — POSIX `unlink()`-while-open does not have an equivalent here). Track upstream progress at [eProsima/Micro-XRCE-DDS-Agent issues](https://github.com/eProsima/Micro-XRCE-DDS-Agent/issues); until a fix lands, the two-stage workaround above is the supported path. +- **Use the winget-installed Ninja.** The `ninja` package distributed via `pip` reproduces the recompaction failure deterministically even with the workaround applied. `winget install Ninja-build.Ninja` ships a build that handles the lock contention gracefully on the dependency phase, which is what makes the two-stage recipe viable in the first place. +- **`UAGENT_P2P_PROFILE=ON` is not supported on Windows today.** The peer-to-peer profile triggers a separate, earlier recompaction failure inside the `microxrcedds_client` ExternalProject. PX4's SITL bridge does not use P2P, so leaving it off is safe. + +## Next Steps + +Once you have finished setting up the command-line toolchain: + +- Install [VS Code](../dev_setup/vscode.md) (if you prefer using an IDE to the command line). +- Install the [QGroundControl Daily Build](../dev_setup/qgc_daily_build.md). +- Continue to [Building PX4 Software](../dev_setup/building_px4.md). + +## Troubleshooting + +### Common Pitfalls + +- **A freshly-installed command is _"not recognized"_ in the same shell that ran the setup script.** The setup script updates the user `PATH` for the current process, but Windows does not propagate registry `PATH` changes into shells that were already open. **Close every terminal window and open a new one** — including any IDE-integrated terminals — and the missing command will resolve. +- **`winget` itself prints _"is not recognized"_.** _App Installer_ is missing or out of date. Open the Microsoft Store, search for _App Installer_, install or update it, then reopen the terminal. +- **The build appears to hang for several minutes the first time.** CMake configures the project and downloads several upstream dependencies on the first run; that part is silent. Subsequent rebuilds are incremental and complete in seconds. +- **`pxh>` keeps emitting `INFO [mavlink] partner IP: 127.0.0.1`.** This is the normal MAVLink heartbeat exchange with QGroundControl (or any other connected GCS). It is not an error. +- **The first launch of `px4.exe` shows a _Windows Defender Firewall_ prompt.** See [Connecting QGroundControl](#connecting-qgroundcontrol) above. +- **The `pxh>` prompt won't respond.** From a different PowerShell window, kill all running PX4 instances with `Get-Process px4 -ErrorAction SilentlyContinue | Stop-Process -Force`. The same one-liner cleans up the background instances launched by `Tools\simulation\sitl_multiple_run.ps1`. Passing `-SitlNum 0` to the helper script also works: `.\Tools\simulation\sitl_multiple_run.ps1 -SitlNum 0`. +- **`PX4 server already running for instance 0` on a fresh launch.** If the previous `px4.exe` was killed forcibly (`Stop-Process -Force`, Task Manager, `CTRL+BREAK`) it may not have unlinked its lock file under `%TEMP%`, so the next launch sees a stale `px4_lock-` and exits. Clear the leftovers and re-launch: `Remove-Item "$env:TEMP\px4_lock-*" -ErrorAction SilentlyContinue`. A graceful shutdown (`shutdown` from `pxh>`, `px4-shutdown.exe`, or `CTRL+C`) removes the lock automatically. + +### `make` Not Found + +PowerShell and CMD do not ship `make`, so the Makefile entry point fails until either `ezwinports.make` (winget) or `make` from Chocolatey is installed. +The setup script installs it for you; to install it manually, run: + +```sh +winget install --id ezwinports.make -e +``` + +### `cl.exe` Not Found (MSVC) + +CMake searches `PATH` for `cl.exe`; the MSVC compiler is only on `PATH` inside a Visual Studio developer shell. +Either launch the build from _x64 Native Tools Command Prompt for VS 2022_ (Start menu → _Visual Studio 2022_ → _Visual Studio Tools_ → _VC_), or source the developer environment into an existing _PowerShell_ window with `vcvars64.bat`. +Use the path that matches your install — the bundled setup script installs the _Build Tools_ edition: + +```sh +# Build Tools (installed by Tools\setup\windows.ps1) +& "C:\Program Files\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat" + +# Visual Studio 2022 Community +& "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat" +``` + +The leading `&` is the PowerShell call operator; from CMD, drop it and run the path directly (e.g. `"C:\Program Files\...\vcvars64.bat"`). + +### `mingw-w64` Not Found (MinGW) + +The MinGW toolchain file (`platforms/posix/cmake/Toolchain-mingw-w64-x86_64.cmake`) searches `C:\msys64\mingw64\bin` and `$env:MINGW_PREFIX\bin` for the GCC binaries. +If you installed MSYS2 to a non-default location, set `MINGW_PREFIX` before running `make`: + +```sh +$env:MINGW_PREFIX = "D:\msys64\mingw64" +``` + +### Antivirus Slowing Builds + +Real-time scanning of every object file produced by the build can slow compilation by an order of magnitude. +Adding the PX4-Autopilot directory to _Windows Defender_'s exclusion list under **Windows Security > Virus & threat protection > Manage settings > Exclusions** typically restores normal build times. diff --git a/docs/en/dev_setup/dev_env_windows_wsl.md b/docs/en/dev_setup/dev_env_windows_wsl.md index 98e640124e..54dc920976 100644 --- a/docs/en/dev_setup/dev_env_windows_wsl.md +++ b/docs/en/dev_setup/dev_env_windows_wsl.md @@ -2,6 +2,10 @@ The following instructions explain how to set up a PX4 development environment on Windows 10 or 11, running on Ubuntu Linux within [WSL2](https://learn.microsoft.com/en-us/windows/wsl/about). +::: info +For a non-WSL build that produces a native `px4.exe` from CMD or PowerShell — limited to [SIH](../sim_sih/index.md) for SITL — see [Windows Native (CMD/PowerShell)](../dev_setup/dev_env_windows_native.md). +::: + This environment can be used to build PX4 for: - [Pixhawk and other NuttX-based hardware](../dev_setup/building_px4.md#nuttx-pixhawk-based-boards) @@ -33,7 +37,7 @@ _QGroundControl for Windows_ is additionally required if you need to: Note that you can also use it to monitor a simulation, but you must manually [connect to the simulation running in WSL](#qgroundcontrol-on-windows). ::: info -Connecting to an USB device from within WSL is not natively supported, however it can still be achieved by using the [USBIPD-WIN](https://learn.microsoft.com/en-us/windows/wsl/connect-usb) project. With this you can automatically upload firmware from the command line in WSL using the [`upload`](../dev_setup/building_px4.md#uploading-firmware-flashing-the-board) function. +Connecting to a USB device from within WSL is not natively supported, however it can still be achieved by using the [USBIPD-WIN](https://learn.microsoft.com/en-us/windows/wsl/connect-usb) project. With this you can automatically upload firmware from the command line in WSL using the [`upload`](../dev_setup/building_px4.md#uploading-firmware-flashing-the-board) function. ::: ::: info @@ -47,8 +51,8 @@ The benefit of WSL2 is that its virtual machine is deeply integrated into Window To install WSL2 with Ubuntu on a new installation of Windows 10 or 11: -1. Make sure your computer your computer's virtualization feature is enabled in the BIOS. - It's usually referred as "Virtualization Technology", "Intel VT-x" or "AMD-V" respectively +1. Make sure your computer's virtualization feature is enabled in the BIOS. + It's usually referred to as "Virtualization Technology", "Intel VT-x" or "AMD-V". 1. Open _cmd.exe_ as administrator. This can be done by pressing the start key, typing `cmd`, right-clicking on the _Command prompt_ entry and selecting **Run as administrator**. 1. Execute the following commands to install WSL2 and a particular Ubuntu version: @@ -71,7 +75,7 @@ To install WSL2 with Ubuntu on a new installation of Windows 10 or 11: ``` ::: info - You can also [Ubuntu 24.04](https://www.microsoft.com/store/productId/9nz3klhxdjp5) or [Ubuntu 22.04](https://www.microsoft.com/store/productId/9PN20MSR04DW) from Microsoft Store, which allows you to delete the application using the normal Windows Add/Remove settings. + You can also install [Ubuntu 24.04](https://www.microsoft.com/store/productId/9nz3klhxdjp5) or [Ubuntu 22.04](https://www.microsoft.com/store/productId/9PN20MSR04DW) from the Microsoft Store, which allows you to delete the application using the normal Windows Add/Remove settings. ::: 1. WSL will prompt you for a user name and password for the Ubuntu installation. @@ -156,7 +160,7 @@ To install the development toolchain: This installs tools to build PX4 for Pixhawk and either Gazebo or Gazebo Classic targets: - You can use the `--no-nuttx` and `--no-sim-tools` options to omit the NuttX and/or simulation tools. - Other Linux build targets are untested (you can try these by entering the appropriate commands in [Ubuntu Development Environment](../dev_setup/dev_env_linux_ubuntu.md) into the WSL shell). - ::: + ::: 1. Restart the "WSL computer" after the script completes (exit the shell, shutdown WSL, and restart WSL): @@ -211,7 +215,7 @@ To set up the integration: ![](../../assets/toolchain/vscode/vscode_wsl.png) - Note however that the IP address of the WSL virtual machine will have changed, so you won't be able to monitor simulation from QGC for Windows (you can still monitor using QGC for Linux) + Note however that the IP address of the WSL virtual machine will have changed, so you won't be able to monitor simulation from QGC for Windows (you can still monitor using QGC for Linux). ## QGroundControl @@ -227,7 +231,7 @@ You can do this from within the WSL shell. 1. In a web browser, navigate to the QGC [Ubuntu download section](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html#ubuntu) 1. Right-click on the **QGroundControl.AppImage** link, and select "Copy link address". This will be something like _https://d176td9ibe4jno.cloudfront.net/builds/master/QGroundControl.AppImage_ -1. [Open a WSL shell](#opening-a-wsl-shell) and enter the following commands to download the appimage and make it executable (replace the AppImage URL where indicated): +1. [Open a WSL shell](#opening-a-wsl-shell) and enter the following commands to download the AppImage and make it executable (replace the AppImage URL where indicated): ```sh cd ~ @@ -298,7 +302,7 @@ Do the following steps to flash your custom binary built in WSL: 1. Detach the USB cable of your Pixhawk board from the computer if it was connected. 1. Open QGC and navigate to **Q > Vehicle Setup > Firmware**. -1. Plug your Pixhawk board via USB +1. Plug in your Pixhawk board via USB. 1. Once connected select "PX4 Flight Stack", check **Advanced settings** and choose _Custom firmware file ..._ from the drop down below. 1. Continue and select the firmware binary you just built in WSL. @@ -330,4 +334,4 @@ sudo apt upgrade - The connection between PX4 SITL on WSL2 and QGroundControl on Windows requires [broadcasting](../simulation/index.md#enable-udp-broadcasting) or [streaming to a specific address](../simulation/index.md#enable-streaming-to-specific-address) to be enabled. Streaming to a specific address should be enabled by default, but is something to check if a connection can't be established. -- Network traffic might be blocked by firewall or antivirus on you system. +- Network traffic might be blocked by firewall or antivirus on your system. diff --git a/docs/en/middleware/uxrce_dds.md b/docs/en/middleware/uxrce_dds.md index d00e0cf928..8538f3b668 100644 --- a/docs/en/middleware/uxrce_dds.md +++ b/docs/en/middleware/uxrce_dds.md @@ -65,6 +65,10 @@ This section summarises the options that have been tested with PX4 during creati PX4 Micro XRCE-DDS Client is based on version `v2.x` which is not compatible with the latest `v3.x` Agent version. ::: +::: info +**Windows native:** the snap and Ubuntu source-build paths below do not apply. On Windows you install ROS 2 via the Pixi helper [`Tools/setup/ros2_pixi_setup.ps1`](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/setup/ros2_pixi_setup.ps1) (defaults to Jazzy LTS; pass `-Distro rolling` or `-Distro latest` for newer releases) and build the agent natively with the two-stage MSVC recipe documented in [Windows Native Development Environment > Building the Micro-XRCE-DDS Agent](../dev_setup/dev_env_windows_native.md#building-the-micro-xrce-dds-agent-optional-for-ros-2-dds-bridging). +::: + ### Install Standalone from Source On Ubuntu you can build from source and install the Agent standalone using the following commands: diff --git a/docs/en/ros2/multi_vehicle.md b/docs/en/ros2/multi_vehicle.md index abed4ee206..f57020a89c 100644 --- a/docs/en/ros2/multi_vehicle.md +++ b/docs/en/ros2/multi_vehicle.md @@ -36,6 +36,10 @@ The environment variable `PX4_UXRCE_DDS_NS`, if set, will override the namespace The first instance (`px4_instance=0`) does not have an additional namespace in order to be consistent with the default behavior of the `xrce-dds` client on a real vehicle. This mismatch can be fixed by manually using `PX4_UXRCE_DDS_NS` on the first instance or by starting adding vehicles from index `1` instead of `0` (this is the default behavior adopted by [sitl_multiple_run.sh](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/simulation/gazebo-classic/sitl_multiple_run.sh) for Gazebo Classic). +::: info Windows native +On Windows use the PowerShell launcher [`Tools\simulation\sitl_multiple_run.ps1`](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/simulation/sitl_multiple_run.ps1). Ad-hoc `px4.exe -i N` invocations auto-create a per-instance work dir, so multi-instance ROS 2 setups work with the same `UXRCE_DDS_KEY` / namespace rules as Linux. See [Windows Native Development Environment](../dev_setup/dev_env_windows_native.md). +::: + The default client configuration in simulation is summarized as follows: | `PX4_UXRCE_DDS_NS` | `px4_instance` | `UXRCE_DDS_KEY` | client namespace | diff --git a/docs/en/ros2/user_guide.md b/docs/en/ros2/user_guide.md index a06c6d05c5..b42c46229b 100644 --- a/docs/en/ros2/user_guide.md +++ b/docs/en/ros2/user_guide.md @@ -131,6 +131,10 @@ To install ROS 2 and its dependencies: :::: + ::: info + **Windows native users:** the Ubuntu `apt` recipe above does not apply. ROS 2 on Windows ships as a Pixi/`conda-forge` bundle; install it with the bundled helper [`Tools/setup/ros2_pixi_setup.ps1`](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/setup/ros2_pixi_setup.ps1) — defaults to Jazzy LTS, pass `-Distro rolling` or `-Distro latest` to pick a newer release — and activate it via `$env:TEMP\activate_ros2.ps1` (or `activate_ros2_.ps1`). See [Windows Native Development Environment > ROS 2 Setup on Windows Native](../dev_setup/dev_env_windows_native.md#ros-2-setup-on-windows-native) for the full walkthrough. + ::: + 1. Some Python dependencies must also be installed (using **`pip`** or **`apt`**): ```sh @@ -146,6 +150,10 @@ For ROS 2 to communicate with PX4, [uXRCE-DDS client](../modules/modules_system. The agent can be installed onto the companion computer in a [number of ways](../middleware/uxrce_dds.md#micro-xrce-dds-agent-installation). Below we show how to build the agent "standalone" from source and connect to a client running on the PX4 simulator. +::: info Windows native +The Linux `cmake .. && make && sudo make install` recipe below does not apply on Windows. Build `MicroXRCEAgent.exe` with the two-stage MSVC recipe in [Windows Native Development Environment > Building the Micro-XRCE-DDS Agent](../dev_setup/dev_env_windows_native.md#building-the-micro-xrce-dds-agent-optional-for-ros-2-dds-bridging) and run it from PowerShell with `fastcdr-2.2.dll` / `fastdds-3.6.dll` co-located on `PATH`. +::: + To setup and start the agent: 1. Open a terminal. @@ -233,6 +241,10 @@ The micro XRCE-DDS agent terminal should also start to show output, as equivalen This section shows how to create a ROS 2 workspace hosted in your home directory (modify the commands as needed to put the source code elsewhere). +::: info Windows native +On Windows replace `source /opt/ros//setup.bash` with `. $env:TEMP\activate_ros2.ps1 -WithVcvars` before running `colcon build` — `conda-forge` ships no MSVC, so `colcon` needs `vcvars64.bat` sourced in the same shell. See [Windows Native Development Environment > ROS 2 Setup on Windows Native](../dev_setup/dev_env_windows_native.md#ros-2-setup-on-windows-native). +::: + The [px4_ros_com](https://github.com/PX4/px4_ros_com) and [px4_msgs](https://github.com/PX4/px4_msgs) packages are cloned to a workspace folder, and then the `colcon` tool is used to build the workspace. The example is run using `ros2 launch`. diff --git a/docs/en/sim_jmavsim/multi_vehicle.md b/docs/en/sim_jmavsim/multi_vehicle.md index 68b8a7217d..8cf8f255db 100644 --- a/docs/en/sim_jmavsim/multi_vehicle.md +++ b/docs/en/sim_jmavsim/multi_vehicle.md @@ -25,6 +25,10 @@ To start multiple instances (on separate ports): ./Tools/sitl_multiple_run.sh 2 ``` + ::: info Windows native + On Windows use the PowerShell variant `Tools\simulation\sitl_multiple_run.ps1`. Per-instance work dirs are created automatically — see [Windows Native Development Environment](../dev_setup/dev_env_windows_native.md). + ::: + 1. Start the first instance in the same terminal (this will run in the foreground): ```sh diff --git a/docs/en/sim_sih/index.md b/docs/en/sim_sih/index.md index 9823ebd594..49b20e19b2 100644 --- a/docs/en/sim_sih/index.md +++ b/docs/en/sim_sih/index.md @@ -33,11 +33,11 @@ The following vehicle types are supported: | Vehicle | Make Target | Status | | --------------------------------------------------------------- | ---------------------------------------- | ------------ | | Quadrotor X | `make px4_sitl_sih sihsim_quadx` | Stable | -| Hexarotor X | `make px4_sitl_sih sihsim_hexa` | Experimental | +| Hexarotor X | `make px4_sitl_sih sihsim_hex` | Experimental | | Fixed-wing (airplane) | `make px4_sitl_sih sihsim_airplane` | Experimental | | Tailsitter VTOL | `make px4_sitl_sih sihsim_xvert` | Experimental | | Standard VTOL (QuadPlane) | `make px4_sitl_sih sihsim_standard_vtol` | Experimental | -| Ackermann Rover | `make px4_sitl_sih sihsim_rover` | Experimental | +| Ackermann Rover | `make px4_sitl_sih sihsim_rover_ackermann` | Experimental | ::: warning Only the quadrotor vehicle type is stable and recommended for development. All other vehicle types (hexarotor, fixed-wing, VTOL, rover) are experimental and may have aerodynamic model or controller interaction issues that produce unrealistic flight behaviour. @@ -148,6 +148,10 @@ To use SIH with ROS 2: MicroXRCEAgent udp4 -p 8888 ``` +::: info Windows native +On Windows, build `MicroXRCEAgent.exe` with the two-stage MSVC recipe in [Windows Native Development Environment > Building the Micro-XRCE-DDS Agent](../dev_setup/dev_env_windows_native.md#building-the-micro-xrce-dds-agent-optional-for-ros-2-dds-bridging) and run it from PowerShell — the runtime DLLs (`fastcdr-2.2.dll`, `fastdds-3.6.dll`) must sit on `PATH` or next to the executable. +::: + See [uXRCE-DDS (PX4-ROS 2/DDS Bridge)](../middleware/uxrce_dds.md) for full setup instructions, including agent installation and ROS 2 workspace configuration. ### Port Reference @@ -182,6 +186,10 @@ Then use the multi-instance launch script: ./Tools/simulation/sitl_multiple_run.sh 3 sihsim_quadx px4_sitl_sih ``` +::: info Windows native +On Windows use the PowerShell variant `Tools\simulation\sitl_multiple_run.ps1` instead. Ad-hoc `px4.exe -i N` invocations auto-create per-instance work dirs (no manual `etc` setup needed). See [Windows Native Development Environment](../dev_setup/dev_env_windows_native.md). +::: + Or launch instances manually: ```sh