Mirrors_Framework/PX4-Autopilot
1
0
Fork 0
mirror of https://github.com/PX4/PX4-Autopilot.git synced 2026-05-10 06:39:25 +08:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

docs(sim): restructure hardware sim pages and add SIH docs

Browse Source 
Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
This commit is contained in:
Ramon Roche
2026-03-05 14:48:39 -08:00
parent 01dd41b7e8
commit 1d80fc317e
11 changed files with 596 additions and 339 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/assets/simulation/sih_overview.svg
+30
View File
@@ -0,0 +1,30 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 160" width="520" height="160" font-family="Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif">
<!-- Arrow marker -->
<defs>
<marker id="arrow" viewBox="0 0 10 7" refX="10" refY="3.5" markerWidth="10" markerHeight="7" orient="auto-start-reverse">
<path d="M 0 0 L 10 3.5 L 0 7 z" fill="#4a5568"/>
</marker>
</defs>
<!-- Left label: Actuator Outputs -->
<text x="20" y="72" font-size="13" fill="#4a5568" font-weight="500" text-anchor="start">Actuator</text>
<text x="20" y="90" font-size="13" fill="#4a5568" font-weight="500" text-anchor="start">Outputs</text>
<text x="20" y="108" font-size="11" fill="#718096" text-anchor="start">(uORB)</text>
<!-- Left arrow -->
<line x1="100" y1="80" x2="170" y2="80" stroke="#4a5568" stroke-width="2" marker-end="url(#arrow)"/>
<!-- SIH Module box -->
<rect x="180" y="30" width="160" height="100" rx="8" ry="8" fill="#edf2f7" stroke="#4a5568" stroke-width="2"/>
<text x="260" y="72" font-size="16" fill="#2d3748" font-weight="600" text-anchor="middle">SIH Module</text>
<text x="260" y="96" font-size="12" fill="#718096" text-anchor="middle">C++ / uORB</text>
<!-- Right arrow -->
<line x1="350" y1="80" x2="420" y2="80" stroke="#4a5568" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Right label: Simulated Sensor Data -->
<text x="432" y="72" font-size="13" fill="#4a5568" font-weight="500" text-anchor="start">Simulated</text>
<text x="432" y="90" font-size="13" fill="#4a5568" font-weight="500" text-anchor="start">Sensor Data</text>
<text x="432" y="108" font-size="11" fill="#718096" text-anchor="start">(uORB)</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.7 KiB

docs/en/SUMMARY.md
+4 -2
View File
@@ -466,6 +466,7 @@
- [Plugins](sim_gazebo_gz/plugins.md)
- [Gazebo Models Repository](sim_gazebo_gz/gazebo_models.md)
- [Multi-Vehicle Sim](sim_gazebo_gz/multi_vehicle_simulation.md)
- [SIH Simulation](sim_sih/index.md)
- [Gazebo Classic Simulation](sim_gazebo_classic/index.md)
- [Vehicles](sim_gazebo_classic/vehicles.md)
- [Worlds](sim_gazebo_classic/worlds.md)
@@ -849,8 +850,9 @@
- [Multi-Vehicle Sim with JMAVSim](sim_jmavsim/multi_vehicle.md)
- [JSBSim Simulation](sim_jsbsim/index.md)
- [AirSim Simulation](sim_airsim/index.md)
- [HITL Simulation](simulation/hitl.md)
- [Simulation-In-Hardware](sim_sih/index.md)
- [Hardware Simulation](simulation/hardware.md)
- [HITL Simulation](simulation/hitl.md)
- [SIH on Hardware](sim_sih/hardware.md)
- [Multi-vehicle simulation](simulation/multi-vehicle-simulation.md)
- [Platform Testing and CI](test_and_ci/index.md)
- [Test Flights](test_and_ci/test_flights.md)
docs/en/dev_setup/building_px4.md
+1 -1
View File
@@ -263,7 +263,7 @@ make [VENDOR_][MODEL][_VARIANT] [VIEWER_MODEL_DEBUGGER_WORLD]
- **VENDOR:** The manufacturer of the board: `px4`, `aerotenna`, `airmind`, `atlflight`, `auav`, `beaglebone`, `intel`, `nxp`, etc.
The vendor name for Pixhawk series boards is `px4`.
- **MODEL:** The _board model_ "model": `sitl`, `fmu-v2`, `fmu-v3`, `fmu-v4`, `fmu-v5`, `navio2`, etc.
- **VARIANT:** Indicates particular configurations: e.g. `bootloader`, `cyphal`, which contain components that are not present in the `default` configuration.
- **VARIANT:** Indicates particular configurations: e.g. `bootloader`, `cyphal`, `sih`, which add or remove components to/from the `default` configuration.
Most commonly this is `default`, and may be omitted.
:::tip
docs/en/sim_jmavsim/index.md
+95 -28
View File
@@ -22,36 +22,31 @@ jMAVSim can also be used for HITL Simulation ([as shown here](../simulation/hitl
## Installation
jMAVSim setup is included in our [standard build instructions](../dev_setup/dev_env.md) for Ubuntu Linux and Windows.
Follow the instructions below to install jMAVSim on macOS.
jMAVSim requires JDK 17 or later.
On Ubuntu and Windows, the [standard development environment setup](../dev_setup/dev_env.md) scripts install all required dependencies including Java.
On macOS, you need to install Java manually as shown below.
### macOS
To setup the environment for [jMAVSim](../sim_jmavsim/index.md) simulation:
jMAVSim requires OpenJDK 17 or later.
Install it via Homebrew:
1. Install a recent version of Java (e.g. Java 15).
You can download [Java 15 (or later) from Oracle](https://www.oracle.com/java/technologies/downloads/?er=221886) or use [Eclipse Temurin](https://adoptium.net):
```sh
brew install openjdk@17
```
```sh
brew install --cask temurin
```
Homebrew installs OpenJDK but does not link it into your `PATH`, so you need to set `JAVA_HOME` for jMAVSim to find it.
Add this to your shell profile (e.g. `~/.zshrc`):
1. Install jMAVSim:
```sh
brew install px4-sim-jmavsim
```
:::warning
PX4 v1.11 and beyond require at least JDK 15 for jMAVSim simulation.
For earlier versions, macOS users might see the error `Exception in thread "main" java.lang.UnsupportedClassVersionError:`.
You can find the fix in the [jMAVSim with SITL > Troubleshooting](../sim_jmavsim/index.md#troubleshooting)).
:::
```sh
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
```
## Simulation Environment
Software in the Loop Simulation runs the complete system on the host machine and simulates the autopilot. It connects via local network to the simulator. The setup looks like this:
Software in the Loop Simulation runs the complete system on the host machine and simulates the autopilot.
It connects via local network to the simulator.
The setup looks like this:
[![Mermaid graph: SITL Simulator](https://mermaid.ink/img/eyJjb2RlIjoiZ3JhcGggTFI7XG4gIFNpbXVsYXRvci0tPk1BVkxpbms7XG4gIE1BVkxpbmstLT5TSVRMOyIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiZ3JhcGggTFI7XG4gIFNpbXVsYXRvci0tPk1BVkxpbms7XG4gIE1BVkxpbmstLT5TSVRMOyIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)
@@ -94,7 +89,8 @@ It will also bring up a window showing a 3D view of the [jMAVSim](https://github
## Taking it to the Sky
The system will start printing status information. You will be able to start flying once you have a position lock (shortly after the console displays the message: _EKF commencing GPS fusion_).
The system will start printing status information.
You will be able to start flying once you have a position lock (shortly after the console displays the message: _EKF commencing GPS fusion_).
To takeoff enter the following into the console:
@@ -196,8 +192,8 @@ Lockstep makes it possible to [change the simulation speed](#change-simulation-s
The sequence of steps for lockstep are:
1. The simulation sends a sensor message [HIL_SENSOR](https://mavlink.io/en/messages/common.html#HIL_SENSOR) including a timestamp `time_usec` to update the sensor state and time of PX4.
1. PX4 receives this and does one iteration of state estimation, controls, etc. and eventually sends an actuator message [HIL_ACTUATOR_CONTROLS](https://mavlink.io/en/messages/common.html#HIL_ACTUATOR_CONTROLS).
1. The simulation waits until it receives the actuator/motor message, then simulates the physics and calculates the next sensor message to send to PX4 again.
2. PX4 receives this and does one iteration of state estimation, controls, etc. and eventually sends an actuator message [HIL_ACTUATOR_CONTROLS](https://mavlink.io/en/messages/common.html#HIL_ACTUATOR_CONTROLS).
3. The simulation waits until it receives the actuator/motor message, then simulates the physics and calculates the next sensor message to send to PX4 again.
The system starts with a "freewheeling" period where the simulation sends sensor messages including time and therefore runs PX4 until it has initialized and responds with an actuator message.
@@ -217,11 +213,13 @@ To disable lockstep in:
## Extending and Customizing
To extend or customize the simulation interface, edit the files in the **Tools/jMAVSim** folder. The code can be accessed through the[jMAVSim repository](https://github.com/px4/jMAVSim) on Github.
To extend or customize the simulation interface, edit the files in the **Tools/jMAVSim** folder.
The code can be accessed through the[jMAVSim repository](https://github.com/px4/jMAVSim) on Github.
::: info
The build system enforces the correct submodule to be checked out for all dependencies, including the simulator.
It will not overwrite changes in files in the directory, however, when these changes are committed the submodule needs to be registered in the Firmware repo with the new commit hash. To do so, `git add Tools/jMAVSim` and commit the change.
It will not overwrite changes in files in the directory, however, when these changes are committed the submodule needs to be registered in the Firmware repo with the new commit hash.
To do so, `git add Tools/jMAVSim` and commit the change.
This will update the GIT hash of the simulator.
:::
@@ -234,6 +232,75 @@ The simulation can be [interfaced to ROS](../simulation/ros_interface.md) the sa
- The startup scripts are discussed in [System Startup](../concept/system_startup.md).
- The simulated root file system ("`/`" directory) is created inside the build directory here: `build/px4_sitl_default/rootfs`.
## Display-Only Mode
jMAVSim can run as a display-only renderer for other simulators (like [SIH](../sim_sih/index.md)), with its internal physics disabled.
In this mode, jMAVSim receives vehicle position via MAVLink and only renders the 3D view.
To use jMAVSim as a display for SIH running in SITL:
```sh
# Start SIH first
make px4_sitl_sih sihsim_quadx
# In another terminal, start jMAVSim in display-only mode
./Tools/simulation/jmavsim/jmavsim_run.sh -p 19410 -u -q -o # 19410 is the default SIH display port
```
For SIH running on flight controller hardware:
```sh
./Tools/simulation/jmavsim/jmavsim_run.sh -q -d /dev/ttyACM0 -b 2000000 -o
```
Use `-a` for airplane display or `-t` for tailsitter display.
## Command-Line Reference
The `jmavsim_run.sh` launch script accepts the following flags:
| Flag | Description |
| ------------- | ------------------------------------------------ |
| `-b <rate>` | Serial baud rate (default: 921600) |
| `-d <device>` | Serial device path (e.g., `/dev/ttyACM0`) |
| `-u` | Use UDP connection instead of serial |
| `-i <id>` | Simulated MAVLink system ID |
| `-p <port>` | UDP port (default: 14560) |
| `-q` | No interactive console |
| `-s <port>` | TCP serial port |
| `-r <rate>` | Render rate in Hz |
| `-l` | Enable lockstep |
| `-o` | Display-only mode (disable physics, render only) |
| `-a` | Use airplane model |
| `-t` | Use tailsitter model |
| `HEADLESS=1` | Environment variable: run without GUI window |
## How jMAVSim Works
jMAVSim is a Java-based lightweight simulator that communicates with PX4 via MAVLink HIL (Hardware-In-the-Loop) messages.
In normal mode:
1. PX4 sends actuator commands via [HIL_ACTUATOR_CONTROLS](https://mavlink.io/en/messages/common.html#HIL_ACTUATOR_CONTROLS).
2. jMAVSim runs its physics engine to compute the vehicle state.
3. jMAVSim sends sensor data back via [HIL_SENSOR](https://mavlink.io/en/messages/common.html#HIL_SENSOR) and [HIL_GPS](https://mavlink.io/en/messages/common.html#HIL_GPS).
In **display-only mode** (`-o` flag), jMAVSim disables its physics engine and only reads [HIL_STATE_QUATERNION](https://mavlink.io/en/messages/common.html#HIL_STATE_QUATERNION) messages to render the vehicle position.
This allows it to visualize vehicles from other simulators like SIH.
jMAVSim supports [lockstep synchronization](#lockstep) with PX4 (enabled with `-l` flag), ensuring deterministic simulation results.
## Keyboard Shortcuts
Camera modes in the jMAVSim 3D view:
| Key | Camera Mode |
| ------------- | ------------------------------------ |
| **F** | First person (attached to vehicle) |
| **S** | Stationary (fixed position) |
| **G** | Gimbal (follows vehicle orientation) |
| **(default)** | Third person follow |
## Troubleshooting
### java.long.NoClassDefFoundError
@@ -324,8 +391,8 @@ Exception in thread "main" java.lang.UnsupportedClassVersionError: me/drton/jmav
This error is telling you, you need a more recent version of Java in your environment.
Class file version 58 corresponds to jdk14, version 59 to jdk15, version 60 to jdk 16 etc.
To fix it under macOS, we recommend installing OpenJDK through homebrew
To fix it under macOS, install a newer OpenJDK via Homebrew:
```sh
brew install --cask adoptopenjdk16
brew install openjdk@17
```
docs/en/sim_sih/hardware.md
+170
View File
@@ -0,0 +1,170 @@
# SIH on Flight Controller Hardware
SIH can run directly on flight controller hardware with `SYS_HITL=2`.
This replaces real sensors with simulated data while running on the actual autopilot, useful for testing without propellers.
For a comparison of SIH and HITL on hardware, see [Hardware Simulation](../simulation/hardware.md).
## Firmware Builds with SIH
The SIH module is included in many, but not all, default firmware builds.
This list can change between PX4 releases. Always verify using the method in [Check if SIH is in Firmware](#check-if-sih-is-in-firmware).
The table below lists build targets that include SIH at the time of writing:
| Build Target | Board |
| ------------------------------------ | -------------------------- |
| `px4_fmu-v3_default` | Pixhawk 2 (Cube Black) |
| `px4_fmu-v4_default` | Pixhawk 3 Pro |
| `px4_fmu-v4pro_default` | Pixracer |
| `px4_fmu-v5_default` | Pixhawk 4 |
| `px4_fmu-v5x_default` | Pixhawk 5X |
| `px4_fmu-v6c_default` | Pixhawk 6C |
| `px4_fmu-v6c_raptor` | Pixhawk 6C (Raptor) |
| `px4_fmu-v6x_multicopter` | Pixhawk 6X (multicopter) |
| `auterion_fmu-v6s_default` | Auterion FMU-v6S |
| `auterion_fmu-v6x_default` | Auterion FMU-v6X |
| `holybro_durandal-v1_default` | Holybro Durandal |
| `holybro_kakuteh7_default` | Holybro Kakute H7 |
| `holybro_kakuteh7v2_default` | Holybro Kakute H7 V2 |
| `holybro_pix32v5_default` | Holybro Pix32 V5 |
| `cuav_nora_default` | CUAV Nora |
| `cuav_x7pro_default` | CUAV X7 Pro |
| `cuav_x25-evo_default` | CUAV X25 EVO |
| `cuav_x25-super_default` | CUAV X25 Super |
| `cubepilot_cubeyellow_default` | CubePilot Cube Yellow |
| `mro_pixracerpro_default` | MRO PixRacer Pro |
| `mro_x21_default` | MRO X2.1 |
| `mro_ctrl-zero-h7_default` | MRO Ctrl Zero H7 |
| `mro_ctrl-zero-h7-oem_default` | MRO Ctrl Zero H7 OEM |
| `mro_ctrl-zero-f7_default` | MRO Ctrl Zero F7 |
| `mro_ctrl-zero-f7-oem_default` | MRO Ctrl Zero F7 OEM |
| `mro_ctrl-zero-classic_default` | MRO Ctrl Zero Classic |
| `3dr_ctrl-zero-h7-oem-revg_default` | 3DR Ctrl Zero H7 OEM RevG |
| `modalai_fc-v1_default` | ModalAI FC V1 |
| `nxp_fmuk66-v3_default` | NXP FMUK66-V3 |
| `nxp_fmuk66-e_default` | NXP FMUK66-E |
| `radiolink_PIX6_default` | Radiolink PIX6 |
| `siyi_n7_default` | SIYI N7 |
| `sky-drones_smartap-airlink_default` | Sky-Drones SmartAP Airlink |
| `uvify_core_default` | UVify Core |
| `atl_mantis-edu_default` | ATL Mantis EDU |
| `av_x-v1_default` | AV X-V1 |
| `narinfc_h7_default` | NarinFC H7 |
| `thepeach_k1_default` | ThePeach K1 |
| `thepeach_r1_default` | ThePeach R1 |
| `airmind_mindpx-v2_default` | AirMind MindPX V2 |
| `beaglebone_blue_default` | BeagleBone Blue |
| `bluerobotics_navigator_default` | BlueRobotics Navigator |
| `emlid_navio2_default` | Emlid Navio2 |
| `px4_raspberrypi_default` | Raspberry Pi |
| `scumaker_pilotpi_default` | Scumaker PilotPi |
::: info
Some boards (e.g., `px4_fmu-v6x_default`, `cubepilot_cubeorange_default`) do not include SIH in their default build due to flash memory constraints.
You can add SIH to any board -- see [Check if SIH is in Firmware](#check-if-sih-is-in-firmware).
:::
## Requirements
- A flight controller with SIH module included in firmware (see [Firmware Builds with SIH](#firmware-builds-with-sih)).
- USB connection for QGroundControl.
- Optional: jMAVSim for 3D visualization via serial link (see [Visualization](#hardware-visualization)).
## Check if SIH is in Firmware
SIH is included in most default firmware builds. To verify, search for `sih` in the parameter list in QGroundControl. If `SIH_*` parameters are available, the module is included.
To add SIH to a custom build, enable it in the board configuration:
```txt
CONFIG_MODULES_SIMULATION_SIMULATOR_SIH=y
```
## Starting SIH
1. Connect the flight controller to QGroundControl via USB.
2. Set `SYS_HITL` parameter to `2`.
3. Reboot the flight controller.
4. The SIH module starts automatically and provides simulated sensor data.
Once running, the vehicle can be controlled from QGroundControl or an RC controller.
:::warning
To save flash memory on boards with limited storage, SIH can be built with only quadrotor support.
Set `SIH_VEHICLE_TYPE` before building to limit included vehicle models.
:::
## Visualization (Optional) {#hardware-visualization}
If you need a visual aid to see what the simulated vehicle is doing on hardware:
### QGroundControl
Connect the flight controller via USB. QGC shows the vehicle on the map view with attitude, position, and telemetry, the same as a real flight.
### jMAVSim (3D Display-Only)
jMAVSim can render a 3D view of the vehicle over a serial connection. No physics are simulated in jMAVSim -- it is display-only.
```sh
./Tools/simulation/jmavsim/jmavsim_run.sh -q -d /dev/ttyACM0 -b 2000000 -o
```
Where `/dev/ttyACM0` is the serial device for the flight controller.
On macOS, this is typically `/dev/tty.usbmodem*`.
## Controlling Actuators
:::warning
If you want to control throttling actuators in SIH, make sure to remove propellers for safety.
:::
In some scenarios, it may be useful to control an actuator while running SIH on hardware. For example, you might want to verify that winches or grippers are functioning correctly by checking the servo responses.
**To enable actuator control in SIH:**
1. Configure PWM parameters in the airframe file:
Ensure your airframe file includes the necessary parameters to map PWM outputs to the correct channels.
For example, if a servo is connected to MAIN 3 and you want to map it to AUX1 on your RC, use the following command:
`param set-default PWM_MAIN_FUNC3 407`
You can find a full list of available values for `PWM_MAIN_FUNCn` [here](../advanced_config/parameter_reference.md#PWM_MAIN_FUNC1). In this case, `407` maps the MAIN 3 output to AUX1 on the RC.
Alternatively, you can use the [`PWM_AUX_FUNCn`](../advanced_config/parameter_reference.md#PWM_AUX_FUNC1) parameters.
You may also configure the output as desired:
- Disarmed PWM: ([`PWM_MAIN_DISn`](../advanced_config/parameter_reference.md#PWM_MAIN_DIS1) / [`PWM_AUX_DIS1`](../advanced_config/parameter_reference.md#PWM_AUX_DIS1))
- Minimum PWM ([`PWM_MAIN_MINn`](../advanced_config/parameter_reference.md#PWM_MAIN_MIN1) / [`PWM_AUX_MINn`](../advanced_config/parameter_reference.md#PWM_AUX_MIN1))
- Maximum PWM ([`PWM_MAIN_MAXn`](../advanced_config/parameter_reference.md#PWM_MAIN_MAX1) / [`PWM_AUX_MAXn`](../advanced_config/parameter_reference.md#PWM_AUX_MAX1))
2. Manually start the PWM output driver
For safety, the PWM driver is not started automatically in SIH. To enable it, run the following command in the MAVLink shell:
```sh
pwm_out start
```
**And to disable it again:**
```sh
pwm_out stop
```
## Adding New Airframes (FC)
Airframe configuration for SIH on a flight controller differs from SITL in a few ways:
- Airframe file goes in `ROMFS/px4fmu_common/init.d/airframes` and follows the naming template `${ID}_${model_name}.hil`, where `ID` is the `SYS_AUTOSTART_ID` used to select the airframe, and `model_name` is the airframe model name.
- Add the model name in `ROMFS/px4fmu_common/init.d/airframes/CMakeLists.txt` to generate a corresponding make target.
- Actuators are configured with `HIL_ACT_FUNC*` parameters (not the usual `PWM_MAIN_FUNC*` parameters).
This is to avoid using the real actuator outputs in SIH.
Similarly, the bitfield for inverting individual actuator output ranges is `HIL_ACT_REV`, rather than `PWM_MAIN_REV`.
For general airframe setup (SIH parameters, EKF2 tuning), see [Adding New Airframes](index.md#adding-new-airframes) on the main SIH page.
For examples, see the `.hil` airframes in [ROMFS/px4fmu_common/init.d/airframes](https://github.com/PX4/PX4-Autopilot/tree/main/ROMFS/px4fmu_common/init.d/airframes).
docs/en/sim_sih/index.md
+181 -277
View File
File diff suppressed because it is too large Load Diff
docs/en/simulation/community_supported_simulators.md
+10 -7
View File
@@ -12,10 +12,13 @@ See [Toolchain Installation](../dev_setup/dev_env.md) for information about the
The tools have variable levels of support from their communities (some are well supported and others are not).
Questions about these tools should be raised on the [discussion forums](../contribute/support.md#forums-and-chat)
| Simulator | Description |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Simulation-In-Hardware](../sim_sih/index.md) (SIH) | <p>A simulator implemented in C++ as a PX4 module directly in the Firmware [code](https://github.com/PX4/PX4-Autopilot/tree/main/src/modules/simulation/simulator_sih). It can be ran in SITL directly on the computer or as an alternative to HITL offering a hard real-time simulation directly on the hardware autopilot. </p><p><strong>Supported Vehicles:</strong> Quad, Hexa, Plane, Tailsitter, Standard VTOL, Ackermann Rover</p> |
| [FlightGear](../sim_flightgear/index.md) | <p>A simulator that provides physically and visually realistic simulations. In particular it can simulate many weather conditions, including thunderstorms, snow, rain and hail, and can also simulate thermals and different types of atmospheric flows. [Multi-vehicle simulation](../sim_flightgear/multi_vehicle.md) is also supported.</p> <p><strong>Supported Vehicles:</strong> Plane, Autogyro, Rover</p> |
| [JMAVSim](../sim_jmavsim/index.md) | <p>A simple multirotor/quad simulator. This was previously part of the PX4 development toolchain but was removed in favour of [Gazebo](../sim_gazebo_gz/index.md).</p> <p><strong>Supported Vehicles:</strong> Quad</p> |
| [JSBSim](../sim_jsbsim/index.md) | <p>A simulator that provides advanced flight dynamics models. This can be used to model realistic flight dynamics based on wind tunnel data.</p> <p><strong>Supported Vehicles:</strong> Plane, Quad, Hex</p> |
| [AirSim](../sim_airsim/index.md) | <p>A cross platform simulator that provides physically and visually realistic simulations. This simulator is resource intensive, and requires a significantly more powerful computer than the other simulators described here.</p><p><strong>Supported Vehicles:</strong> Iris (MultiRotor model and a configuration for PX4 QuadRotor in the X configuration).</p> |
| Simulator | Description |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [FlightGear](../sim_flightgear/index.md) | <p>A simulator that provides physically and visually realistic simulations. In particular it can simulate many weather conditions, including thunderstorms, snow, rain and hail, and can also simulate thermals and different types of atmospheric flows. [Multi-vehicle simulation](../sim_flightgear/multi_vehicle.md) is also supported.</p> <p><strong>Supported Vehicles:</strong> Plane, Autogyro, Rover</p> |
| [JMAVSim](../sim_jmavsim/index.md) | <p>A simple multirotor/quad simulator. This was previously part of the PX4 development toolchain but was removed in favour of [Gazebo](../sim_gazebo_gz/index.md).</p> <p><strong>Supported Vehicles:</strong> Quad</p> |
| [JSBSim](../sim_jsbsim/index.md) | <p>A simulator that provides advanced flight dynamics models. This can be used to model realistic flight dynamics based on wind tunnel data.</p> <p><strong>Supported Vehicles:</strong> Plane, Quad, Hex</p> |
| [AirSim](../sim_airsim/index.md) | <p>A cross platform simulator that provides physically and visually realistic simulations. This simulator is resource intensive, and requires a significantly more powerful computer than the other simulators described here.</p><p><strong>Supported Vehicles:</strong> Iris (MultiRotor model and a configuration for PX4 QuadRotor in the X configuration).</p> |
:::tip
[Gazebo](../sim_gazebo_gz/index.md) and [SIH](../sim_sih/index.md) are the officially supported simulators. See the [Simulation](index.md) page for more information.
:::
docs/en/simulation/hardware.md
+29
View File
@@ -0,0 +1,29 @@
# Hardware Simulation
PX4 can run simulation directly on a real flight controller, replacing real sensors with simulated data, while otherwise executing the full flight stack on actual autopilot hardware.
::: info
Simulating PX4 on flight controller hardware exercises more flight stack code than SITL, and tests more of your hardware integration.
It can surface issues with running PX4 that might hidden when running on a desktop OS and hardware, or even a different flight controller board.
:::
Two simulation approaches are available, controlled by the [SYS_HITL](../advanced_config/parameter_reference.md#SYS_HITL) parameter:
- **[HITL Simulation](../simulation/hitl.md) (`SYS_HITL=1`):** An external simulator (Gazebo Classic or jMAVSim) runs physics on a companion computer and sends sensor data to the flight controller via MAVLink HIL messages. Requires a USB/UART connection and simulator setup.
- **[SIH on Hardware](../sim_sih/hardware.md) (`SYS_HITL=2`):** A C++ physics model runs directly on the flight controller itself. No external simulator, no companion computer, no MAVLink sensor data. Just set the parameter and reboot.
## HITL vs SIH {#comparision}
| | HITL (`SYS_HITL=1`) | SIH (`SYS_HITL=2`) |
| ----------------- | -------------------------------------------- | ---------------------------------------------------- |
| Physics model | External simulator (Gazebo Classic, jMAVSim) | Internal C++ module |
| Communication | MAVLink HIL messages | uORB (internal) |
| External process | Required | Not required |
| Setup complexity | Higher | Lower |
| Sensor simulation | Camera, lidar, etc. (via simulator) | IMU, GPS, baro, mag, airspeed only |
| Vehicle types | Quadcopter, Standard VTOL | Quad, Hex, FW, VTOL Tailsitter, Standard VTOL, Rover |
## When to Use Which
- Use **SIH** if you want the simplest possible setup. No external dependencies.
- Use **HITL** if you need an external physics engine, 3D visualization from Gazebo Classic, or camera/lidar sensor simulation that SIH does not provide.
docs/en/simulation/hitl.md
+10 -12
View File
@@ -12,20 +12,18 @@ This approach has the benefit of testing most of the actual flight code on the r
PX4 supports HITL for multicopters (using [jMAVSim](../sim_jmavsim/index.md) or [Gazebo Classic](../sim_gazebo_classic/index.md)) and VTOL (using Gazebo Classic).
<a id="compatible_airframe"></a>
For a comparison of HITL and SIH on hardware, see [Hardware Simulation](../simulation/hardware.md).
## HITL-Compatible Airframes
## HITL-Compatible Airframes {#compatible_airframe}
The set of compatible airframes vs simulators is:
| Airframe | `SYS_AUTOSTART` | Gazebo Classic | jMAVSim |
| ---------------------------------------------------------------------------------------------------------------- | --------------- | -------------- | ------- |
| [HIL Quadcopter X](../airframes/airframe_reference.md#copter_simulation_hil_quadcopter_x) | 1001 | Y | Y |
| [HIL Standard VTOL QuadPlane](../airframes/airframe_reference.md#vtol_standard_vtol_hil_standard_vtol_quadplane) | 1002 | Y |
| [HIL Standard VTOL QuadPlane](../airframes/airframe_reference.md#vtol_standard_vtol_hil_standard_vtol_quadplane) | 1002 | Y | |
<a id="simulation_environment"></a>
## HITL Simulation Environment
## HITL Simulation Environment {#simulation_environment}
With Hardware-in-the-Loop (HITL) simulation the normal PX4 firmware is run on real hardware.
JMAVSim or Gazebo Classic (running on a development computer) are connected to the flight controller hardware via USB/UART.
@@ -135,8 +133,8 @@ Make sure _QGroundControl_ is not running!
DONT_RUN=1 make px4_sitl_default gazebo-classic
```
1. Open the vehicle model's sdf file (e.g. **Tools/simulation/gazebo-classic/sitl_gazebo-classic/models/iris_hitl/iris_hitl.sdf**).
1. Replace the `serialDevice` parameter (`/dev/ttyACM0`) if necessary.
2. Open the vehicle model's sdf file (e.g. **Tools/simulation/gazebo-classic/sitl_gazebo-classic/models/iris_hitl/iris_hitl.sdf**).
3. Replace the `serialDevice` parameter (`/dev/ttyACM0`) if necessary.
::: info
The serial device depends on what port is used to connect the vehicle to the computer (this is usually `/dev/ttyACM0`).
@@ -144,7 +142,7 @@ Make sure _QGroundControl_ is not running!
The correct device will be the last one shown.
:::
1. Set up the environment variables:
4. Set up the environment variables:
```sh
source Tools/simulation/gazebo-classic/setup_gazebo.bash $(pwd) $(pwd)/build/px4_sitl_default
@@ -156,7 +154,7 @@ Make sure _QGroundControl_ is not running!
gazebo Tools/simulation/gazebo-classic/sitl_gazebo-classic/worlds/hitl_iris.world
```
1. Start _QGroundControl_.
5. Start _QGroundControl_.
It should autoconnect to PX4 and Gazebo Classic.
#### jMAVSim (Quadrotor only)
@@ -166,7 +164,7 @@ Make sure _QGroundControl_ is not running!
:::
1. Connect the flight controller to the computer and wait for it to boot.
1. Run jMAVSim in HITL mode:
2. Run jMAVSim in HITL mode:
```sh
./Tools/simulation/jmavsim/jmavsim_run.sh -q -s -d /dev/ttyACM0 -b 921600 -r 250
@@ -178,7 +176,7 @@ Make sure _QGroundControl_ is not running!
On Windows (including Cygwin) it would be the COM1 or another port - check the connection in the Windows Device Manager.
:::
1. Start _QGroundControl_.
3. Start _QGroundControl_.
It should autoconnect to PX4 and jMAVSim.
## Fly an Autonomous Mission in HITL
docs/en/simulation/index.md
+61 -11
View File
@@ -3,38 +3,79 @@
Simulators allow PX4 flight code to control a computer modeled vehicle in a simulated "world".
You can interact with this vehicle just as you might with a real vehicle, using _QGroundControl_, an offboard API, or a radio controller/gamepad.
:::tip
Simulation is a quick, easy, and most importantly, _safe_ way to test changes to PX4 code before attempting to fly in the real world.
It is also a good way to start flying with PX4 when you haven't yet got a vehicle to experiment with.
:::
PX4 supports both _Software In the Loop (SITL)_ simulation, where the flight stack runs on computer (either the same computer or another computer on the same network) and _Hardware In the Loop (HITL)_ simulation using a simulation firmware on a real flight controller board.
Information about available simulators and how to set them up are provided in the next section.
The other sections provide general information about how the simulator works, and are not required to _use_ the simulators.
:::tip
Simulation is a quick, easy, and most importantly, _safe_ way to test changes to PX4 code before attempting to fly in the real world.
It is also a good way to start flying with PX4 when you haven't yet got a vehicle to experiment with.
:::
## Supported Simulators
The following simulators are supported by the PX4 core development team.
:::info
Gazebo Classic is being downgraded to [community supported](../simulation/community_supported_simulators.md) and is no longer recommended as the default simulation solution.
Use [Gazebo](../sim_gazebo_gz/index.md) (formerly Gazebo Ignition) for new projects.
If you have an older workflow that does not yet work in newer Gazebo, Gazebo Classic remains available but will not receive core team maintenance going forward.
See [PX4-Autopilot#23602](https://github.com/PX4/PX4-Autopilot/issues/23602) for the deprecation timeline and migration status.
:::
| Simulator | Description |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Gazebo](../sim_gazebo_gz/index.md) | Gazebo supersedes [Gazebo Classic](../sim_gazebo_classic/index.md), featuring more advanced rendering, physics and sensor models. It is the only version of Gazebo available from Ubuntu Linux 22.04<br><br>A powerful 3D simulation environment that is particularly suitable for testing object-avoidance and computer vision. It can also be used for [multi-vehicle simulation](../simulation/multi-vehicle-simulation.md) and is commonly used with [ROS](../simulation/ros_interface.md), a collection of tools for automating vehicle control. <br><br><strong>Supported Vehicles:</strong> Quad, VTOL (Standard, Tailsitter, Tiltroter), Plane, Rovers |
| [Gazebo Classic](../sim_gazebo_classic/index.md) | A powerful 3D simulation environment that is particularly suitable for testing object-avoidance and computer vision. It can also be used for [multi-vehicle simulation](../simulation/multi-vehicle-simulation.md) and is commonly used with [ROS](../simulation/ros_interface.md), a collection of tools for automating vehicle control.<br><br>**Supported Vehicles:** Quad ([Iris](../airframes/airframe_reference.md#copter_quadrotor_x_generic_quadcopter)), Hex (Typhoon H480), [Generic Standard VTOL (QuadPlane)](../airframes/airframe_reference.md#vtol_standard_vtol_generic_standard_vtol), Tailsitter, Plane, Rover, Submarine |
| [SIH](../sim_sih/index.md) | A lightweight, headless simulator that runs physics directly inside PX4 as a C++ module (no external dependencies). Headless by default for fastest iteration. Supports ROS 2 via uXRCE-DDS. Can also run on flight controller hardware (`SYS_HITL=2`).<br><br>**Supported Vehicles:** Quad, Hex, Plane, Tailsitter, Standard VTOL, Rover |
There are also a number of [Community Supported Simulators](../simulation/community_supported_simulators.md).
---
### Simulator Comparison
The remainder of this topic is a "somewhat generic" description of how the simulation infrastructure works.
It is not required to _use_ the simulators.
| Feature | Gazebo | SIH |
| ------------------------- | ----------------------------------------- | ------------------------------------------------------------------- |
| **Default Mode** | GUI with 3D rendering | Headless (fastest iteration) |
| **3D Visualization** | Built-in (photorealistic) | Optional: QGC map or jMAVSim display-only |
| **Physics Engine** | External (gz-physics) | Internal (C++ module, uORB) |
| **External Dependencies** | Gazebo packages, rendering libs | None |
| **Vehicle Types** | Quad, VTOL, Plane, Rovers | Quad, Hex, Plane, Tailsitter, Std VTOL, Rover |
| **Multi-vehicle** | Yes (documented) | Yes ([multi-vehicle](../sim_sih/index.md#multi-vehicle-simulation)) |
| **Sensor Simulation** | Camera, LiDAR, depth, IMU, GPS, baro, mag | IMU, GPS, baro, mag, airspeed |
| **Custom Worlds/Models** | Yes (SDF, large model library) | No |
| **ROS 2 Integration** | Yes (uXRCE-DDS) | Yes (uXRCE-DDS) |
| **Extensibility** | Plugins, custom sensors, environments | Modify C++ source, tune SIH\_\* parameters |
| **Community/Ecosystem** | Large Gazebo community, model repos | PX4-internal |
| **Faster-than-Realtime** | Yes | Yes |
| **Runs on FC Hardware** | No | Yes (SYS_HITL=2) |
| **macOS Apple Silicon** | Unstable (known issues) | Works natively |
| **Lockstep** | Yes | Yes |
:::tip
For a detailed analysis of PX4 simulation user needs, priorities, and pain points, see the [PX4 Simulation Integration Survey Report](https://www.mcguirerobotics.com/px4_sim_research_report/) (K. McGuire, Dronecode Foundation, Dec 2025, 120 respondents).
:::
### Which Simulator Should I Use?
- **Full-featured simulation with 3D rendering, custom worlds, camera/lidar sensors, or rich sensor ecosystems:** Use [Gazebo](../sim_gazebo_gz/index.md). Largest ecosystem, custom models and plugins, photorealistic rendering, extensive sensor library, large community.
- **Fast headless iteration, controls research, zero-dependency setup, or macOS:** Use [SIH](../sim_sih/index.md). Runs entirely inside PX4 with no external dependencies, headless by default for maximum speed, physics parameters directly tunable via `SIH_*` params. Supports ROS 2 via uXRCE-DDS.
- **Hardware integration testing without propellers:** Use [SIH on flight controller hardware](../sim_sih/index.md#sih-on-flight-controller-hardware) (`SYS_HITL=2`).
:::info
SIH is headless by default. For optional 3D visualization, you can use [jMAVSim in display-only mode](../sim_sih/index.md#visualization-optional) or monitor the vehicle in QGroundControl's map view.
:::
## Simulator MAVLink API
All simulators except for Gazebo communicate with PX4 using the Simulator MAVLink API.
Most external simulators communicate with PX4 using the Simulator MAVLink API.
This API defines a set of MAVLink messages that supply sensor data from the simulated world to PX4 and return motor and actuator values from the flight code that will be applied to the simulated vehicle.
The image below shows the message flow.
:::info
SIH does not use the MAVLink simulator API. It runs physics internally via uORB messages. Gazebo communicates with PX4 via gz_bridge (Gazebo transport), not MAVLink.
:::
![Simulator MAVLink API](../../assets/simulation/px4_simulator_messages.svg)
::: info
@@ -95,7 +136,7 @@ See [System Startup](../concept/system_startup.md) to learn more.
## SITL Simulation Environment
The diagram below shows a typical SITL simulation environment for any of the supported simulators that use MAVLink (i.e. all of them except Gazebo).
The diagram below shows a typical SITL simulation environment for any of the supported simulators that use MAVLink (i.e. most external simulators, but not Gazebo or SIH).
![PX4 SITL overview](../../assets/simulation/px4_sitl_overview.svg)
@@ -149,8 +190,16 @@ make px4_sitl jmavsim
# Start PX4 with no simulator (i.e. to use your own "custom" simulator)
make px4_sitl none_iris
# SIH (headless, zero dependencies)
make px4_sitl_sih sihsim_quadx
make px4_sitl_sih sihsim_airplane
```
::: info
Use `px4_sitl_sih` instead of `px4_sitl` to avoid building Gazebo dependencies.
:::
The simulation can be further configured via environment variables:
- Any of the [PX4 parameters](../advanced_config/parameter_reference.md) can be overridden via `export PX4_PARAM_{name}={value}`.
@@ -161,7 +210,7 @@ For more information see: [Building the Code > PX4 Make Build Targets](../dev_se
### Run Simulation Faster than Realtime {#simulation_speed}
SITL can be run faster or slower than real-time when using Gazebo, Gazebo Classic, or jMAVSim.
SITL can be run faster or slower than real-time when using Gazebo, Gazebo Classic, jMAVSim, or SIH.
The speed factor is set using the environment variable `PX4_SIM_SPEED_FACTOR`.
@@ -175,6 +224,7 @@ For more information see:
- Gazebo: [Change Simulation Speed](../sim_gazebo_gz/index.md#change-simulation-speed)
- Gazebo Classic: [Change Simulation Speed](../sim_gazebo_classic/index.md#change-simulation-speed) and [Lockstep](../sim_gazebo_classic/index.md#lockstep)
- jMAVSim: [Change Simulation Speed](../sim_jmavsim/index.md#change-simulation-speed) and [Lockstep](../sim_jmavsim/index.md#lockstep)
- SIH: Supports `PX4_SIM_SPEED_FACTOR` for faster-than-realtime simulation.
### Startup Scripts
docs/en/simulation/multi-vehicle-simulation.md
+5 -1
View File
@@ -6,6 +6,7 @@ PX4 supports multi-vehicle simulation using the following simulators:
- [Multi-Vehicle Sim with Gazebo Classic](../sim_gazebo_classic/multi_vehicle_simulation.md) (both with and without ROS)
- [Multi-Vehicle Sim with FlightGear](../sim_flightgear/multi_vehicle.md)
- [Multi-Vehicle Sim with JMAVSim](../sim_jmavsim/multi_vehicle.md)
- [Multi-Vehicle Sim with SIH](../sim_sih/index.md#multi-vehicle-simulation)
The choice of the simulator depends on the vehicle to be simulated, how "good" the simulation needs to be (and for what features), and how many vehicles need to be simulated at a time:
@@ -18,5 +19,8 @@ The choice of the simulator depends on the vehicle to be simulated, how "good" t
Note, this is the successor of [Gazebo Classic](../sim_gazebo_classic/index.md) (below).
- [Gazebo Classic](../sim_gazebo_classic/index.md) is less accurate and less heavy-weight and supports many features and vehicles that aren't available for FlightGear.
It can simulate many more vehicles at a time than FlightGear and it allows for different types of vehicles to be simulated at the same time.
- JMAVSim is a very light-weight simulator that supports only quadcopters.
- [JMAVSim](../sim_jmavsim/index.md) is a very light-weight simulator that supports only quadcopters.
It is recommended if you need to support a lot of quadcopters, and the simulation only needs to be approximate.
- [SIH](../sim_sih/index.md) is the lightest-weight option with zero external dependencies.
Since SIH is headless and runs physics internally, it can launch many instances with minimal resource usage.
It supports all 6 vehicle types (quad, hex, plane, tailsitter, standard VTOL, rover).