mirror of
https://github.com/PX4/PX4-Autopilot.git
synced 2026-05-21 21:55:34 +08:00
docs(windows): add native SITL setup guide
Document the native Windows development environment, setup scripts, SITL usage, and related ROS 2 / simulation notes while keeping the existing WSL and Cygwin pages linked clearly.
This commit is contained in:
Nuno Marques
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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.
|
||||
:::
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -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:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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_<distro>.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/<distro>/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`.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -33,11 +33,11 @@ The following vehicle types are supported:
|
||||
| Vehicle | Make Target | Status |
|
||||
| --------------------------------------------------------------- | ---------------------------------------- | ------------ |
|
||||
| Quadrotor X <Badge type="tip" text="PX4 v1.9" /> | `make px4_sitl_sih sihsim_quadx` | Stable |
|
||||
| Hexarotor X <Badge type="tip" text="PX4 v1.16" /> | `make px4_sitl_sih sihsim_hexa` | Experimental |
|
||||
| Hexarotor X <Badge type="tip" text="PX4 v1.16" /> | `make px4_sitl_sih sihsim_hex` | Experimental |
|
||||
| Fixed-wing (airplane) <Badge type="tip" text="PX4 v1.13" /> | `make px4_sitl_sih sihsim_airplane` | Experimental |
|
||||
| Tailsitter VTOL <Badge type="tip" text="PX4 v1.13" /> | `make px4_sitl_sih sihsim_xvert` | Experimental |
|
||||
| Standard VTOL (QuadPlane) <Badge type="tip" text="PX4 v1.16" /> | `make px4_sitl_sih sihsim_standard_vtol` | Experimental |
|
||||
| Ackermann Rover <Badge type="tip" text="PX4 v1.16" /> | `make px4_sitl_sih sihsim_rover` | Experimental |
|
||||
| Ackermann Rover <Badge type="tip" text="PX4 v1.16" /> | `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
|
||||
|
||||
Reference in New Issue
Block a user