ArduPilot 直升机怠速控制脚本（Heli_idle_control）完整指南：地面怠速 RPM 手动/自动闭环控制-二趣网

ArduPilot 直升机怠速控制脚本（Heli_idle_control）完整指南：地面怠速 RPM 手动/自动闭环控制

【免费下载链接】ardupilotArduPlane, ArduCopter, ArduRover, ArduSub source项目地址: https://gitcode.com/GitHub_Trending/ar/ardupilot

导读

本文档围绕 ArduPilot 仓库中 libraries/AP_Scripting/applets/Heli_idle_control.md 及同名 Lua 脚本 Heli_idle_control.lua 展开，讲解传统直升机（trad-heli）在地面怠速工况下，如何通过 Lua 脚本对旋翼转速（RPM）进行手动或自动闭环控制。读完本文你将掌握：IDLE_* 参数表的完整语义与调参方法、RCx_OPTION=301 辅助电位器的接线与配置、脚本内部 PI 控制器的实现原理与运行流程，以及如何将该 applet 安装到飞控并与其他旋翼转速控制（RSC）参数协同工作。

脚本定位与使用前提

Heli_idle_control 是 ArduPilot Lua Applets 集合（见 libraries/AP_Scripting/applets/README.md）中的一个完整应用。与 examples 目录下的教学示例不同，这类 applet 无需用户编辑脚本本身即可使用——每个 applet 都有一个 .md 文件描述其运行方式与所需参数，用户只需将 .lua 文件复制到飞控 SD 卡的APM/scripts目录即可完成安装。

安装与运行有三个硬性前提：

固件必须启用脚本支持（SCR_ENABLE = 1）；
飞控硬件必须具有运行 Lua 脚本的能力（需有一定 Flash/RAM 资源）；
目标机型是传统直升机（trad-heli），因为该脚本依赖H_RSC_*（直升机旋翼转速控制）参数与 RPM 传感器输入。

脚本启动时会向 GCS 发送idle_control_running文本消息（Heli_idle_control.lua），可作为脚本是否正常加载的快速验证手段。

参数表 IDLE_*：定义与默认值

脚本通过 ArduPilot Lua 的脚本参数表机制动态注册参数。关键代码如下：

local PARAM_TABLE_KEY = 73 local PARAM_TABLE_PREFIX = 'IDLE_' assert(param:add_table(PARAM_TABLE_KEY, PARAM_TABLE_PREFIX, 30), 'could not add param table') function bind_add_param(name, idx, default_value) assert(param:add_param(PARAM_TABLE_KEY, idx, name, default_value), string.format('could not add param %s', name)) return Parameter(PARAM_TABLE_PREFIX .. name) end

param:add_table(table_key, prefix, num_params)与param:add_param(table_key, param_num, name, default_value)是 ArduPilot 脚本参数表的底层绑定接口（见 libraries/AP_Scripting/docs/docs.lua）。表键（key）为 73，前缀为IDLE_，最大可注册 30 个参数，当前脚本使用了其中 7 个。

脚本注册的参数及其默认值如下表：

参数名	索引	默认值	含义
`IDLE_GAIN_I`	1	0.05	控制器积分增益
`IDLE_GAIN_P`	2	0.25	控制器比例增益
`IDLE_GAIN_MAX`	3	1	积分项的 IMAX 限幅
`IDLE_MAX`	4	17	最大油门位置（%）
`IDLE_RANGE`	5	300	怠速控制生效的 RPM 范围
`IDLE_SETPOINT`	6	600	期望的 RPM 设定值
`IDLE_RPM_ENABLE`	7	0	0=手动油门控制；1=使用 RPM1 目标；2=使用 RPM2 目标

参数注册源码见 Heli_idle_control.lua。

参数调参要点

IDLE_GAIN_P / IDLE_GAIN_I：经典 PI 参数。P 项对 RPM 偏差立即响应，I 项消除稳态误差。I 过大会引起振荡，I 过小则怠速 RPM 无法收敛到设定值。
IDLE_GAIN_MAX：积分限幅（IMAX），防止积分饱和导致超调。脚本中该值同时用于正负双向限幅（见PI_controller实现）。
IDLE_MAX：怠速允许的最大油门输出（百分比），含义是“地面怠速时油门的上限”。文档原文强调：必须设置得足够低，以免离合器接合/打滑，或低于油门曲线第一段（first point of throttle curve）。从代码看，IDLE_MAX与H_RSC_IDLE共同构成油门输出的上下边界。
IDLE_RANGE：决定 PI 闭环何时介入的 RPM 死区范围（见下文运行流程）。默认 300 RPM。
IDLE_SETPOINT：闭环目标转速，默认 600 RPM。
IDLE_RPM_ENABLE：控制模式选择。0时脚本退化为“手动油门怠速”，电位器直接映射油门；1/2时分别以 RPM 传感器实例 1 或实例 2（对应RPM1/RPM2的RPM_TYPE配置）作为反馈，进入自动转速闭环。

如何启用：RCx_OPTION=301 辅助电位器

文档给出的启用方式只有一条核心命令：

set RCx_OPTION to 301

其中x是实际使用的 RC 通道编号。301对应 ArduPilot RC 通道可选功能SCRIPTING_2（脚本输入 2），在 libraries/RC_Channel/RC_Channel.h 中定义为SCRIPTING_2 = 301。该通道通过rc:find_channel_for_option(301)被脚本捕获（Heli_idle_control.lua），用作辅助电位器输入（aux potentiometer），用于手动微调怠速。

接线与配置建议：

将一个模拟电位器接到接收机空闲通道，再把该通道在飞控上映射为任意 RC 通道（RCx）。
将RCx_OPTION设为301。通道输入范围归一化为-1（最低）到+1（最高），对应pot_input:norm_input()（脚本第 119 行），再经map(pot_pos, -1, 1, 0, 1)映射为 0~1 的手动油门系数（第 120 行）。
电位器在最低位（pot_pos = -1）时手动系数为 0，怠速油门 =H_RSC_IDLE；在最高位时系数为 1，怠速油门 =IDLE_MAX。

与 RSC 开关（RCx_OPTION=32）的配合

脚本还依赖一个“RSC 开关”通道（Heli_idle_control.lua）：rc:find_channel_for_option(32)，即MOTOR_INTERLOCK（电机/旋翼互锁开关，定义于 libraries/RC_Channel/RC_Channel.h）。该开关的辅助开关位置（get_aux_switch_pos()）用于判断是否处于“地面怠速”工况（与vehicle:get_likely_flying()联合判定，见第 129 行），只有开关处于位置 0 且飞行器未起飞时才执行怠速控制逻辑。

运行流程与状态机解析

脚本主循环以10Hz（每 100ms）的频率运行（return update, 100，第 209 行）。整体流程按状态分为三大部分，对应脚本update()函数（第 113-207 行）的三个分支。

分支一：未解锁（disarmed）

当arming:is_armed()返回 false 时，脚本将内部状态复位：

记录当前H_RSC_IDLE到idle_default；
关闭怠速控制（idle_control_active = false）；
复位爬升标志（ramp_up_complete = false、idle_adjusted = false）；
复位 PI 积分器（thr_PI.reset(0)）。

此时不干预 RSC 输出，旋翼转速控制完全交给飞控原生逻辑（H_RSC_IDLE保持默认值 0，定义见 libraries/AP_Motors/AP_MotorsHeli_RSC.cpp）。

分支二：解锁 + 地面怠速（RSC 开关位置 0 且未起飞）

这是脚本的核心工作区，再细分为手动与自动两种模式：

手动模式（IDLE_RPM_ENABLE == 0）

thr_out = H_RSC_IDLE:get() + thr_man*(IDLE_MAX:get() - H_RSC_IDLE:get())

油门在H_RSC_IDLE与IDLE_MAX之间随电位器线性变化，同时复位爬升与调整标志。

自动模式（IDLE_RPM_ENABLE == 1/2）

先读取 RPM 反馈：RPM:get_rpm((IDLE_RPM_ENABLE:get())-1)（第 148 行），即1对应 RPM 实例 0（RPM1），2对应 RPM 实例 1（RPM2）。RPM:get_rpm为脚本绑定接口（见 libraries/AP_Scripting/docs/docs.lua 与 libraries/AP_RPM/AP_RPM.h）。随后依据当前 RPM 与设定值的关系分三种情况：

RPM 远低于设定值（rpm_current < IDLE_SETPOINT - IDLE_RANGE）：处于爬升初期，PI 暂不接管，油门直接按电位器手动映射，并记录thr_out_last；
RPM 远高于设定值（rpm_current > IDLE_SETPOINT + IDLE_RANGE）：油门回落至H_RSC_IDLE，同样记录thr_out_last；
RPM 在设定值 ± IDLE_RANGE 范围内：进入 PI 闭环。将 RPM 归一化pv = rpm_current / IDLE_SETPOINT（目标为 1.0），调用thr_PI.update(1, pv)得到控制量，约束到 0~1 后映射为H_RSC_IDLE到IDLE_MAX之间的油门，并限制单步变化不超过 ±0.05（防止油门突变，第 166 行）。此时置idle_control_active = true，并向 GCS 发送idle control: ON（第 171 行）。

电位器归零（thr_man == 0）时自动模式强制退出闭环，油门回到H_RSC_IDLE，发送idle control: OFF，并复位 PI 积分器（第 139-146 行）。

无论手动还是自动，最终输出都通过SRV_Channels:set_output_pwm_chan_timeout直接写入 RSC 伺服通道 PWM（第 177-181 行），超时 150ms 后自动失效。输出通道来自SRV_Channels:find_channel(31)，即RSC功能输出（第 40 行），并根据SERVO{ch}_REVERSED处理正反舵（第 177-181 行）。

分支三：解锁但离开地面怠速（飞行/互锁解除）

当 RSC 开关不在位置 0 或检测到可能飞行（get_likely_flying()为 true）时：

关闭怠速控制并发送idle control: deactivated；
进入爬升（ramp-up）交接逻辑：若爬升尚未完成，则将当前怠速油门写入H_RSC_IDLE（H_RSC_IDLE:set(last_scaled_output*100)），保证从怠速到正常旋翼爬升的油门衔接平滑；当超过H_RSC_RUNUP_TIME（旋翼达到全速的时间，默认 10 秒，定义见 libraries/AP_Motors/AP_MotorsHeli_RSC.cpp）后，恢复H_RSC_IDLE默认值并标记ramp_up_complete = true（第 188-203 行）。

这一设计使得“怠速控制脚本”与飞控原生的 RSC 爬升逻辑（set_idle_output/set_runup_time，见 libraries/AP_Motors/AP_MotorsHeli_RSC.cpp）能够无缝衔接，起飞后旋翼转速交给原生控制器管理。

PI 控制器的源码级剖析

脚本实现了一个轻量 PI 控制器闭包（PI_controller，第 67-107 行），核心update(target, current)逻辑：

local err = target - current local P = _kP:get() * err if ((_total < _max and _total > _min) or (_total >= _max and err < 0) or (_total <= _min and err > 0)) then _I = _I + _kI:get() * err * dt end if _iMax:get() > 0 then _I = constrain(_I, -_iMax:get(), iMax:get()) end local ret = P + _I _total = ret return ret

值得注意的实现细节：

条件积分（anti-windup）：只有在前次输出未越界，或越界但误差方向能拉回边界时，才累加积分项，避免积分饱和；
积分限幅：IDLE_GAIN_MAX > 0时对积分项做 ±IMAX 约束；
周期计算：dt由millis()差值换算而来，保证 10Hz 调度下的时间一致性；
外部复位接口：reset(integrator)用于在怠速退出、电位器归零或未解锁时清空积分器。

该 PI 控制器实例化于第 109 行：thr_PI = PI_controller(IDLE_GAIN_P, IDLE_GAIN_I, IDLE_GAIN_MAX, 0, 1)，输出被约束在 0~1 之间，再映射为实际油门百分比。

参数	含义	脚本用途
`H_RSC_IDLE`	怠速油门输出（默认 0），libraries/AP_Motors/AP_MotorsHeli_RSC.cpp	作为怠速油门下限与爬升交接值
`H_RSC_RUNUP_TIME`	旋翼达到全速所需时间（默认 10s）	决定爬升交接窗口长度

安装、验证与常见问题

安装步骤

启用脚本：地面站中设置SCR_ENABLE = 1；
将 Heli_idle_control.lua 复制到 SD 卡的APM/scripts目录；
设置怠速电位器通道：RCx_OPTION = 301；
设置 RSC 开关通道：RCy_OPTION = 32（MOTOR_INTERLOCK）；
重启飞控使脚本加载，并按上文表格调校IDLE_*参数。

验证方式

启动后 GCS 消息流应出现idle_control_running；
切换怠速闭环时出现idle control: ON/idle control: OFF；
离开地面怠速工况时出现idle control: deactivated；
通过RPM1/RPM2遥测观察实际转速是否收敛到IDLE_SETPOINT。

常见问题排查

脚本未加载：检查SCR_ENABLE、SD 卡目录路径、固件是否支持脚本，以及是否出现idle_control_running消息；
自动模式无闭环：确认IDLE_RPM_ENABLE为 1/2、对应 RPM 传感器已配置且读数有效、电位器输入非零；
怠速转速超调/振荡：先降低IDLE_GAIN_I与IDLE_GAIN_P，再检查IDLE_GAIN_MAX限幅是否过松；
离合器打滑：降低IDLE_MAX，确保其低于离合器接合点或油门曲线第一段；
起飞后油门突变：检查H_RSC_RUNUP_TIME与爬升交接是否正常完成（观察H_RSC_IDLE updated for ramp up与H_RSC_IDLE default restored消息）。

小结

Heli_idle_control 用约 200 行 Lua 脚本，在飞控原生 RSC 逻辑之外提供了一套独立、可插拔的地面怠速 RPM 控制方案：通过IDLE_RPM_ENABLE在“电位器手动油门”与“RPM 传感器自动闭环”之间切换，以IDLE_RANGE定义 PI 介入死区，并借助H_RSC_IDLE/H_RSC_RUNUP_TIME实现与起飞爬升的无缝交接。理解其参数表、PI 实现与三态状态机，即可按需将其移植或调优到自己的传统直升机平台上。

企业官网建设流程全解析