ArduPilot 固定翼脚本化特技飞行Scripted Aerobatics完全指南从特技表、AUTO 任务到“开关即用”的落地实战【免费下载链接】ardupilotArduPlane, ArduCopter, ArduRover, ArduSub source项目地址: https://gitcode.com/GitHub_Trending/ar/ardupilotArduPilot 的 Scripted Aerobatics 是一套运行在固定翼飞控 Lua 脚本环境中的特技飞行系统它让固定翼无人机能够在 AUTO 任务中自动执行横滚、筋斗、古巴八字、殷麦曼转弯等数十种标准特技也能通过遥控器拨杆随时触发“开关即用”的预编程特技。本文以仓库中 libraries/AP_Scripting/applets/Aerobatics/FixedWing/README.md 为主体骨架结合 3272 行的 plane_aerobatics.lua 源码与 Schedules 下的完整套路文件带你从特技 ID 表、脚本加载、飞控参数设置一直深入到源码级的路径生成原理与自定义特技开发读完即可在 SITL 中复现并移植到真实飞机。Scripted Aerobatics 是什么一套“轨迹式”特技系统plane_aerobatics.lua实现的是**轨迹式Trajectory-Based特技飞行每个特技在几何上被定义为一组精确的航迹path脚本内部由路径控制器、横滚控制器、偏航控制器、空速/高度控制器共同闭环跟踪飞机严格沿着空间中的几何路径飞行。这与同目录下 RateBased/sport_aerobatics.lua 的速率式Rate-Based**方案形成互补——速率式只控制姿态角速率、不维持地理航迹对飞机性能和抗风能力要求更低适合难以长时间保持垂直爬升与 90° 侧飞knife-edge的机型但机动形状在强风中会走样。注意本文档描述的轨迹式特技需要ArduPilot 4.4.1 或更高版本才能运行见 README.md 顶部说明。官方反复强调尤其是特技飞行务必先在 SITL 中充分测试、理解每个特技的行为并准备好在必要时切换手动接管。特技系统在三个层面工作单个特技trick一个几何动作如 Loop、Immelmann用 ID 号引用套路schedule由多个特技按顺序编排的完整特技表演序列可整体作为一个“大特技”调用触发方式在 AUTO 任务中通过NAV_SCRIPT_TIME航点触发或通过遥控器开关tricks on a switch随时触发。全部 32 个可用特技ID / 参数 / 方向反转下表完整收录了 README.md 中的特技表。每个特技有一个 ID 号用于 AUTO 任务或TRIKn_ID参数特技以当前地面航迹ground track作为机动的方向基线。“Turnaround”列表示该特技是否导致航向反转——这直接影响它在 AUTO 任务中的编排方式。特技完成后飞行模式会恢复到特技开始前的模式若此前处于 CRUISE 模式其航迹与高度会被重置为模式恢复时的值。AUTO 任务中的特技必须位于两个航点之间以建立地面航迹。| ID | 名称 | Arg1 | Arg2 | Arg3 | Arg4 | Turnaround | | -- | --- | --- | --- | --- | --- | --- | | 1 | Figure Eight八字 | radius | bank angle | | | 否 | | 2 | Loop筋斗 | radius | bank angle | num loops | | 否 | | 3 | Horizontal Rectangle水平矩形 | length | width | radius | bank angle | 否 | | 4 | Climbing Circle爬升圆 | radius | height | bank angle | | 否 | | 5 | vertical Box垂直箱形 | length | height | radius | | 否 | | 6 | Immelmann (FastRoll)殷麦曼快速横滚 | radius | | | | 是 | | 7 | Straight Roll直线横滚 | length | num rolls | | | 否 | | 8 | Rolling Circle横滚盘旋 | radius | num rolls | | | 否 | | 9 | Half Cuban Eight半古巴八字 | radius | | | | 是 | | 10 | Half Reverse Cuban Eight半反向古巴八字 | radius | | | | 是 | | 11 | Cuban Eight古巴八字 | radius | | | | 否 | | 12 | Humpty Bump | radius | height | | | 是 | | 13 | Straight Flight直线飞行 | length | bank angle | | | 否 | | 14 | Scale Figure Eight缩放八字 | radius | bank angle | | | 否 | | 15 | Immelmann Turn殷麦曼转弯 | radius | | | | 是 | | 16 | Split-S破 S | radius | | | | 是 | | 17 | Upline-4545° 上升线 | radius | height gain | | | 否 | | 18 | Downline-4545° 下降线 | radius | height loss | | | 否 | | 19 | Stall Turn失速转弯实验性 | radius | height | direction | | 是 | | 20 | Procedure Turn程序转弯 | radius | bank angle | step-out | | 是 | | 23 | Half Climbing Circle半爬升圆 | radius | height | bank angle | | 是 | | 25 | Laydown Humpty | radius | height | | | 是 | | 26 | Barrel Roll桶滚 | radius | length | num spirals | | 否 | | 27 | Straight Hold直线保持 | length | bank angle | | | 否 | | 28 | Partial Circle部分圆弧 | radius | bank angle | arc angle | | 否 | | 31 | Multi Point Roll多点横滚 | length | num points | hold frac | pts to do | 否 | | 32 | Side Step侧步 | width | length | | | 否 |特技参数Arg1–Arg4如何理解每个特技的参数是该机动执行所需的几何/数量参数例如横滚的长度米、筋斗的半径米、横滚圈数、机动高度等。以多点横滚ID 31为例length整个机动在水平方向上的长度米num points360° 一圈分几个“点”位hold fraction机动中“不滚动”停顿保持所占的比例pts to do实际要飞几个点。文档中的例子——想要“4 点横滚中的 2 点”从正飞滚过 90° 停顿再滚过 90° 结束在倒飞全程 100 米点与点之间的停顿占整个机动长度的 50%则四个参数为Length 100, num points 4, hold fraction 0.5, pts to do 2切记该机动结束时飞机处于倒飞状态下一个特技必须从这一姿态开始规划。这正是套路文件需要精心编排顺序的原因。特技表中的“未列出”特技在脚本源码中还存在一些未出现在上表的专业特技specialised manoeuvres它们不用于“开关即用”的普通特技而是被下方讲到的套路schedule文件内部调用其中部分在 Schedules/README.md 中有说明。例如从 NZClubMan.txt 源码可以看到upline_45、downline_45、straight_align等内部函数它们通过 make_paths 组合path_vertical_arc、path_straight等基础路径原语构造。加载脚本三步把特技系统跑起来把plane_aerobatics.lua放到 microSD 卡的APM/SCRIPTS目录可通过 MAVFtp 上传然后设置以下三个脚本参数见 README.mdSCR_ENABLE 1SCR_HEAP_SIZE 300000SCR_VM_I_COUNT 200000设置SCR_ENABLE后需要刷新参数然后重启飞控以启动脚本执行。若使用速率式版本sport_aerobatics.lua其堆栈更小只需SCR_HEAP_SIZE 150000、SCR_VM_I_COUNT 100000见 RateBased/README.md。飞机设置特技性能的基础轨迹式特技对飞机的 ACRO 模式性能要求较高README.md 明确要求YAW_RATE_ENABLE 1—— 启用偏航角速率控制器ACRO_YAW_RATE 90—— 偏航角速率上限单位 度/秒该值取决于机型能力90 dps 左右是合理起点。随后需要在AUTOTUNE 模式下飞行来回拨动方向舵摇杆直到飞控报告偏航角速率调参完成。为了获得理想效果尤其是精确的 Rolling Circle 需要的俯仰/偏航调优通常还要结合日志分析手动微调各轴参数。注意速率式版本sport_aerobatics.lua同样需要这两项设置而且即使飞机无法维持 90° 侧飞knife-edge也仍然需要开启偏航角速率控制器——因为 180° 倒飞、筋斗、横滚这些动作一般还是能做到的见 RateBased/README.md。在 AUTO 任务中使用特技NAV_SCRIPT_TIME在 Mission Planner 中NAV_SCRIPT_TIME显示为SCRIPT_TIME航点元素即可触发特技。该任务元素携带以下参数见 README.md特技命令 ID上表中的数字或套路 ID超时时间秒最多四个特技参数对上表中的 Arg1–Arg4。在源码中该 MAVLink 命令号为42702见 plane_aerobatics.lua 的local NAV_SCRIPT_TIME 42702脚本通过vehicle:nav_script_time()读取 ID 与参数、用vehicle:nav_script_time_done()报告完成见 plane_aerobatics.lua 与 plane_aerobatics.lua。编排规则特技系统使用前一个航点与后一个航点的位置来对准机动方向。因此任务应这样规划普通航点机动开始前的位置 NAV_SCRIPT_TIME特技/套路 ID 足够长的超时 普通航点机动结束后的位置速率式版本还支持在两个航点之间编排连续多个特技并可用 ID 5Pause特技来推移特技开始位置或在连续特技之间插入间隔时间见 RateBased/README.md。开关即用Tricks on a Switch最多 11 个预编程特技轨迹式版本可以在以下飞行模式中通过遥控器开关触发特技CIRCLE、STABILIZE、ACRO、FBWA、FBWB、CRUISE、LOITER。配置流程按 README.md设置TRIK_ENABLE 1重启脚本或整机重启设置TRIK_COUNT为可用特技数量最大 11重启并刷新参数此时每个特技会出现 5 个参数TRIKn_ID特技 ID来自上面的表TRIKn_ARG1/TRIKn_ARG2/TRIKn_ARG3/TRIKn_ARG4特技参数分配两个控制通道激活通道推荐 3 段开关设RCn_OPTION 300选择通道推荐旋钮可覆盖 11 个特技设RCn_OPTION 301。重要提醒这些TRIKn_*参数是由 Lua 脚本在运行时创建的不是固件内置参数。因此若从参数文件加载必须等脚本实际运行后这些参数才会存在见 README.md。在源码中脚本通过rc:find_channel_for_option(TRIK_SEL_FN:get())定位选择通道、用rc:get_aux_cached(TRIK_ACT_FN:get())读取激活通道状态见 plane_aerobatics.lua 与 plane_aerobatics.luaTRIK_COUNT的取值被constrain在 1–11 之间见 plane_aerobatics.lua。飞行动作语义激活通道处于中间位置时转动选择旋钮GCS 会显示当前选中的特技激活通道拨到顶部高位置特技开始执行激活通道拨到底部低位置取消正在执行的特技并停止特技系统切换飞行模式也会取消当前特技。速率式版本使用独立的参数前缀TRIKRn_*TRIKR_COUNT最大 11多出来的名额用于存放同型特技变体比如 90° 与 180° 两种侧飞、TRIKRn_ID、TRIKRn_ARG1、TRIKRn_ARG2TRIKRn_ARG3/ARG4预留未用。它不需要 300 通道也能工作——TRIKR_COUNT非零且存在一个 301 通道即可也可以直接用 GCS 的 AUX Function 页面从地面站触发见 RateBased/README.md。AEROM_ 参数全解来自源码的默认值与作用README.md 列出了若干关键路径跟踪参数。脚本运行时通过param:add_table(PARAM_TABLE_KEY, AEROM_, 40)注册了 40 个槽位的参数表见 plane_aerobatics.lua。下表合并了文档要点与源码中的完整默认值参数默认值说明AEROM_ANG_ACCEL6000最大角加速度度/秒²。调小可获得更平滑的飞行但延迟更大AEROM_ANG_TC0.1修正滚转角误差的时间常数秒。调小使横滚更干脆但更易振荡AEROM_ENTRY_RATE60进入/退出横滚变化的滚转速率度/秒AEROM_KE_RUDD25巡航速度下侧飞knife-edge保持高度所需的方向舵百分比AEROM_KE_RUDD_LK0.25预判方向舵提前施加的时间秒用于抵消侧飞的滞后AEROM_THR_MIN0所有特技动作的最小油门百分比AEROM_THR_BOOST50被标记为 throttle boost 的特技最小油门百分比AEROM_YAW_ACCEL1500最大偏航加速度度/秒²调低可柔化偏航控制AEROM_BOX_WIDTH400特技箱体长度箱体中心由套路起点定义AEROM_PATH_SCALE1.0所有机动的整体缩放系数1 放大、1 缩小、负值镜像左右互易AEROM_ALT_ABORT15从特技/套路起点算起的最大高度损失米超过则中止AEROM_THR_PIT_FF—俯仰-油门前馈油门随俯仰角变化的前馈补偿AEROM_SPD_P/AEROM_SPD_I—空速控制 PIDAEROM_ROL_COR_TC—滚转修正时间常数AEROM_TIME_COR_P/AEROM_ERR_COR_P/AEROM_ERR_COR_D—时间/位置误差修正控制器AEROM_THR_LKAHD1油门前瞻时间秒AEROM_LKAHD0.5路径前瞻时间秒AEROM_STALL_THR40失速转弯Stall Turn相关油门阈值AEROM_STALL_PIT-20失速转弯相关俯仰阈值AEROM_TS_P/AEROM_TS_I/AEROM_TS_SPDMAX/AEROM_TS_RATE0.33 / 0.33 / 0.0 / 4.0空速调整控制器speed adjust参数AEROM_MIS_ANGLE0.0任务对准角度修正AEROM_OPTIONS0行为选项位掩码见下AEROM_DEBUG0调试输出开关源码中的选项位定义见 plane_aerobatics.luaABORT_RTL 10中止特技后返回起飞点RTLMSG_ADD_AT 11GCS/OSD 消息中附加时间信息DUAL_AIRCRAFT 12双机编队模式配合仓库中dual_plane.sh/dual_log.py脚本使用。同时源码会在检测到旧参数值时自动修正如AEROM_ANG_ACCEL在 0–100 之间时被强制写回 3000AEROM_ANG_TC 1.0时被写回 0.2见 plane_aerobatics.lua兼容从早期版本升级的用户。源码级原理路径原语与机动组合器轨迹式特技的实现核心是把每个机动拆解为**路径组件path component与横滚组件roll component**的组合见 plane_aerobatics.lua 的Path(path_component, roll_component)。从源码可见的基础原语path_straight(distance)直线段见 plane_aerobatics.luapath_vertical_arc(radius, angle)垂直面圆弧筋斗的基本构成见 plane_aerobatics.luapath_horizontal_arc(radius, angle, height_gain)水平面圆弧爬升圆、部分圆弧的基本构成见 plane_aerobatics.luapath_cylinder(radius, length, num_spirals)螺旋圆柱桶滚 Barrel Roll 的构成见 plane_aerobatics.luaroll_angle(angle)/roll_angle_entry_exit(angle)/roll_sequence(seq)定值横滚、带进入/退出过渡的横滚、以及按{比例, 角度}序列分段的横滚多点横滚就靠它实现见 plane_aerobatics.lua、plane_aerobatics.lua、plane_aerobatics.luaqorient(roll_deg, pitch_deg, yaw_deg)显式设定机动中飞机的目标姿态四元数见 plane_aerobatics.lua路径属性表path_attribs支持set_orient、thr_boost、message、rate_override等附加属性见 plane_aerobatics.lua。这些原语由make_paths(name, paths)见 plane_aerobatics.lua组装成完整的特技函数例如 Loop 本质就是path_vertical_arc(radius, 360*num_loops)加横滚进入/退出见 NZClubMan.txt 中重定义的loop函数。整条航迹再由脚本内置的 PI 控制器族——横滚roll_angle系列、空速控制器speed_controller、空速调整控制器speed_adjust_controllerplane_aerobatics.lua 与 plane_aerobatics.lua——闭环跟踪。预定义套路Schedules整场特技表演一步调用Schedules 目录提供了多种现成的完整特技表演序列包括 F3AF23、F3AF25、F3AP23、F3AP25、F4CScaleExample、NZClubMan、AirShow、SportPlane_Airshow 与 stall_turn_test。它们既可用于 AUTO 任务也可作为“开关即用”的单个特技见 Schedules/README.md。安装trickNN.txt 命名规则把套路文件复制或符号链接为scripts/目录与plane_aerobatics.lua同目录下的trickNN.txtNN就是要使用的特技编号。例如NZClubMan.txt → trick94.txt之后把TRIK3_ID设为 94作为第 3 个开关特技或在NAV_SCRIPT_TIME任务中直接填 94 即可调用整个新西兰 Clubman 套路。注意NZClubMan.txt源码注释特别说明该文件要放在microSD 根目录不是 APM 目录下。缩放与镜像适配机型与场地套路往往很大可以用AEROM_PATH_SCALE统一缩放所有特技与套路AEROM_PATH_SCALE 0.5整体缩小一半负值镜像如-0.5表示“缩小一半 左右镜像”适合把为“从右向左”设计的套路如 NZClubMan 默认从左向右飞行改成顺应风向的“从左向右”。箱体内对齐align_center 与 align_box两个命令用于把特技摆放到特技箱体box内的正确位置见 Schedules/README.mdalign_center延迟下一个特技开始直到飞行到达箱体中心若已飞过中心沿飞行方向特技立即开始align_box n延迟下一个特技开始直到到达n × (半箱宽 − 特技半径)的位置n1 即箱体末端用于下一个特技的摆放。同样已越过则立即开始。AEROM_BOX_WIDTH定义箱体总长且受AEROM_PATH_SCALE缩放影响套路的起点即箱体中心。GCS/OSD 消息与油门增强name: 字符串在选中或执行该特技时显示特技名称message: 字符串放在某特技前一行在该特技开始时显示消息thr_boost: true对该特技指令提高油门输出适用于需要更多动力的动作如垂直爬升类。完整示例AirShow.txt 剖析AirShow.txt 是一个“可加载文件中的示例表演”同时演示了如何定义全新的路径函数。其骨架为# 使用 name: 给序列命名 name: SuperAirShow # 自定义新特技三角形筋斗 function triangular_loop(radius, height, arg3, arg4) ... return make_paths(triangular_loop, { { path_straight(base * 1/5), roll_angle(180) }, { path_straight(base * 2/5), roll_angle(0) }, { path_vertical_arc(radius, 135), roll_angle(0) }, ... }) end # 跨箱体“高帽”动作用于桶滚后回位 function crossbox_tophat(radius, height, width, arg4) return make_paths(crossbox_tophat, { { path_vertical_arc(radius, 90), roll_angle(0) }, { path_straight((height-2*radius)), roll_sequence({{1,0}, {1, 90}, {1, 0}}), set_orientqorient(0,90,90) }, ... }) end # 编排表演对齐 消息 特技调用 message: Loop loop 25 0 1 align_box 1 message: HalfReverseCubanEight half_reverse_cuban_eight 25 align_center message: ScaleFigureEight scale_figure_eight -40 -45 ...从中可以掌握套路文件的三层语法头部的 Lua 函数与主脚本plane_aerobatics.lua相同的语法定义新特技functionmake_paths 路径/横滚原语所以新特技可以“随套路文件一起被创建和加载”属性指令name:、message:、thr_boost: true特技调用序列特技名 参数穿插align_center/align_box n/straight_align等对齐命令。更复杂的参考可见 NZClubMan.txt398 行的 F3AF23.txt 等文件亦然其中multi_point_roll(length, N, hold_frac, num_points)用roll_sequence在 Lua 中动态构建多点横滚序列展示了速率/比例的编程式组合能力。速率式变体sport_aerobatics.lua速览若你的飞机无法完成精确轨迹机动尤其垂直爬升与 90° 侧飞RateBased/sport_aerobatics.lua 提供了 8 个基于姿态角速率的特技见 RateBased/README.md| ID | 名称 | Arg1 | Arg2 | Turnaround | | -- | --- | --- | --- | --- | | 1 | Roll(s) | rollrate (dps) | num rolls | 否 | | 2 | Loop(s)/TurnAround | pitchrate (dps) | num loops 或 turnaround(0) | num0 时是 | | 3 | Rolling Circle | yawrate (dps) | rollrate (dps) | 否 | | 4 | KnifeEdge | roll angle (deg) | length (sec) | 否 | | 5 | Pause | length (sec) | na | 否 | | 6 | KnifeEdge Circle | yawrate (dps) | na | 否 | | 7 | 4 point roll | rollrate (dps) | pause in sec | 否 | | 8 | Split-S | pitchrate (dps) | rollrate (dps) | 是 |速率式有一个关键设计它不维持地理航迹只维持姿态速率因此即使抗不住 90° 侧飞的飞机也通常能完成 180° 倒飞、筋斗与横滚且强风中也能执行只是形状不完美。Rolling Circle 的圈时 360 / yawrate应保证在该时间内横滚圈数为整数即rollrate 圈数 × yawrate多数情况下负速率表示反向如 -45 表示以 45 dps 向左滚。其控制参数以AEROR_为前缀核心两个AEROR_HGT_KE_BIAS侧飞高度补偿飞机滚入 90° 位置时立即施加方向舵而不等高度变化与AEROR_THR_FF油门随俯仰角变化的前馈其余为脚本内高度/空速 PID 控制器参数。测试与辅助工具仓库在 Aerobatics 目录下提供了三个开发辅助脚本view_paths.py可视化绘制特技/套路的几何路径非常适合在 SITL 里先“看”轨迹再上真机dual_log.py 与 dual_plane.sh配合AEROM_OPTIONS的DUAL_AIRCRAFT位实现双机编队特技的开发与日志处理。官方建议的完整开发流程是先在 SITL 中加载脚本 → 用view_paths.py校验每个特技的几何形状 → 用开关逐步触发验证行为 → 再在真实飞机上以充足的离地高度和随时手动接管为前提试飞。文档也再次强调你需要一架性能足够的飞机并做好随时手动接管的准备。结语Scripted Aerobatics 把特技飞行的“几何定义”“轨迹跟踪”和“任务/遥控触发”三层完全脚本化底层是make_paths组合的路径与横滚原语中层是 32 个标准特技与trickNN.txt套路文件上层则是NAV_SCRIPT_TIME任务元素与RCn_OPTION 300/301的开关映射。配合AEROM_PATH_SCALE、AEROM_BOX_WIDTH、align_center/align_box与thr_boost你可以把一套表演无缝缩放到任意机型和场地甚至像 AirShow.txt 那样直接在套路文件里用 Lua 编写全新特技。在起飞前请务必在 SITL 中验证每一个动作理解特技之间的姿态衔接——尤其是倒飞退出的特技——再带着这份理解飞向真实的蓝天。【免费下载链接】ardupilotArduPlane, ArduCopter, ArduRover, ArduSub source项目地址: https://gitcode.com/GitHub_Trending/ar/ardupilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考