New Crowdin translations - zh-CN (#25661)

Co-authored-by: Crowdin Bot <support+bot@crowdin.com>
2026-05-27 10:17:45 +08:00 · 2025-10-08 16:19:27 +11:00
parent fa706c905f
commit d3bcdf8ba7
20 changed files with 631 additions and 283 deletions
@@ -6,23 +6,23 @@
 小提示
 PX4 开发团队强烈建议您使用此 ROS 版本，或将现有系统迁移至此 ROS 版本！

-这是最新版本的 [ROS](https://www.ros.org/) (机器人操作系统)。
+这是最新版本的 [ROS](https://www.ros.org/)(机器人操作系统)。
 它在 ROS “1” 的基础上进行了显著改进，尤其能够实现与 PX4 更深度、更低延迟的集成。
 :::

 ROS的优势在于拥有活跃的开发者生态系统 —— 该生态系统致力于解决各类常见的机器人技术问题，同时还能调用其他为 Linux 系统编写的软件库。
-例如，它可以用于 [computer vision](../computer_vision/index.md)解决问题。
+例如，它可以用于 [计算机试图](../computer_vision/index.md) 解决问题。

 ROS 2 能够实现与 PX4 极深度的集成，你可以在 ROS 2 中创建飞行模式，这些模式与 PX4 内部原生飞行模式毫无区别；同时还能以高速率直接读取和写入 PX4 内部的 uORB 主题。
 （尤其）建议在以下场景中使用：从伴飞计算机进行控制与通信（且低延迟至关重要时）、需借助 Linux 系统的现有库时，或编写新的高级飞行模式时。

 ROS 2 与 PX4 之间的通信使用的中间件需实现 [XRCE-DDS protocol](../middleware/uxrce_dds.md).
-这个中间件将以 ROS 2 消息和类型显示 PX4 [uORB messages](../msg_docs/index.md) 会转换为 ROS 2 消息和数据类型，从而切实支持从 ROS 2 工作流与节点直接访问 PX4。
+这个中间件将以 ROS 2 消息和类型显示 PX4  [uORB messages](../msg_docs/index.md) 会转换为 ROS 2 消息和数据类型，从而切实支持从 ROS 2 工作流与节点直接访问 PX4。
 中间件使用 uORB 消息定义生成代码来序列化和反序列化来处理PX4 的收发消息。
 这些相同的消息定义也用于 ROS 2 应用程序中以便能够解析这些消息。

 :::info
-ROS 2 也可以使用 [MAVROS](https://github.com/mavlink/mavros/tree/ros2/mavros而不是 XRCE-DDS连接到 PX4。
+ROS 2 也可以使用 [MAVROS](https://github.com/mavlink/mavros/tree/ros2/mavros)而不是 XRCE-DDS连接到 PX4。
 该选项受 MAVROS 项目支持（本文档未对此进行说明）。
 :::

@@ -33,9 +33,9 @@ ROS 2 也可以使用 [MAVROS](https://github.com/mavlink/mavros/tree/ros2/mavro

 本节的主要主题是：

- ROS 2 用户指南: PX4 视角下的 ROS 2，包括安装、设置和如何构建与 PX4 通信的 ROS 2 应用。
- [ROS 2 离板控制示例](../ros2/offboard_control.md)：一个 C++ 教程示例显示如何在 [离板模式] (../flight_modes/offboard.md) 中使用 ROS 2 节点进行位置控制。
- [ROS 2 多车辆模拟](../ros2/multi_vehicle.md)：通过单独的ROS2 代理商连接到多极PX4 模拟的说明。
+- [ROS 2 用户指南](../ros2/user_guide.md): PX4 视角下的 ROS 2，包括安装、设置和如何构建与 PX4 通信的 ROS 2 应用。
+- [ROS 2 离板控制实例](../ros2/offboard_control.md)：一个 C++ 教程示例显示如何在 [离板模式] (../flight_modes/offboard.md) 中使用 ROS 2 节点进行位置控制。
+- [ROS 2 多载具模拟](../ros2/multi_vehicle.md)：通过单独的ROS2 代理商连接到多极PX4 模拟的说明。
 - [PX4 ROS2 接口库](../ros2/px4_ros2_interface_lib.md)：一个C++ 库，它与ROS2的 PX4 交互。
  可以使用 ROS 2 创建和注册飞行模式，并从 ROS2 应用程序如VIO 系统发送位置估计数。
 - [ROS 2 消息翻译节点](../ros2/px4_ros2_msg_translation_node.md)：一个 ROS 2 消息翻译节点，它允许在 PX4 和 ROS 2 应用程序之间共享，这些应用程序被编译成不同的消息版本。
@@ -1,54 +1,54 @@
-# 使用 ROS 2 进行多车辆模拟
+# 使用 ROS 2 的多载具模拟

-[XRCE-DDS](../middleware/uxrce_dds.md) 支持多个客户端通过 UDP 协议连接到同一个代理。
+[XRCE-DDS](../middleware/uxrce_dds.md)支持多个客户端通过 UDP 协议连接到同一个代理。
 这在模拟中特别有用，因为只有一个代理需要启动。

 ## 设置和要求

 唯一的要求是

- 能够在不依赖 ROS 2 的情况下，使用所需的仿真器([Gazebo](../sim_gazebo_gz/multi_vehicle_simulation.md), [Gazebo Classic](../sim_gazebo_classic/multi_vehicle_simulation.md#multiple-vehicle-with-gazebo-classic), [FlightGear](../sim_flightgear/multi_vehicle.md) 和 [JMAVSim](../sim_jmavsim/multi_vehicle.md))运行多车辆仿真[multi-vehicle simulation](../simulation/multi-vehicle-simulation.md)。
- 能够在单一车辆仿真中使用ROS 2（机器人操作系统 2）
+- 能够在不依赖 ROS 2 的情况下，使用所需的仿真器([Gazebo](../sim_gazebo_gz/multi_vehicle_simulation.md), [Gazebo Classic](../sim_gazebo_classic/multi_vehicle_simulation.md#multiple-vehicle-with-gazebo-classic), [FlightGear](../sim_flightgear/multi_vehicle.md) and [JMAVSim](../sim_jmavsim/multi_vehicle.md))运行多载具模拟 [multi-vehicle simulation](../simulation/multi-vehicle-simulation.md) 。
+- 能够在单一载具模拟中使用 [ROS 2](../ros2/user_guide.md)

 ## 工作原理

-在仿真中，每个 PX4 实例都会获得一个唯一的px4_instance编号，编号从0开始。
+在模拟中，每个 PX4 实例都会获得一个唯一的`px4_instance`编号，编号从`0`开始。
 该值用于为 [UXRCE_DDS_KEY](../advanced_config/parameter_reference.md#UXRCE_DDS_KEY)分配一个唯一值：

 ```sh
-参数设置 UXRCE_DDS_KEY $(px4_instance+1))
+参数设置UXRCE_DDS_KEY $((px4_instance+1))
 ```

 :::info
-通过这种方式，UXRCE_DDS_KEY 将始终与 [MAV_SYS_ID] 保持一致（../advanced_config/parameter_reference.md#MAV_SYS_ID）
+通过这种方式， `UXRCE_DDS_KEY` 将始终与 [MAV_SYS_ID] 保持一致(../advanced_config/parameter_reference.md#MAV_SYS_ID)
 :::

-此外，当 px4_instance 大于 0 时，会添加一个格式为 px4_$px4_instance 的唯一 ROS 2 命名空间前缀：
+此外，当 `px4_instance` 大于 0 时，会添加一个格式为  `px4_$px4_instance` 的唯一 ROS 2[namespace prefix](../middleware/uxrce_dds.md#customizing-the-namespace)：

 ```sh
 uxrce_dds_ns="-n px4_$px4_instance"
 ```

 :::info
-环境变量 PX4_UXRCE_DDS_NS 若已设置，将覆盖上文所述的命名空间行为。
+环境变量`PX4_UXRCE_DDS_NS` 若已设置，将覆盖上文所述的命名空间行为。
 :::

-第一个实例（px4_instance=0）没有额外的命名空间，此举是为了与真实载具上 xrce-dds 客户端的默认行为保持一致。
-这种不匹配可以通过手动使用 `PX4_UXRCE_DDS_NS` 来修复，或者通过从索引 `1` 中添加车辆而不是 `0` (这是Gazebo Classic的 [sitl_multiple_run.sh](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/simulation/gazebo-classic/sitl_multiple_run.sh) 的默认行为)。
+第一个实例(`px4_instance=0`)没有额外的命名空间，此举是为了与真实载具上 xrce-dds 客户端的默认行为保持一致。
+这种不匹配可以通过手动使用 `PX4_UXRCE_DDS_NS` 来修复，或者通过从索引 `1` 中添加车辆而不是 `0` (这是Gazebo Classic的  [sitl_multiple_run.sh](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/simulation/gazebo-classic/sitl_multiple_run.sh) 的默认行为)。

 模拟中的默认客户端配置概述如下：

-| `PX4_UXRCE_DDS_NS` | `px4_instance` | `UXRCE_DDS_KEY`  | 客户端命名空间               |
+| `PX4_UXRCE_DDS_NS` | `px4_instance` | `UXRCE_DDS_KEY`  | client namespace      |
 | ------------------ | -------------- | ---------------- | --------------------- |
-| 未提供                | 0              | `px4_instance+1` | 无                     |
-| 已提供                | 0              | `px4_instance+1` | `PX4_UXRCE_DDS_NS`    |
-| 未提供                | > 0            | `px4_instance+1` | `px4_${px4_instance}` |
-| 已提供                | > 0            | `px4_instance+1` | `PX4_UXRCE_DDS_NS`    |
+| not provided       | 0              | `px4_instance+1` | 无                     |
+| provided           | 0              | `px4_instance+1` | `PX4_UXRCE_DDS_NS`    |
+| not provided       | > 0            | `px4_instance+1` | `px4_${px4_instance}` |
+| provided           | > 0            | `px4_instance+1` | `PX4_UXRCE_DDS_NS`    |

 ## 调整 `target_system` 值

-PX4 只在他们的 `target_system` 字段为 0 (路由通信) 或与 `MAV_SYS_ID` 一致时，才接受 [VehicleCommand](../msg_docs/VehicleCommand.md)。
+PX4 只在他们的 `target_system` 字段为 0`(路由通信) 或与`MAV_SYS_ID` 一致时，才接受[VehicleCommand](../msg_docs/VehicleCommand.md)。
 在所有其他情况下，信息都被忽视。
-因此，当 ROS 2 节点需向 PX4 发送 VehicleCommand（载具指令）消息时，必须确保消息中填写了合适的 target_system（目标系统）字段值。
+因此，当 ROS 2 节点需向 PX4 发送`VehicleCommand`消息时，必须确保消息中填写了合适的`target_system\`字段值。

-例如，若你想向 px4_instance=2 的第三台飞行器发送指令，则需要在所有 VehicleCommand消息中设置 target_system=3。
+例如，若你想向 `px4_instance=2` 的第三台飞行器发送指令，则需要在所有`VehicleCommand`消息中设置 `target_system=3`。
@@ -1,6 +1,6 @@
 # ROS 2 Offboard 控制示例

-以下的 C++ 示例展示了如何在 [离板模式] (../flight_modes/offboard.md) 中从 ROS 2 节点进行位置控制。
+以下的 C++ 示例展示了如何在 [离板模式] (../flight_modes/offboard.md) 中从 ROS 2 节点进行多轴位置控制。

 示例将首先发送设置点、进入offboard模式、解锁、起飞至5米，并悬停等待。
 虽然简单，但它显示了如何使用offboard控制以及如何向无人机发送指令。
@@ -16,13 +16,13 @@ _Offboard_ control is dangerous.
 ROS 与 PX4 存在若干不同的预设（假设），尤其是在坐标系约定（[frame conventions]）方面../ros/external_position_estimation.md#reference-frames-and-ros
 当主题发布或订阅时，坐标系类型之间没有隐含转换！

-这个例子按照PX4的预期在NED坐标系下发布位置。
+这个例子按照 PX4 的预期在NED坐标系下发布位置。
 若要订阅来自在不同框架内发布的节点的数据(例如ENU, 这是ROS/ROS 2中的标准参考框架，使用 [frame_transforms](https://github.com/PX4/px4_ros_com/blob/main/src/lib/frame_transforms.cpp)库中的辅助函数。
 :::

 ## 小試身手

-请遵循 ROS 2 用户指南 （../ros2/user_guide.md）中的说明，完成安装 PX4和运行模拟器，安装 ROS 2和启动 XRCE-DDS 代理（Agent）。
+按照 [ROS 2 User Guide](../ros2/user_guide.md)中的说明来安装PX 并运行多轴模拟器，安装ROS 2, 并启动XRCE-DDS代理。

 之后，我们可参照 ROS 2 用户指南 > 构建 ROS 2 工作空间 （../ros2/user_guide.md#build-ros-2-workspace）中的相似的步骤来运行这个例子。

@@ -95,7 +95,7 @@ ROS 与 PX4 存在若干不同的预设（假设），尤其是在坐标系约
   ros2 run px4_ros_com offboard_control
   ```

-飞行器将解锁、起飞至5米并悬停等待（永久）。
+飞行器将解锁、起飞至 5 米并悬停等待(永久)。

 ## 实现

@@ -133,7 +133,7 @@ timer_ = this-&gt;create_wall_timer(100ms, timer_callback);
 ```

 循环运行在一个100毫秒计时器。
-在最初的 10 个循环中，它会调用 publish_offboard_control_mode() 和 publish_trajectory_setpoint() 这两个函数，向 PX4 发送 OffboardControlMode（离板控制模式）（../msg_docs/OffboardControlMode.md） 和 TrajectorySetpoint（轨迹设定点）（../msg_docs/TrajectorySetpoint.md） 消息。
+在最初的 10 个循环中，它会调用 `publish_offboard_control_mode()` 和 `publish_trajectory_setpoint()` 这两个函数，向 PX4 发送 OffboardControlMode[OffboardControlMode](../msg_docs/OffboardControlMode.md) 和 [TrajectorySetpoint](../msg_docs/TrajectorySetpoint.md) 消息。
 OffboardControlMode消息会持续发送，以便 PX4 切换到离板模式后允许解锁；而 TrajectorySetpoint消息会被忽略（直到载具处于离板模式）

 10 个循环后，会调用 publish_vehicle_command() 函数切换至离板模式，并调用 arm() 函数对载具进行解锁。
@@ -327,7 +327,7 @@ private:
 };
 ```

- `[1]`: 首先创建一个从 [`px4_ros2::ModeExecutorBase`](https://auterion.github.io/px4-ros2-interface-lib/classpx4__ros2_1_1ModeExecutorBase.html) 继承的类。
+- `[1]`: 首先创建一个继承 [`px4_ros2::ModeExecutorBase`](https://auterion.github.io/px4-ros2-interface-lib/classpx4__ros2_1_1ModeExecutorBase.html)。
 - `[2]`: 构造函数采用与执行器相关联的自定义模式，并传递给`ModeExecutorBase`的构造函数。
 - `[3]`: 我们为想要运行的状态定义一个枚举。
 - `[4]`: `onActivate` 在执行器激活时被调用。 此时，我们可以开始遍历这些状态了。
@@ -344,9 +344,10 @@ private:

 以下章节提供了支持的设置点类型列表：

- [MulticopterGotoSetpointType](#go-to-setpoint-multicoptergotosetpointtype): <Badge type="warning" text="MC only" /> Smooth position and (optionally) heading control
- [FwLateralLongitudinalSetpointType](#fixed-wing-lateral-and-longitudinal-setpoint-fwlaterallongitudinalsetpointtype): <Badge type="warning" text="FW only" /> <Badge type="tip" text="main (planned for: PX4 v1.17)" /> Direct control of lateral and longitudinal fixed wing dynamics
+- [MulticopterGotoSetpointType](#go-to-setpoint-multicoptergotosetpointtype): <Badge type="warning" text="MC only" /> 平滑的位置控制以及（可选的）航向控制
+- [FwLateralLongitudinalSetpointType](#fixed-wing-lateral-and-longitudinal-setpoint-fwlaterallongitudinalsetpointtype): <Badge type="warning" text="FW only" /> <Badge type="tip" text="main (planned for: PX4 v1.17)" /> 对横向和纵向固定翼动态的直接控制
 - [DirectActuatorsSetpointType](#direct-actuator-control-setpoint-directactuatorssetpointtype)：直接控制发动机和飞行地面servo setpoints
+- [Rover Setpoints](#rover-setpoints): <Badge type="tip" text="main (planned for: PX4 v1.17)" /> Direct access to rover control setpoints (Position, Speed, Attitude, Rate, Throttle and Steering).

 :::tip
 其他设置点类型目前是实验性的，可在以下网址找到：[px4_ros2/control/setpoint_types/experimental](https://github.com/Auterion/px4-ros2-interface-lib/tree/main/px4_ros2_cpp/include/px4_ros2/control/setpoint_types/experimental)。
@@ -354,18 +355,20 @@ private:
 您可以通过添加一个从 `px4_ros2::SetpointBase` 继承的类来添加您自己的 setpoint 类型， 根据设置点的要求设置配置标志，然后发布任何包含设置点的主题。
 :::

-#### Go-to Setpoint (MulticopterGotoSetpointType)
+#### 转到设置点 (MulticopterGotoSetpointType)

 <Badge type="warning" text="MC only" />

+<Badge type="warning" text="Multicopter only" />
+
 :::info
-This setpoint type is currently only supported for multicopters.
+当前，此设定点类型仅支持多旋翼飞行器。
 :::

-Smoothly control position and (optionally) heading setpoints with the [`px4_ros2::MulticopterGotoSetpointType`](https://github.com/Auterion/px4-ros2-interface-lib/blob/main/px4_ros2_cpp/include/px4_ros2/control/setpoint_types/multicopter/goto.hpp) setpoint type.
-The setpoint type is streamed to FMU based position and heading smoothers formulated with time-optimal, maximum-jerk trajectories, with velocity and acceleration constraints.
+可通过[`px4_ros2::MulticopterGotoSetpointType`](https://github.com/Auterion/px4-ros2-interface-lib/blob/main/px4_ros2_cpp/include/px4_ros2/control/setpoint_types/multicopter/goto.hpp)设定点类型，对位置设定点以及（可选的）航向设定点进行平滑控制。
+设定点类型会被传输至飞控主模块（FMU），该模块基于采用时间最优、最大加加速度轨迹构建的位置及航向平滑器。

-There is also a [`px4_ros2::MulticopterGotoGlobalSetpointType`](https://github.com/Auterion/px4-ros2-interface-lib/blob/main/px4_ros2_cpp/include/px4_ros2/control/setpoint_types/multicopter/goto.hpp) class that allows to send setpoints in global coordinates.
+还有一个 [\`px4_ros2::MulticopterGotoGlobalSetpootType'(https://github.com/Auterion/px4-ros2-interface-lib/blob/main/px4_ros2_cpp/include/px4_ros2/control/setpoint_types/multicopter/goto.hpp)， 该类支持在全局坐标系下发送设定点。

 最简单的用法就是直接向update method中输入一个3D 位置

@@ -551,13 +554,47 @@ _fw_lateral_longitudinal_setpoint->update(setpoint_s, config_s);
 若你想控制的执行器并非用于控制飞行器的运动（例如，而是用于控制有效载荷舵机），请参阅 [below](#controlling-an-independent-actuator-servo)。
 :::

+#### Rover Setpoints
+
+<Badge type="tip" text="main (planned for: PX4 v1.17)" /> <Badge type="warning" text="Experimental" />
+
+The rover modules use a hierarchical structure to propagate setpoints:
+
+![Rover Control Structure](../../assets/middleware/ros2/px4_ros2_interface_lib/rover_control_structure.svg)
+
+:::info
+The "highest" setpoint that is provided will be used within the PX4 rover modules to generate the setpoints that are below it (Overriding them!).
+With this hierarchy there are clear rules for providing a valid control input:
+
+- Provide a position setpoint, **or**
+- One of the setpoints on the "left" (speed **or** throttle) **and** one of the setpoints on the "right" (attitude, rate **or** steering). All combinations of "left" and "right" setpoints are valid.
+
+For ease of use we expose these valid combinations as new SetpointTypes.
+:::
+
+The RoverSetpointTypes exposed through the control interface are combinations of these setpoints that lead to a valid control input:
+
+| SetpointType                                                                                                                        | 安装位置                        | Speed                                            | 油门                                               | Attitude                                         | 频率                                               | Steering                                         | Control Flags                                          |
+| ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------ |
+| [RoverPosition](https://auterion.github.io/px4-ros2-interface-lib/classpx4__ros2_1_1RoverPositionSetpointType.html#details)         | &check; | (&check;) | (&check;) | (&check;) | (&check;) | (&check;) | Position, Velocity, Attitude, Rate, Control Allocation |
+| [RoverSpeedAttitude](https://auterion.github.io/px4-ros2-interface-lib/classpx4__ros2_1_1RoverSpeedAttitudeSetpointType.html)       |                             | &check;                      | (&check;) | &check;                      | (&check;) | (&check;) | Velocity, Attitude, Rate, Control Allocation           |
+| [RoverSpeedRate](https://auterion.github.io/px4-ros2-interface-lib/classpx4__ros2_1_1RoverSpeedRateSetpointType.html)               |                             | &check;                      | (&check;) |                                                  | &check;                      | (&check;) | Velocity, Rate, Control Allocation                     |
+| [RoverSpeedSteering](https://auterion.github.io/px4-ros2-interface-lib/classpx4__ros2_1_1RoverSpeedSteeringSetpointType.html)       |                             | &check;                      | (&check;) |                                                  |                                                  | &check;                      | Velocity, Control Allocation                           |
+| [RoverThrottleAttitude](https://auterion.github.io/px4-ros2-interface-lib/classpx4__ros2_1_1RoverThrottleAttitudeSetpointType.html) |                             |                                                  | &check;                      | &check;                      | (&check;) | (&check;) | Attitude, Rate, Control Allocation                     |
+| [RoverThrottleRate](https://auterion.github.io/px4-ros2-interface-lib/classpx4__ros2_1_1RoverThrottleRateSetpointType.html)         |                             |                                                  | &check;                      |                                                  | &check;                      | (&check;) | Rate, Control Allocation                               |
+| [RoverThrottleSteering](https://auterion.github.io/px4-ros2-interface-lib/classpx4__ros2_1_1RoverThrottleSteeringSetpointType.html) |                             |                                                  | &check;                      |                                                  |                                                  | &check;                      | Control Allocation                                     |
+
+&check; are the setpoints we publish, and (&check;) are generated internally by the PX4 rover modules according to the hierarchy above.
+
+An example for a rover specific drive mode using the `RoverSpeedAttitudeSetpointType` is provided [here](https://github.com/Auterion/px4-ros2-interface-lib/tree/main/examples/cpp/modes/rover_velocity).
+
 ### 控制VTOL

 <Badge type="tip" text="main (planned for: PX4 v1.17)" /> <Badge type="warning" text="Experimental" />

 要在外部飞行模式下控制VTOL，需确保根据当前飞行配置返回正确的设定值类型：

- 多旋翼模式：使用与多旋翼控制兼容的设定值类型。 For example: either the [`MulticopterGotoSetpointType`](#go-to-setpoint-multicoptergotosetpointtype) or the [`TrajectorySetpointType`](https://auterion.github.io/px4-ros2-interface-lib/classpx4__ros2_1_1TrajectorySetpointType.html).
+- 多旋翼模式：使用与多旋翼控制兼容的设定值类型。 例如：要么[`MulticopterGotoSetpootType`](#go-to-setpoint-multicoptergotosetpointtype) 要么[`TrattorySettpointType`](https://auterion.github.io/px4-ros2-interface-lib/classpx4__ros2_1_1TrajectorySetpointType.html)。
 - 固定翼形模式：使用 [`FwLateralLongitudinalSetpointType` ](#fixed-wing-lateral-and-longitudinal-setpoint-fwlaterallongitudinalsetpointtype)。

 只要VTOL在整个外部模式期间始终处于多旋翼模式或固定翼模式中的任意一种，就无需额外处理。
@@ -14,10 +14,7 @@ Experimental
 1. [Control Interface](./px4_ros2_control_interface.md) 允许开发者创建并动态注册使用 ROS2 编写的模式。
   它为发送不同类型的设置点提供了课程，涵盖范围从高级导航任务一直到直接执行器控制。
 2. [导航界面](./px4_ros2_navigation_interface.md) 允许从ROS 2应用程序（如VIO系统）向PX4发送车辆位置估计数。
-
-<!--
-## Overview
-->
+3. [Waypoint Missions](./px4_ros2_waypoint_missions.md) 允许航点飞行任务完全在ROS2中运行。

 ## 在 ROS 2 工作区中安装

@@ -1,6 +1,6 @@
 # PX4 ROS 2 消息翻译节点

-<0/> <1/>
+<Badge type="tip" text="PX4 v1.16" /> <Badge type="warning" text="Experimental" />

 消息翻译节点允许针对不同版本的 PX4 消息编译的 ROS 2 应用程序与更新版本的 PX4 交互。 反之亦然，而不必更改应用程序或PX4一侧。

@@ -0,0 +1,190 @@
+# PX4 ROS 2 Waypoint Missions
+
+<Badge type="tip" text="PX4 v1.16" /> <Badge type="tip" text="Multicopter (only)" /> <Badge type="warning" text="Experimental" />
+
+The [PX4 ROS 2 Interface Library](../ros2/px4_ros2_interface_lib.md) provides a high-level interface for executing ROS-based waypoint missions in ROS 2.
+The main use-case is for creating missions where a custom behavior is required, such as a pickup action within a mission.
+
+:::warning
+ROS 2 missions are not compatible with MAVLink mission definitions, plan files, or ground stations.
+They completely bypass the existing PX4 mission mode and waypoint logic, and cannot be planned or displayed within a ground station.
+:::
+
+ROS 2 waypoint missions are effectively special PX4 ROS 2 custom modes that are run based on the content of a [JSON mission definition](#mission-definition).
+Mission definitions can contain actions that reference existing PX4 modes, such as Takeoff mode or RTL, and can also be extended with arbitrary custom actions written in ROS.
+A [mode executor](px4_ros2_control_interface.md#mode-executor) is used to schedule the modes.
+
+Mission definitions can be hard coded in the custom mission mode (either in code or statically loaded from a JSON string), or directly generated within the application.
+They can also be dynamically loaded based on modification of a particular JSON file — this allows for building a more generic mission framework with a fixed set of custom actions.
+The file can then be written by any other application, for example a HTTP or MAVFTP server.
+
+The current implementation only supports multicopters but is designed to be extendable to any other vehicle type.
+
+## Comparison to PX4/MAVLink Missions
+
+There are some benefits and drawbacks to using ROS-based missions, which are provided in the following paragraphs.
+
+### Benefits
+
+- Allows to extend mission capabilities by registering custom actions.
+- More control over how the mission is executed.
+  A custom trajectory executor can be implemented, which can use any of the existing PX4 setpoint types to track the trajectory.
+- Reduced complexity on the flight controller side by running non-safety-critical and non-real-time code on a more high-level companion computer.
+- It can be extended to support other trajectory types, like Bezier or Dubin curves.
+
+### Drawbacks
+
+- QGroundControl currently does not display the mission or progress during execution, and cannot upload or download a mission.
+  Therefore you will need another mechanism to provide a mission, such as from a web server, a custom GCS, or by generating it directly inside the application.
+- The current implementation only supports multicopters (it uses the [GotoSetpointType](../ros2/px4_ros2_control_interface.md#go-to-setpoint-gotosetpointtype), which only works for multicopters, and VTOL in MC mode).
+  It is designed to be extendable to any other vehicle type.
+
+## 综述
+
+This diagram provides a conceptual overview of the main classes and their interactions:
+
+![Waypoint missions overview diagram](../../assets/middleware/ros2/px4_ros2_interface_lib/waypoint_missions.svg)
+
+<!-- Source: https://drive.google.com/file/d/1BXx4fegVE71eq0kDMMuRnhcLnJeDawWe/view?usp=sharing -->
+
+Missions can be defined in [JSON](#mission-definition), either as a file, or directly inside the application.
+There is a file change monitor (`MissionFileMonitor`), that can be used to automatically load a mission from a specific file whenever it is created by another application (e.g. upload via MAVFTP or a cloud service).
+
+The **`MissionExecutor`** class contains the state machine to progress the mission index, and is at the core of the implementation:
+
+- Internally, it builds on top of the [Modes and Mode Executors](px4_ros2_control_interface.md#overview) and registers itself through a custom mode and executor with PX4.
+- It handles switching in and out of missions: it gets activated when the user switches to the custom mode that represents the mission and the vehicle is armed.
+  The mode name can be customized (`My Mission` in the example below).
+  The mission can be paused, which makes the vehicle switch into _Hold mode_.
+  To resume the mission, the custom mode has to be selected again.
+- When an action switches into another mode (for example Takeoff), QGroundControl will display this mode until it is completed.
+  The mission executor will then automatically continue.
+- Custom actions can be registered.
+- The mission can be set.
+  It then checks that all the actions which the mission defines are available and can be run.
+- The state can be stored persistently by providing a file name, allowing for battery swapping.
+
+The **`ActionInterface`** is an interface class for custom actions.
+They are identified by a name, and any number of these can be registered with the `MissionExecutor`.
+A custom action is then run whenever a mission item with matching name is executed, and any extra arguments from the JSON definition are passed as arguments (for example an altitude for a takeoff action).
+Actions can call other actions, run any mode (PX4 or external by its ID), run a trajectory, or run any other external action before deciding when to continue the mission.
+
+There is a set of default actions, for example for RTL, Land, etc.
+These simply trigger the corresponding PX4 mode.
+They can be disabled or replaced with custom implementations.
+There are also some special actions (which can be replaced as well):
+
+- `OnFailure`: this is called in case of a failure, e.g. a mode switch failed, a non-existing action is called (by another action) or by an explicit call to `MissionExecutor::abort()`.
+  The default is to run RTL, with fallback to Land.
+- `OnResume`: this is called when resuming a mission (either from the ground or in-air).
+  It handles a number of cases:
+  - when called with an argument `action="storeState"`: this can be used to store the current position when the mission is deactivated, so it can be resumed from the same position.
+    Currently it does not store anything.
+  - otherwise, when called without a valid mission index or 0, it directly continues.
+  - otherwise, when called while in-air, it also directly continues.
+  - otherwise, if landed and if the current mission item is an action that supports resuming from landed, it continues to let the action handle the resuming.
+  - otherwise, if landed, it finds the takeoff action from the mission, runs it, and then flies to the previous waypoint from the current index to continue the mission.
+- `ChangeSettings`: this can be used to change the mission settings, such as the velocity.
+  The settings are applied to all following items in the mission.
+
+The **`TrajectoryExecutorInterface`** is an interface class to execute segments of a trajectory.
+It can use any setpoint that PX4 and the current vehicle supports for tracking the trajectory.
+This class is vehicle-type specific.
+The current default implementation (`multicopter::WaypointTrajectoryExecutor`) uses a Goto setpoint (and thus is limited to multicopters).
+The default can be replaced with a custom implementation.
+
+## 用法
+
+The following provides a small example.
+It defines a custom action and a mission that uses it.
+
+```c++
+class CustomAction : public px4_ros2::ActionInterface {
+public:
+  CustomAction(px4_ros2::ModeBase & mode) : _node(mode.node()) { }
+
+  std::string name() const override {return "customAction";}
+
+  void run(
+    const std::shared_ptr<px4_ros2::ActionHandler> & handler,
+    const px4_ros2::ActionArguments & arguments,
+    const std::function<void()> & on_completed) override
+  {
+    RCLCPP_INFO(_node.get_logger(), "Running custom action");
+    // Do something...
+
+    on_completed();
+  }
+private:
+  rclcpp::Node & _node;
+};
+
+class MyMission {
+public:
+  MyMission(const std::shared_ptr<rclcpp::Node> & node) : _node(node)
+  {
+    const auto mission =  px4_ros2::Mission(nlohmann::json::parse(R"(
+  {
+    "version": 1,
+    "mission": {
+        "items": [
+           {
+               "type": "takeoff"
+           },
+           {
+               "type": "navigation",
+               "navigationType": "waypoint",
+               "x": 47.3977419,
+               "y": 8.5455939,
+               "z": 500,
+               "frame": "global"
+           },
+           {
+               "type": "navigation",
+               "navigationType": "waypoint",
+               "x": 47.39791657,
+               "y": 8.54595214,
+               "z": 500,
+               "frame": "global"
+           },
+           {
+               "type": "customAction"
+           },
+           {
+               "type": "rtl"
+           }
+        ]
+    }
+  }
+)"));
+    _mission_executor = std::make_unique<px4_ros2::MissionExecutor>("My Mission",
+      px4_ros2::MissionExecutor::Configuration().addCustomAction<CustomAction>(), *node);
+
+    if (!_mission_executor->doRegister()) {
+      throw std::runtime_error("Failed to register mission executor");
+    }
+    _mission_executor->setMission(mission);
+
+    _mission_executor->onProgressUpdate([&](int current_index) {
+        RCLCPP_INFO(_node->get_logger(), "Current mission index: %i", current_index);
+      });
+    _mission_executor->onCompleted([&] {
+        RCLCPP_INFO(_node->get_logger(), "Mission completed callback");
+      });
+  }
+
+private:
+  std::shared_ptr<rclcpp::Node> _node;
+  std::unique_ptr<px4_ros2::MissionExecutor> _mission_executor;
+};
+```
+
+A full example with a few custom actions can be found under [github.com/Auterion/px4-ros2-interface-lib/tree/main/examples/cpp/modes/mission/include](https://github.com/Auterion/px4-ros2-interface-lib/tree/main/examples/cpp/modes/mission/include).
+
+## Mission Definition
+
+The mission JSON file can contain mission defaults and a list of mission items, including user-defined types with custom arguments.
+Waypoint coordinates currently need to be defined in global frame, and other frame types might be added in future.
+
+The schema can be found under [github.com/Auterion/px4-ros2-interface-lib/blob/main/mission/schema.yaml](https://github.com/Auterion/px4-ros2-interface-lib/blob/main/mission/schema.yaml).
+It provides more details and can be used to validate a JSON file.