fly316/PX4-Autopilot
7
0
Fork 0
mirror of https://gitee.com/mirrors_PX4/PX4-Autopilot.git synced 2026-10-17 19:33:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

Move PX4 Guide source into /docs (#24490)

Browse Source 
* Add vitepress tree

* Update existing workflows so they dont trigger on changes in the docs path

* Add nojekyll, package.json, LICENCE etc

* Add crowdin docs upload/download scripts

* Add docs flaw checker workflows

* Used docs prefix for docs workflows

* Crowdin obvious fixes

* ci: docs move to self hosted runner

runs on a beefy server for faster builds

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: don't run build action for docs or ci changes

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: update runners

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* Add docs/en

* Add docs assets and scripts

* Fix up editlinks to point to PX4 sources

* Download just the translations that are supported

* Add translation sources for zh, uk, ko

* Update latest tranlsation and uorb graphs

* update vitepress to latest

---------

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Ramon Roche <mrpollo@gmail.com>
This commit is contained in:
Hamish Willee
2025-03-13 16:08:27 +11:00
committed by GitHub
co-authored by Ramon Roche
parent 8e6d2ebe4a
commit 88d623bedb
5176 changed files with 558771 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh/simulation/community_supported_simulators.md
+21
View File
@@ -0,0 +1,21 @@
# Community Supported Simulators
This section contains information about _community-supported_ simulations
:::warning
These simulators are not maintained, tested, or supported, by the core development team.
他们可能与当前版本的 PX4 工作, 也可能不工作。
See [Toolchain Installation](../dev_setup/dev_env.md) for information about the environments and tools supported by the core development team.
:::
这些工具有来自其社区的不同程度的支持 (有些得到很好的支持，有些则没有) 。
Questions about these tools should be raised on the [discussion forums](../contribute/support.md#forums-and-chat)
| 仿真器 | 描述 |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [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 very 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> |
| [Simulation-In-Hardware](../sim_sih/index.md) (SIH) | <p>An alternative to HITL that offers a hard real-time simulation directly on the hardware autopilot. This simulator is 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). </p><p><strong>Supported Vehicles:</strong> Plane, Quad, Tailsitter, Standard VTOL</p> |
docs/zh/simulation/failsafes.md
+70
View File
@@ -0,0 +1,70 @@
# 模拟故障保护
[Failsafes](../config/safety.md) define the safe limits/conditions under which you can safely use PX4, and the action that will be performed if a failsafe is triggered (for example, landing, holding position, or returning to a specified point).
在 SITL 中，默认情况下会禁用某一些故障，以便方便模拟使用。
本主题说明如何在实际世界中尝试 SITL 仿真之前测试安全关键行为。
:::info
You can also test failsafes using [HITL simulation](../simulation/hitl.md).
这使得模拟仅适用于连接的 GCS，SDK 或其他 MAVLink 应用程序。
:::
## 数据链路丢失
The _Data Link Loss_ failsafe (unavailability of external data via MAVLink) is enabled by default.
This makes the simulation only usable with a connected GCS, SDK, or other MAVLink application.
Set the parameter [NAV_DLL_ACT](../advanced_config/parameter_reference.md#NAV_DLL_ACT) to the desired failsafe action to change the behavior.
For example, set to `0` to disable it.
:::info
All parameters in SITL including this one get reset when you do `make clean`.
:::
## RC 链接损失
The _RC Link Loss_ failsafe (unavailability of data from a remote control) is enabled by default.
这可以在 GCS UI 中测试电池指示，而不会触发可能中断其他测试的低电池反应。
Set the parameter [NAV_RCL_ACT](../advanced_config/parameter_reference.md#NAV_RCL_ACT) to the desired failsafe action to change the behavior.
For example, set to `0` to disable it.
:::info
All parameters in SITL including this one get reset when you do `make clean`.
:::
## Low Battery
为了模拟丢失和重新获取 GPS 全球定位系统信息，您可以停止/重新启动 GPS 驱动程序。
This enables testing of battery indication in GCS UIs without triggering low battery reactions that might interrupt other testing.
To change this minimal battery percentage value use the parameter [SIM_BAT_MIN_PCT](../advanced_config/parameter_reference.md#SIM_BAT_MIN_PCT).
To control how fast the battery depletes to the minimal value use the parameter [SIM_BAT_DRAIN](../advanced_config/parameter_reference.md#SIM_BAT_DRAIN).
:::tip
By changing [SIM_BAT_MIN_PCT](../advanced_config/parameter_reference.md#SIM_BAT_MIN_PCT) in flight, you can also test regaining capacity to simulate inaccurate battery state estimation or in-air charging technology.
:::
It is also possible to disable the simulated battery using [SIM_BAT_ENABLE](../advanced_config/parameter_reference.md#SIM_BAT_ENABLE) in order to, for example, provide an external battery simulation via MAVLink.
## GPS 损失
[Failure injection](../debug/failure_injection.md) can be used to simulate different types of failures in many sensors and systems.
For example, this can be used to simulate absent or intermittent GPS, RC signal that has stopped or got stuck on a particular value, failure of the avoidance system, and much more.
For example, to simulate GPS failure:
1. Enable the parameter [SYS_FAILURE_EN](../advanced_config/parameter_reference.md#SYS_FAILURE_EN).
2. Enter the following commands on the SITL instance _pxh shell_:
```sh
# Turn (all) GPS off
failure gps off
# Turn (all) GPS on
failure gps ok
```
See [System Failure Injection](../debug/failure_injection.md) for a list of supported target sensors and failure modes.
docs/zh/simulation/hitl.md
+174
View File
@@ -0,0 +1,174 @@
# Hardware in the Loop Simulation (HITL)
:::warning
HITL is [community supported and maintained](../simulation/community_supported_simulators.md).
It may or may not work with current versions of PX4.
See [Toolchain Installation](../dev_setup/dev_env.md) for information about the environments and tools supported by the core development team.
:::
硬件在环仿真模式 (HITL 或 HIL) 下 PX4 固件代码运行在真实的飞行控制器硬件平台上。
这种方法的优点是可以在实际硬件上测试大多数的实际飞行代码。
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>
## HITL兼容机架
The set of compatible airframes vs simulators is:
| 机架 | `SYS_AUTOSTART` | Gazebo Classic | jMAVSim |
| ---------------------------------------------------------------------------------------------------------------- | --------------- | -------------- | ------- |
| [HIL Quadcopter X](../airframes/airframe_reference.md#copter_simulation_hil_quadcopter_x) | 1002 | Y | Y |
| [HIL Standard VTOL QuadPlane](../airframes/airframe_reference.md#vtol_standard_vtol_hil_standard_vtol_quadplane) | 4001 | Y | |
| [Generic Quadrotor x](../airframes/airframe_reference.md#copter_quadrotor_x_generic_quadcopter) copter | 4011 | Y | Y |
<a id="simulation_environment"></a>
## HITL 仿真环境
硬件在环仿真（HITL）模式下标准的 PX4 固件在真实的硬件上运行。
JMAVSim or Gazebo Classic (running on a development computer) are connected to the flight controller hardware via USB/UART.
The simulator acts as gateway to share MAVLink data between PX4 and _QGroundControl_.
:::info
The simulator can also be connected via UDP if the flight controller has networking support and uses a stable, low-latency connection (e.g. a wired Ethernet connection - WiFi is usually not sufficiently reliable).
For example, this configuration has been tested with PX4 running on a Raspberry Pi connected via Ethernet to the computer (a startup configuration that includes the command for running jMAVSim can be found [here](https://github.com/PX4/PX4-Autopilot/blob/main/posix-configs/rpi/px4_hil.config)).
:::
The diagram below shows the simulation environment:
- A HITL configuration is selected (via _QGroundControl_) that doesn't start any real sensors.
- _jMAVSim_ or _Gazebo Classic_ are connected to the flight controller via USB.
- The simulator is connected to _QGroundControl_ via UDP and bridges its MAVLink messages to PX4.
- _Gazebo Classic_ and _jMAVSim_ can also connect to an offboard API and bridge MAVLink messages to PX4.
- (Optional) A serial connection can be used to connect Joystick/Gamepad hardware via _QGroundControl_.
![HITL Setup - jMAVSim and Gazebo Classic](../../assets/simulation/px4_hitl_overview_jmavsim_gazebo.svg)
## HITL 相比于 SITL
相比之下， HITL 在正常飞控硬件平台上运行正常的处于 ”HITL 模式“ 的 PX4 固件。
仿真数据进入整个仿真系统的时间点与 SITL 有所不同。
By contrast, HITL runs normal PX4 firmware in "HITL mode", on normal hardware.
The simulation data enters the system at a different point than for SITL.
Core modules like commander and sensors have HITL modes at startup that bypass some of the normal functionality.
完成所有的配置设定后 <strong x-id="1">关闭</strong> <em x-id="3">QGroundControl</em> 并断开飞控板与计算机的连接。
## 配置 HITL
### PX4 配置
1. Connect the autopilot directly to _QGroundControl_ via USB.
2. 激活 HITL 模式
1. Open **Setup > Safety** section.
2. Enable HITL mode by selecting **Enabled** from the _HITL Enabled_ list:
![QGroundControl HITL configuration](../../assets/gcs/qgc_hitl_config.png)
3. 选择机架
1. Open **Setup > Airframes**
2. Select a [compatible airframe](#compatible_airframe) you want to test.
Then click **Apply and Restart** on top-right of the _Airframe Setup_ page.
![Select Airframe](../../assets/gcs/qgc_hil_config.png)
4. 如有必要, 校准您的 RC 遥控器 或操纵杆。
5. 设置 UDP
1. Under the _General_ tab of the settings menu, uncheck all _AutoConnect_ boxes except for **UDP**.
![QGC Auto-connect settings for HITL](../../assets/gcs/qgc_hitl_autoconnect.png)
6. (可选) 配置操纵杆和故障保护。
Set the following [parameters](../advanced_config/parameters.md) in order to use a joystick instead of an RC remote control transmitter:
- [COM_RC_IN_MODE](../advanced_config/parameter_reference.md#COM_RC_IN_MODE) to "Joystick/No RC Checks". 这允许操纵杆输入并禁用 RC 输入检查。
- [NAV_RCL_ACT](../advanced_config/parameter_reference.md#NAV_RCL_ACT) to "Disabled". 这可确保在没有无线遥控的情况下运行 HITL 时 RC 失控保护不会介入。
:::tip
The _QGroundControl User Guide_ also has instructions on [Joystick](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/setup_view/joystick.html) and [Virtual Joystick](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/settings_view/virtual_joystick.html) setup.
:::
Once configuration is complete, **close** _QGroundControl_ and disconnect the flight controller hardware from the computer.
### X-Plane HITL 仿真环境
总而言之， HITL 在真实硬件上运行标准 PX4 固件，而 SITL 实际上要比标准 PX4 系统执行更多的代码。
#### Gazebo Classic
:::info
Make sure _QGroundControl_ is not running!
:::
1. Build PX4 with [Gazebo Classic](../sim_gazebo_classic/index.md) (in order to build the Gazebo Classic plugins).
```sh
cd <Firmware_clone>
DONT_RUN=1 make px4_sitl_default gazebo-classic
```
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`).
An easy way to check on Ubuntu is to plug in the autopilot, open up a terminal, and type `dmesg | grep "tty"`.
The correct device will be the last one shown.
:::
4. Set up the environment variables:
```sh
source Tools/simulation/gazebo-classic/setup_gazebo.bash $(pwd) $(pwd)/build/px4_sitl_default
```
and run Gazebo Classic in HITL mode:
```sh
gazebo Tools/simulation/gazebo-classic/sitl_gazebo-classic/worlds/hitl_iris.world
```
5. Start _QGroundControl_.
It should autoconnect to PX4 and Gazebo Classic.
#### jMAVSim (仅适用于四旋翼无人机)
:::info
Make sure _QGroundControl_ is not running!
:::
1. 将飞行控制器连接到计算机, 并等待其启动。
2. 在 HITL 模式下运行 jMAVSim (r如有必要，修改串口号名称 <code>/dev/ttyACM0</code> - 比如，在 Mac OS 上该参数应为 <code>/dev/tty.usbmodem1</code>)：
sh
./Tools/jmavsim_run.sh -q -d /dev/ttyACM0 -b 921600 -r 250
```sh
./Tools/simulation/jmavsim/jmavsim_run.sh -q -s -d /dev/ttyACM0 -b 921600 -r 250
```
::: info
Replace the serial port name `/dev/ttyACM0` as appropriate.
On macOS this port would be `/dev/tty.usbmodem1`.
On Windows (including Cygwin) it would be the COM1 or another port - check the connection in the Windows Device Manager.
:::
3. Start _QGroundControl_.
它应该会自动连接 PX4 和 Gazebo 。
## 在 HITL 仿真中执行自主飞行任务
You should be able to use _QGroundControl_ to [run missions](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/fly_view/fly_view.html#missions) and otherwise control the vehicle.
docs/zh/simulation/index.md
+342
View File
@@ -0,0 +1,342 @@
# 仿真
在仿真机中模拟器允许 px4 飞行代码来控制计算机建模工具。
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.
## 支持的仿真器
The following simulators are supported by the PX4 core development team.
| 仿真器 | 描述 |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [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. 它还可用于 [多工具仿真](../simulation/multi-vehicle-simulation.md)，通常用于 [ROS](../simulation/ros_interface.md)，这是一种用于自动控制的工具集。 <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 |
There are also a number of [Community Supported Simulators](../simulation/community_supported_simulators.md).
---
所有模拟器都使用 Simulator MAVLink API 与 PX4 进行通信。
It is not required to _use_ the simulators.
## 仿真器 MAVLink API
All simulators except for Gazebo 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.
![Simulator MAVLink API](../../assets/simulation/px4_simulator_messages.svg)
:::info
A SITL build of PX4 uses [SimulatorMavlink.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/simulation/simulator_mavlink/SimulatorMavlink.cpp) to handle these messages while a hardware build in HIL mode uses [mavlink_receiver.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_receiver.cpp).
这些端口是：
All motors / actuators are blocked, but internal software is fully operational.
:::
The messages are described below (see links for specific detail).
| 消息 | 方向 | 描述 |
| -------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------- |
| [MAV\_MODE:MAV\_MODE\_FLAG\_HIL\_ENABLED][mav_mode_flag_hil_enabled] | 不可用 | 使用模拟时的模式标志。 所有电机/执行器都被卡停，但内部软件可以完全正常运行。 |
| [HIL\_ACTUATOR\_CONTROLS][hil_actuator_controls] | PX4 至 Sim | PX4 控制输出 （电机、执行器）。 |
| [HIL\_SENSOR][hil_sensor] | Sim 至 PX4 | 在 NED 体框架中以 SI 单位模拟 IMU 读数。 |
| [HIL\_GPS][hil_gps] | Sim 至 PX4 | 模拟的 GPS RAW 传感器值。 |
| [HIL\_OPTICAL\_FLOW][hil_optical_flow] | Sim 至 PX4 | 来自流量传感器的模拟光流 （例如 PX4FLOW 或光学鼠标传感器）。 |
| [HIL\_STATE\_QUATERNION][hil_state_quaternion] | Sim 至 PX4 | 包含实际的“仿真”无人机位置、姿态、速度等。 这可以记录并与 px4 的分析和调试估计进行比较 （例如，检查估计器在噪声 （仿真） 传感器输入中的工作情况）。 |
| [HIL\_RC\_INPUTS\_RAW][hil_rc_inputs_raw] | Sim 至 PX4 | 收到 RC 通道的 RAW 值。 |
<!-- links for table above -->
[mav_mode_flag_hil_enabled]: https://mavlink.io/en/messages/common.html#MAV_MODE_FLAG_HIL_ENABLED
[hil_actuator_controls]: https://mavlink.io/en/messages/common.html#HIL_ACTUATOR_CONTROLS
[hil_sensor]: https://mavlink.io/en/messages/common.html#HIL_SENSOR
[hil_gps]: https://mavlink.io/en/messages/common.html#HIL_GPS
[hil_optical_flow]: https://mavlink.io/en/messages/common.html#HIL_OPTICAL_FLOW
[hil_state_quaternion]: https://mavlink.io/en/messages/common.html#HIL_STATE_QUATERNION
[hil_rc_inputs_raw]: https://mavlink.io/en/messages/common.html#HIL_RC_INPUTS_RAW
<!-- above ^^^ links for table -->
PX4 directly uses the [Gazebo API](https://gazebosim.org/docs) to interface with [Gazebo](../sim_gazebo_gz/index.md) and MAVlink is not required.
## 默认 PX4 MAVLink UDP 端口
By default, PX4 uses commonly established UDP ports for MAVLink communication with ground control stations (e.g. _QGroundControl_), Offboard APIs (e.g. MAVSDK, MAVROS) and simulator APIs (e.g. Gazebo).
These ports are:
- PX4's remote UDP Port **14550** is used for communication with ground control stations.
期望外接 APIs 监听此端口上的连接。
_QGroundControl_ listens to this port by default.
- PX4's remote UDP Port **14540** is used for communication with offboard APIs.
期望 GCS 将侦听此端口上的连接。
::: info
Multi-vehicle simulations use a separate remote port for each instance, allocated sequentially from `14540` to `14549`
(additional instances all use port `14549`).
:::
- The simulator's local TCP Port, **4560**, is used for communication with PX4.
PX4 侦听此端口，仿真器应通过向该端口广播数据来启动通信。
:::info
The ports for the GCS, offboard APIs and simulator are specified by startup scripts.
See [System Startup](../concept/system_startup.md) to learn more.
:::
<!-- A useful discussion about UDP ports here: https://github.com/PX4/PX4-user_guide/issues/1035#issuecomment-777243106 -->
## SITL 仿真环境
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).
![PX4 SITL overview](../../assets/simulation/px4_sitl_overview.svg)
The different parts of the system connect via UDP, and can be run on either the same computer or another computer on the same network.
- PX4 uses a simulation-specific module to connect to the simulator's local TCP port 4560.
Simulators then exchange information with PX4 using the [Simulator MAVLink API](#simulator-mavlink-api) described above.
SITL 和模拟器上的 PX4 可以在同一台计算机上运行，也可以在同一网络上运行不同的计算机。
::: info
Simulators can also use the _uxrce-dds bridge_ ([XRCE-DDS](../middleware/uxrce_dds.md)) to directly interact with PX4 (i.e. via [UORB topics](../middleware/uorb.md) rather than MAVLink).
This approach _may_ used by Gazebo Classic for [multi-vehicle simulation](../sim_gazebo_classic/multi_vehicle_simulation.md#build-and-test-xrce-dds).
:::
- PX4 uses the normal MAVLink module to connect to ground stations and external developer APIs like MAVSDK or ROS
- Ground stations listen to PX4's remote UDP port: `14550`
- External developer APIs listen to PX4's remote UDP port: `14540`.
For multi-vehicle simulations, PX4 sequentially allocates a separate remote port for each instance from `14540` to `14549` (additional instances all use port `14549`).
- PX4 defines a number of _local_ UDP ports (`14580`,`18570`), which are sometimes used when networking with PX4 running in a container or virtual machine.
These are not recommended for "general" use and may change in future.
- A serial connection may be used to connect [Joystick/Gamepad](../config/joystick.md) hardware via _QGroundControl_.
If you use the normal build system SITL `make` configuration targets (see next section) then both SITL and the Simulator will be launched on the same computer and the ports above will automatically be configured.
You can configure additional MAVLink UDP connections and otherwise modify the simulation environment in the build configuration and initialisation files.
### 启动/构建 SITL 模拟
The build system makes it very easy to build and start PX4 on SITL, launch a simulator, and connect them.
The syntax (simplified) looks like this:
```sh
make px4_sitl simulator[_vehicle-model]
```
where `simulator` is `gz` (for Gazebo), `gazebo-classic`, `jmavsim` or some other simulator, and vehicle-model is a particular vehicle type supported by that simulator ([Gazebo](../sim_gazebo_gz/index.md) and [jMAVSim](../sim_jmavsim/index.md) only support multicopters at time of writing, while [Gazebo Classic](../sim_gazebo_classic/index.md) supports many different types).
A number of examples are shown below, and there are many more in the individual pages for each of the simulators:
```sh
# Start Gazebo with the x500 multicopter
make px4_sitl gz_x500
# Start Gazebo Classic with plane
make px4_sitl gazebo-classic_plane
# Start Gazebo Classic with iris and optical flow
make px4_sitl gazebo-classic_iris_opt_flow
# Start JMavSim with iris (default vehicle model)
make px4_sitl jmavsim
# Start PX4 with no simulator (i.e. to use your own "custom" simulator)
make px4_sitl none_iris
```
The simulation can be further configured via environment variables:
- `PX4_ESTIMATOR`: This variable configures which estimator to use.
Possible options are: `ekf2` (default), `lpe` (deprecated).
It can be set via `export PX4_ESTIMATOR=lpe` before running the simulation.
The syntax described here is simplified, and there are many other options that you can configure via _make_ - for example, to set that you wish to connect to an IDE or debugger.
For more information see: [Building the Code > PX4 Make Build Targets](../dev_setup/building_px4.md#px4-make-build-targets).
### Run Simulation Faster than Realtime {#simulation_speed}
SITL can be run faster or slower than real-time when using Gazebo, Gazebo Classic, or jMAVSim.
The speed factor is set using the environment variable `PX4_SIM_SPEED_FACTOR`.
:::info
PX4 SITL and the simulators are run in _lockstep_, which means that they are locked to run at the same speed, and therefore can react appropriately to sensor and actuator messages.
This is what makes it possible to run the simulation at different speeds, and also pause the simulation in order to step through code.
:::
有关详细信息，请参阅︰
- 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)
### 启动脚本
Scripts are used to control which parameter settings to use or which modules to start.
They are located in the [ROMFS/px4fmu_common/init.d-posix](https://github.com/PX4/PX4-Autopilot/tree/main/ROMFS/px4fmu_common/init.d-posix) directory, the `rcS` file is the main entry point.
See [System Startup](../concept/system_startup.md) for more information.
### Simulating Failsafes and Sensor/Hardware Failure
[Simulate Failsafes](../simulation/failsafes.md) explains how to trigger safety failsafes like GPS failure and battery drain.
## HITL 仿真环境
硬件在环仿真（HITL）模式下标准的 PX4 固件在真实的硬件上运行。
The HITL Simulation Environment in documented in: [HITL Simulation](../simulation/hitl.md).
## 操纵杆／手柄集成
_QGroundControl_ desktop versions can connect to a USB Joystick/Gamepad and send its movement commands and button presses to PX4 over MAVLink.
相反，它将数据包路由到 "本地主机"。
If you don't have a joystick you can alternatively control the vehicle using QGroundControl's onscreen virtual thumbsticks.
For setup information see the _QGroundControl User Guide_:
- [Joystick Setup](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/setup_view/joystick.html)
- [Virtual Joystick](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/settings_view/virtual_joystick.html)
<!-- FYI Airsim info on this setting up remote controls: https://github.com/Microsoft/AirSim/blob/master/docs/remote_controls.md -->
## 相机模拟
PX4 supports capture of both still images and video from within the [Gazebo Classic](../sim_gazebo_classic/index.md) simulated environment.
This can be enabled/set up as described in [Gazebo Glassic > Video Streaming](../sim_gazebo_classic/index.md#video-streaming).
The simulated camera is a gazebo classic plugin that implements the [MAVLink Camera Protocol](https://mavlink.io/en/protocol/camera.html) <!-- **PX4-Autopilot/Tools/simulation/gazebo-classic/sitl_gazebo-classic/src/gazebo_geotagged_images_plugin.cpp -->.
PX4 connects/integrates with this camera in _exactly the same way_ as it would with any other MAVLink camera:
1. [TRIG_INTERFACE](../advanced_config/parameter_reference.md#TRIG_INTERFACE) must be set to `3` to configure the camera trigger driver for use with a MAVLink camera
:::tip
In this mode the driver just sends a [CAMERA_TRIGGER](https://mavlink.io/en/messages/common.html#CAMERA_TRIGGER) message whenever an image capture is requested.
For more information see [Cameras Connected to Flight Controller Outputs](../camera/fc_connected_camera.md).
:::
2. PX4 必须在 GCS 和（模拟器）MAVLink Camera 之间转发所有摄像机命令。
You can do this by starting [MAVLink](../modules/modules_communication.md#mavlink) with the `-f` flag as shown, specifying the UDP ports for the new connection.
```sh
mavlink start -u 14558 -o 14530 -r 4000 -f -m camera
```
::: info
More than just the camera MAVLink messages will be forwarded, but the camera will ignore those that it doesn't consider relevant.
:::
The same approach can be used by other simulators to implement camera support.
## 在远程服务器上运行仿真
It is possible to run the simulator on one computer, and access it from another computer on the same network (or on another network with appropriate routing).
This might be useful, for example, if you want to test a drone application running on real companion computer hardware running against a simulated vehicle.
This does not work "out of the box" because PX4 does not route packets to external interfaces by default (in order to avoid spamming the network and different simulations interfering with each other).
Instead it routes traffic internally - to "localhost".
There are a number of ways to make the UDP packets available on external interfaces, as outlined below.
### 启用 MAV_BROADCAST
The [mavlink-router](https://github.com/mavlink-router/mavlink-router) can be used to route packets from localhost to an external interface.
To route packets between SITL running on one computer (sending MAVLink traffic to localhost on UDP port 14550), and QGC running on another computer (e.g. at address `10.73.41.30`) you could:
- Start _mavlink-router_ with the following command:
```sh
mavlink-routerd -e 10.73.41.30:14550 127.0.0.1:14550
```
- Use a _mavlink-router_ conf file.
```ini
[UdpEndpoint QGC]
Mode = Normal
Address = 10.73.41.30
Port = 14550
[UdpEndpoint SIM]
Mode = Eavesdropping
Address = 127.0.0.1
Port = 14550
```
:::info
More information about _mavlink-router_ configuration can be found [here](https://github.com/mavlink-router/mavlink-router#running).
:::
### 使用 MAVLink 路由器
The [mavlink module](../modules/modules_communication.md#mavlink_usage) routes to _localhost_ by default, but you can enable UDP broadcasting of heartbeats using its `-p` option.
Any remote computer on the network can then connect to the simulator by listening to the appropriate port (i.e. 14550 for _QGroundControl_).
:::info
UDP broadcasting provides a simple way to set up the connection when there is only one simulation running on the network.
Do not use this approach if there are multiple simulations running on the network (you might instead [publish to a specific address](#enable-streaming-to-specific-address)).
:::
This should be done in an appropriate configuration file where `mavlink start` is called.
For example: [/ROMFS/px4fmu_common/init.d-posix/px4-rc.mavlink](https://github.com/PX4/PX4-Autopilot/blob/main/ROMFS/px4fmu_common/init.d-posix/px4-rc.mavlink).
### 修改外部广播的配置
The [mavlink module](../modules/modules_communication.md#mavlink_usage) routes to _localhost_ by default, but you can specify an external IP address to stream to using its `-t` option.
The specified remote computer can then connect to the simulator by listening to the appropriate port (i.e. 14550 for _QGroundControl_).
This should be done in various configuration files where `mavlink start` is called.
For example: [/ROMFS/px4fmu_common/init.d-posix/px4-rc.mavlink](https://github.com/PX4/PX4-Autopilot/blob/main/ROMFS/px4fmu_common/init.d-posix/px4-rc.mavlink).
### SSH 通道
SSH tunneling is a flexible option because the simulation computer and the system using it need not be on the same network.
:::info
You might similarly use VPN to provide a tunnel to an external interface (on the same network or another network).
:::
One way to create the tunnel is to use SSH tunneling options.
The tunnel itself can be created by running the following command on _localhost_, where `remote.local` is the name of a remote computer:
```sh
ssh -C -fR 14551:localhost:14551 remote.local
```
The UDP packets need to be translated to TCP packets so they can be routed over SSH.
The [netcat](https://en.wikipedia.org/wiki/Netcat) utility can be used on both sides of the tunnel - first to convert packets from UDP to TCP, and then back to UDP at the other end.
:::tip
QGC must be running before executing _netcat_.
:::
On the _QGroundControl_ computer, UDP packet translation may be implemented by running following commands:
```sh
mkfifo /tmp/tcp2udp
netcat -lvp 14551 < /tmp/tcp2udp | netcat -u localhost 14550 > /tmp/tcp2udp
```
On the simulator side of the SSH tunnel, the command is:
```sh
mkfifo /tmp/udp2tcp
netcat -lvup 14550 < /tmp/udp2tcp | netcat localhost 14551 > /tmp/udp2tcp
```
The port number `14550` is valid for connecting to QGroundControl or another GCS, but should be adjusted for other endpoints (e.g. developer APIs etc.).
The tunnel may in theory run indefinitely, but _netcat_ connections may need to be restarted if there is a problem.
The [QGC_remote_connect.bash](https://raw.githubusercontent.com/ThunderFly-aerospace/sitl_gazebo/autogyro-sitl/scripts/QGC_remote_connect.bash) script can be run on the QGC computer to automatically setup/run the above instructions.
The simulation must already be running on the remote server, and you must be able to SSH into that server.
docs/zh/simulation/multi-vehicle-simulation.md
+22
View File
@@ -0,0 +1,22 @@
# 基于gazebo的多飞行器仿真
本主题介绍如何使用 gazebo 和 sitl (仅限 linux) 模拟多架无人机/车辆。
- [Multi-Vehicle Sim with Gazebo](../sim_gazebo_gz/multi_vehicle_simulation.md) (both with and without ROS)
- [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)
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:
- FlightGear is the most accurate simulator, and as a result the most heavy weight.
It might be used if you need a great simulation but not too many vehicles at a time.
It can also be used if different types of vehicles need to be simulated at the same time.
- [Gazebo](../sim_gazebo_gz/index.md) is less accurate and less heavy-weight and supports many features 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.
It can only be used with Ubuntu 20.04 and newer.
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.
It is recommended if you need to support a lot of quadcopters, and the simulation only needs to be approximate.
docs/zh/simulation/ros_interface.md
+151
View File
@@ -0,0 +1,151 @@
# ROS 与 Gazebo 仿真。
[ROS](../ros/index.md) (Robot Operating System) can be used with PX4 and the [Gazebo Classic](../sim_gazebo_classic/index.md) simulator.
It uses the [MAVROS](../ros/mavros_installation.md) MAVLink node to communicate with PX4.
The ROS/Gazebo Classic integration with PX4 follows the pattern in the diagram below (this shows the _generic_ [PX4 simulation environment](../simulation/index.md#sitl-simulation-environment)).
PX4 communicates with the simulator (e.g. Gazebo Classic) to receive sensor data from the simulated world and send motor and actuator values.
它与 GCS 和 Offboard API（例如 ROS）通信，以从模拟环境发送遥测数据并接收命令。
![PX4 SITL overview](../../assets/simulation/px4_sitl_overview.png)
:::info
The only _slight_ difference to "normal behaviour" is that ROS initiates the connection on port 14557, while it is more typical for an offboard API to listen for connections on UDP port 14540.
:::
## Installing ROS and Gazebo Classic
[ROS (1) with MAVROS Installation Guide](../ros/mavros_installation.md) explains how to set up a guide for working with ROS (1), MAVROS, and PX4.
:::info
_ROS_ is only supported on Linux (not macOS or Windows).
:::
## 启动 ROS/Simulation
The command below can be used to launch the simulation and connect ROS to it via [MAVROS](../ros/mavros_installation.md), where `fcu_url` is the IP / port of the computer running the simulation:
```sh
roslaunch mavros px4.launch fcu_url:="udp://:14540@192.168.1.36:14557"
```
要运行包含在 ROS 中的 SITL，需要更新 ROS 环境，然后像往常一样启动：
```sh
cd &lt;Firmware_clone&gt;
make px4_sitl_default gazebo
source ~/catkin_ws/devel/setup.bash // (optional)
source Tools/setup_gazebo.bash $(pwd) $(pwd)/build/px4_sitl_default
export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:$(pwd)
export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:$(pwd)/Tools/sitl_gazebo
roslaunch px4 posix_sitl.launch
```
:::info
It can be useful to call _roslaunch_ with the `-w NUM_WORKERS` (override number of worker threads) and/or `-v` (verbose) in order to get warnings about missing dependencies in your setup. 例如：
```sh
cd &lt;Firmware_clone&gt;
make px4_sitl_default gazebo
source ~/catkin_ws/devel/setup.bash // (optional)
source Tools/setup_gazebo.bash $(pwd) $(pwd)/build/px4_sitl_default
export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:$(pwd)
export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:$(pwd)/Tools/sitl_gazebo
roslaunch px4 posix_sitl.launch
```
:::
## Launching Gazebo Classic with ROS Wrappers
The Gazebo Classic simulation can be modified to integrate sensors publishing directly to ROS topics e.g. the Gazebo Classic ROS laser plugin.
To support this feature, Gazebo Classic must be launched with the appropriate ROS wrappers.
首先使用以下命令启动模拟器：
- [posix_sitl.launch](https://github.com/PX4/PX4-Autopilot/blob/main/launch/posix_sitl.launch): plain SITL launch
- [mavros_posix_sitl.launch](https://github.com/PX4/PX4-Autopilot/blob/main/launch/mavros_posix_sitl.launch): SITL and MAVROS
控制台将如下所示：
现在在新终端中确保您可以通过 Gazebo 菜单插入 Iris 模型，为此设置环境变量以包含相应的<code>sitl_gazebo</code>文件夹。
```sh
cd <PX4-Autopilot_clone>
DONT_RUN=1 make px4_sitl_default gazebo-classic
source ~/catkin_ws/devel/setup.bash # (optional)
source Tools/simulation/gazebo-classic/setup_gazebo.bash $(pwd) $(pwd)/build/px4_sitl_default
export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:$(pwd)
export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:$(pwd)/Tools/simulation/gazebo-classic/sitl_gazebo-classic
roslaunch px4 posix_sitl.launch
```
Include one of the above mentioned launch files in your own launch file to run your ROS application in the simulation.
## 事件之后发生了什么
This section shows how the _roslaunch_ instructions provided previously actually work (you can follow them to manually launch the simulation and ROS).
You will need three terminals, in all of them the ros environment must be sourced.
First start the simulator using the command below:
```sh
cd <PX4-Autopilot_clone>
export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:$(pwd)
roslaunch px4 px4.launch
```
The console will look like this:
```sh
INFO [px4] instance: 0
______ __ __ ___
| ___ \ \ \ / / / |
| |_/ / \ V / / /| |
| __/ / \ / /_| |
| | / /^\ \ \___ |
\_| \/ \/ |_/
px4 starting.
INFO [px4] startup script: /bin/sh etc/init.d-posix/rcS 0
INFO [init] found model autostart file as SYS_AUTOSTART=10016
INFO [param] selected parameter default file parameters.bson
INFO [param] importing from 'parameters.bson'
INFO [parameters] BSON document size 295 bytes, decoded 295 bytes (INT32:12, FLOAT:3)
INFO [param] selected parameter backup file parameters_backup.bson
INFO [dataman] data manager file './dataman' size is 7866640 bytes
etc/init.d-posix/rcS: 31: [: Illegal number:
INFO [init] PX4_SIM_HOSTNAME: localhost
INFO [simulator_mavlink] Waiting for simulator to accept connection on TCP port 4560
```
In the second terminal make sure you will be able to start gazebo with the world files defined in PX4-Autopilot. To do this set your environment variables to include the appropriate `sitl_gazebo-classic` folders.
```sh
cd <PX4-Autopilot_clone>
source Tools/simulation/gazebo-classic/setup_gazebo.bash $(pwd) $(pwd)/build/px4_sitl_default
export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:$(pwd)/Tools/simulation/gazebo-classic/sitl_gazebo-classic
```
Now start Gazebo Classic like you would when working with ROS
```sh
roslaunch gazebo_ros empty_world.launch world_name:=$(pwd)/Tools/simulation/gazebo-classic/sitl_gazebo-classic/worlds/empty.world
```
In the third terminal make sure you will be able to spawn the model with the sdf files defined in PX4-Autopilot. To do this set your environment variables to include the appropriate `sitl_gazebo-classic` folders.
```sh
cd <PX4-Autopilot_clone>
source Tools/simulation/gazebo-classic/setup_gazebo.bash $(pwd) $(pwd)/build/px4_sitl_default
export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:$(pwd)/Tools/simulation/gazebo-classic/sitl_gazebo-classic
```
Now insert the Iris quadcopter model like you would when working with ROS. Once the Iris is loaded it will automatically connect to the px4 app.
```sh
rosrun gazebo_ros spawn_model -sdf -file $(pwd)/Tools/simulation/gazebo-classic/sitl_gazebo-classic/models/iris/iris.sdf -model iris -x 0 -y 0 -z 0 -R 0 -P 0 -Y 0
```