feat: add guide point command with path and yaw options

msg_definitions/VKFly.xml

@@ -686,6 +686,29 @@
       <entry value="12" name="VKFLY_VINS_CONFIG_SET_PRIME_VINS"></entry>
     </enum>
 
+    <enum name="VKFLY_GUIDE_PATH_TYPE">
+      <description>Approach path for VKFLY_CMD_DO_GUIDE_POINT. Applies to this command only.</description>
+      <entry value="0" name="VKFLY_GUIDE_PATH_ALT_THEN_XY">
+        <description>Reach the target altitude at the starting horizontal position, then fly horizontally to the target.</description>
+      </entry>
+      <entry value="1" name="VKFLY_GUIDE_PATH_XY_THEN_ALT">
+        <description>Fly horizontally at the starting altitude, then change altitude at the target horizontal position.</description>
+      </entry>
+      <entry value="2" name="VKFLY_GUIDE_PATH_LINEAR">
+        <description>Move along a straight three-dimensional path with coordinated horizontal and vertical progress.</description>
+      </entry>
+    </enum>
+
+    <enum name="VKFLY_GUIDE_YAW_MODE">
+      <description>Heading during the approach. Does not change the arrival yaw specified in param4.</description>
+      <entry value="0" name="VKFLY_GUIDE_YAW_FACE_TARGET">
+        <description>Face the target. For targets within 5 m, keep the current heading.</description>
+      </entry>
+      <entry value="1" name="VKFLY_GUIDE_YAW_HOLD">
+        <description>Keep the vehicle heading captured when this command is accepted throughout the approach.</description>
+      </entry>
+    </enum>
+
     <enum name="MAV_CMD">
       <description> VKFLY custom CMD </description>
       <entry value="44010" name="VKFLY_CMD_NAV_WP" hasLocation="true" isDestination="true">
@@ -988,6 +1011,18 @@
            1 means vel_ctl</param>
         <param index="5" label="act_param"> NAN means invalid.</param>
       </entry>
+
+      <entry value="44075" name="VKFLY_CMD_DO_GUIDE_POINT" hasLocation="true"
+        isDestination="true">
+        <description>Guide a multicopter to a WGS84 global position, then hold position. Use COMMAND_INT. Parameters follow MAV_CMD_DO_REPOSITION except param2 selects the approach path and param3 selects the approach heading mode. Path and heading options apply only to this command and are not persistent parameters.</description>
+        <param index="1" label="Speed" units="m/s" minValue="-1" maxValue="655.35">Ground speed. A negative value or NaN selects the current implementation default of 5 m/s.</param>
+        <param index="2" label="Guide Path" enum="VKFLY_GUIDE_PATH_TYPE" minValue="0" maxValue="2" increment="1">Required approach path: 0 altitude then horizontal, 1 horizontal then altitude, 2 linear. Other values, including NaN, are rejected.</param>
+        <param index="3" label="Yaw Mode" enum="VKFLY_GUIDE_YAW_MODE" minValue="0" maxValue="1" increment="1">Required heading mode during the approach: 0 face target, 1 keep the heading at command acceptance. Other values, including NaN, are rejected.</param>
+        <param index="4" label="Yaw" units="deg">Target yaw after arrival. NaN leaves the approach heading unchanged.</param>
+        <param index="5" label="Latitude">Target latitude. In COMMAND_INT, use x in degrees multiplied by 1e7.</param>
+        <param index="6" label="Longitude">Target longitude. In COMMAND_INT, use y in degrees multiplied by 1e7.</param>
+        <param index="7" label="Altitude" units="m">Target altitude in the command frame. NaN keeps the current altitude. GLOBAL frames use AMSL altitude; GLOBAL_RELATIVE_ALT frames use altitude above takeoff.</param>
+      </entry>
     </enum>
   </enums>
 

readme.md

@@ -1841,6 +1841,38 @@ param3 = (float)((int8)速度 + (uint8)(时间<<8))
 | param4 | quick_act_mode选项,仅在控制选项为2时有效,指定当前控制模式,0为长度控制,1为速度控制,其余控制选项该参数为NAN|
 | param5 | quick_act_param参数,仅在控制选项为2且ctl_mode非NAN时有效,ctl_mode为0时进行长度控制，范围为[0,10000],单位为cm,ctl_mode为1时进行速度控制，范围为[-300,300],单位为cm/s,其余控制选项该参数为NAN|
 
+### 5.48 自定义指点 VKFLY_CMD_DO_GUIDE_POINT
+
+命令号 **44075**，当前仅多旋翼支持，使用 `COMMAND_INT`。
+参数作用参考多旋翼 `MAV_CMD_DO_REPOSITION`，其中 `param2` 改为本次路径方式，
+`param3` 改为飞行途中航向方式。路径与航向均为任务级选项，不写入持久化参数。
+
+| 参数 | 说明 |
+| ---- | ---- |
+| param1 | 地速，m/s；负值或 NaN 使用现有实现默认值 5 m/s。速度存储范围上限 655.35 m/s，正无穷及超出范围的值拒绝执行 |
+| param2 | `VKFLY_GUIDE_PATH_TYPE`：0 先原地到目标高度再水平飞行；1 先保持起始高度水平到点再升降；2 协调斜坡线性移动 |
+| param3 | `VKFLY_GUIDE_YAW_MODE`：0 朝向目标点（水平距离小于 5 m 时保持当前航向）；1 在整个接近过程中保持接受指令时的机头航向 |
+| param4 | 到点后悬停的目标航向，deg；NaN 不另指定，到点后仍保持接近阶段的目标航向 |
+| x（param5） | 目标纬度，deg × 1e7 |
+| y（param6） | 目标经度，deg × 1e7 |
+| z（param7） | 目标高度，m；NaN 保持当前高度。GLOBAL 为海拔高度，GLOBAL_RELATIVE_ALT 为相对起飞点高度 |
+
+支持 `MAV_FRAME_GLOBAL`、`MAV_FRAME_GLOBAL_INT`、
+`MAV_FRAME_GLOBAL_RELATIVE_ALT` 和 `MAV_FRAME_GLOBAL_RELATIVE_ALT_INT`。
+需已解锁、在空中且 INS/GPS 正常；不满足时返回 `MAV_RESULT_TEMPORARILY_REJECTED`。
+`COMMAND_LONG` 返回 `MAV_RESULT_COMMAND_INT_ONLY`。
+`param2` 必须精确为 0/1/2，`param3` 必须精确为 0/1；
+NaN、无穷、非整数或越界值返回 `MAV_RESULT_DENIED`，不会改写当前指点任务。
+
+例如：`param1=5, param2=2, param3=1, param4=NaN` 表示以 5 m/s 的水平速度上限
+沿协调斜坡到点，途中和到点后保持接收时的机头航向。
+将 `param4` 设为 90，则途中仍保持原航向，到点后再转向东。
+
+标准 `MAV_CMD_DO_REPOSITION` 的参数含义不变，仍采用默认斜坡接近、朝目标点；
+不会继承上一条自定义指点命令的路径或固定航向。
+原有指点后降落、备降点入口也显式使用默认斜坡接近、朝目标点。
+固定翼和 VTOL 暂不支持此新命令。
+
 ## 6 飞控数据 LOG 读取
 
 ### 6.1 获取日志列表