ArduPilot Lua 脚本之 Param_Controller用辅助开关在三套参数组间一键切换【免费下载链接】ardupilotArduPlane, ArduCopter, ArduRover, ArduSub source项目地址: https://gitcode.com/GitHub_Trending/ar/ardupilot导读Param_Controller 是 ArduPilot 官方 Lua applet 中的一个实用脚本位于 libraries/AP_Scripting/applets/Param_Controller.lua它允许用户在主脚本目录下的三个子目录scripts/1、scripts/2、scripts/3中各放置一份params.param参数文件然后通过遥控器上一个配置为辅助功能 302Scripting3的开关或通过 Mission Planner 的 AUX Function 面板在飞行现场一键切换整套参数配置。读完本文你将掌握该脚本的安装步骤、目录与参数文件的组织方式、开关通道的配置方法以及其基于 Lua 脚本引擎的分块读取与批量加载的底层实现原理。一、Param_Controller 解决什么问题多旋翼、固定翼等飞行器在切换任务场景时往往需要不同的参数组合例如一套用于普通航拍一套用于竞速一套用于载重。传统做法是每次用地面站逐项修改参数既繁琐又容易出错。Param_Controller 的设计目标正是解决这一痛点按开关位置从三个预置子目录中加载对应参数集实现场外备好、现场一键切换。它的核心特点包括与 Script_Controller.lua 使用同一个辅助功能 302与同一套子目录规范scripts/1、scripts/2、scripts/3两个脚本可以同时使用、互不冲突不需要地面站常驻切换完全由机载脚本自动完成切换动作包括检查子目录是否存在、读取参数文件、逐批写入参数并在地面站GCS上输出状态消息方便飞行前确认。需要注意的是脚本加载的参数修改不会自动跨重启保存需要保存时仍需手动操作详见第五节。二、工作原理辅助功能 302 与三个脚本子目录2.1 辅助功能 302Scripting3ArduPilot 为 Lua 脚本保留了 300~315 的辅助功能号定义在 libraries/RC_Channel/RC_Channel.h 中SCRIPTING_1 300, SCRIPTING_2 301, SCRIPTING_3 302, // Param_Controller 使用该值 ... SCRIPTING_16 315,同时在 libraries/RC_Channel/RC_Channel.cpp 的参数元数据中302 被标注为Scripting3可直接作为RCx_OPTION如RC1_OPTION、RC2_OPTION等的取值。2.2 开关位置到子目录的映射脚本通过rc:get_aux_cached(SEL_CH)读取 302 号辅助功能的缓存档位档位与子目录的对应关系如下开关档位辅助功能返回值物理含义加载的子目录0LOWscripts/11MIDDLEscripts/22HIGHscripts/32.3 目录与文件结构脚本需要在脚本目录下存在三个子目录每个子目录内放置一份参数文件scripts/ ChibiOS 板为 APM/scriptsSITL 下为 scripts/ ├── 1/ │ └── params.param ← 开关 LOW 档加载 ├── 2/ │ └── params.param ← 开关 MIDDLE 档加载 └── 3/ └── params.param ← 开关 HIGH 档加载 └── Param_Controller.lua ← 脚本本体脚本源码 Param_Controller.lua 中硬编码了两个关键常量local SEL_CH 302 -- 使用的辅助功能号 local PARAM_FILENAME params.param -- 参数文件名脚本目录的判定逻辑get_scripts_dir()会优先探测APM/scripts存在则使用之否则回退到scripts/从而同时兼容 SD 卡ChibiOS与 SITL 仿真环境function get_scripts_dir() local dlist1 dirlist(APM/scripts) if dlist1 and #dlist1 0 then return APM/scripts end return scripts end2.4 未建立 RC 连接时的默认行为文档约定若在地面启动ground start期间尚未建立 RC 连接则行为等同于选中了子目录 1。从源码看当rc:get_aux_cached(SEL_CH)返回nilRC 未就绪时update()循环会直接跳过切换动作等待下一轮检测见 Param_Controller.lualocal sw_current rc:get_aux_cached(SEL_CH) if (sw_current sw_last) or (sw_current nil) then return update, 500 end这意味着在 RC 尚未建立时不会误加载任何子目录一旦开关位置发生变化并检测到有效档位才会触发参数加载。三、安装与启用3.1 前置条件固件需包含 Lua 脚本支持applet 为官方随固件发布的完整脚本无需用户修改即可使用参见 libraries/AP_Scripting/applets/README.md必须启用脚本功能设置SCR_ENABLE 1并重启飞控参见 libraries/AP_Scripting/README.md。3.2 安装步骤将 Param_Controller.lua 复制到 SD 卡的APM/scripts目录SITL 仿真下对应scripts/目录在APM/scripts下创建1、2、3三个子目录在每个子目录中放置名为params.param的参数文件设置SCR_ENABLE 1重启飞控。3.3 配置辅助开关将一个遥控器通道的RCx_OPTION参数如RC7_OPTION设置为302该通道即承担参数组切换职责开关置于 LOW → 加载scripts/1/params.param开关置于 MIDDLE → 加载scripts/2/params.param开关置于 HIGH → 加载scripts/3/params.param。切换开关位置的动作可以发生在地面启动之前也可以发生在启动之后每次档位变化都会重新加载目标子目录中的参数文件。如果不方便使用遥控器开关Mission Planner 的AUX Function 选项卡也提供了触发 302 号功能的入口可直接以等效方式执行切换无需额外占用发射机通道。四、参数文件格式与解析规则params.param是纯文本参数文件脚本使用统一的正则解析逗号分隔与空格分隔两种格式见 Param_Controller.lua-- trim trailing spaces line string.gsub(line, ^(.-)%s*$, %1) -- skip empty lines and comments if line ~ and not string.match(line, ^%s*#) then -- Parse parameter using unified pattern for both comma and space delimited formats local _, _, parm, value string.find(line, ^([%w_])[, ] *([%d.-])) ... if param:set(parm, num_value) then count count 1 ...文件格式规则可以总结为每行一个参数格式为参数名[,空格]数值例如RC1_MIN 1000或RC1_MIN,1000支持负数与小数匹配模式[%d.-]覆盖数字、小数点与负号空行与以#开头的注释行会被跳过行尾多余空格会被自动裁剪。典型示例scripts/2/params.param# 竞速模式参数组 PSC_VELXY_P 2.5 PSC_VELXY_I 1.0 RC1_MIN 1000 RC1_MAX 2000需要注意文档Param_Controller.md正文中曾将文件名写作 params.parm而脚本源码实际使用的是params.param以源码为准文件必须命名为params.param。五、源码级实现剖析分块读取与批量加载5.1 为什么需要分块处理飞控上的 Lua 脚本运行在调度器scheduler的任务槽中单次update()调用不能占用过长时间否则会触发看门狗超时。参数文件可能包含上百行甚至更多条目因此脚本把读文件和写参数都拆成了多个批次每轮update()只处理一小块。5.2 读取阶段每次 200 行read_file_chunk()每轮从文件中读取最多 200 行存入内存缓冲local chunk_size 200 for _ 1, chunk_size do local line file_handle:read() if not line then -- 文件读完 file_handle:close() ... param_loading true -- 转入加载阶段 return false end table.insert(param_lines, line) end5.3 写入阶段每次 200 个参数param_load_batch()每轮调用param:set()处理最多 200 个参数。param:set是脚本引擎提供的参数写入接口依据 libraries/AP_Scripting/docs/docs.lua 的说明set parameter value, this will not be retained over a reboot即该接口只修改内存中的参数值不写入持久化存储——这正是本文档所述参数修改不跨重启保存的机制根源。如果需要持久化需改用param:set_and_save()。local batch_size 200 for _ 1, batch_size do if param_index #param_lines then param_loading false if not failed then gcs:send_text(6, string.format(Config %d loaded, param_subdir)) else gcs:send_text(6, string.format(Config %d loaded (some failed), param_subdir)) end return false end ... if param:set(parm, num_value) then count count 1 else failed true end end5.4 主循环的调度节奏update()根据当前所处阶段返回不同的延时让调度器合理分配时间片见 Param_Controller.lua阶段返回延时正在读取文件100 ms正在写入参数200 ms空闲等待开关变化500 ms六、运行反馈与异常处理脚本通过gcs:send_text()向地面站发送不同级别的状态消息便于飞行前确认切换结果消息内容严重级别触发场景Loaded Parameter_Controller.lua5脚本启动时Loading config %d6开始加载某子目录Config %d loaded6加载成功全部参数写入成功Config %d loaded (some failed)6加载完成但存在失败条目.../params.param not present0目标子目录缺少参数文件Scripts subdirectory /%s does not exist!0目标子目录不存在异常防护逻辑Param_Controller.luaif not check_subdir_exists(subdir) then gcs:send_text(0, string.format(Scripts subdirectory /%s does not exist!, subdir)) return update, 500 endcheck_subdir_exists()借助脚本引擎的dirlist()绑定参见 docs.lua检测子目录是否存在若不存在则不会尝试加载仅发出告警消息后继续等待下一次开关变化。七、与 Script_Controller 协同使用Param_Controller 与 Script_Controller 是一对互补的脚本选择器Script_ControllerScript_Controller.lua按开关位置将scripts/1|2|3中的.lua脚本复制到主脚本目录并重启脚本引擎实现脚本组切换其辅助功能号默认也是 302可用参数SCR_USER6覆盖范围 300~307Param_Controller按同一开关、同一套子目录规范加载params.param实现参数组切换。由于两者共用 302 号辅助功能与相同的子目录映射可以同时在脚本目录中共存切换开关时脚本组与参数组同步切换非常适合不同任务使用不同脚本 不同参数的组合场景。使用时只需把两个.lua文件都放入主脚本目录即可。八、使用限制与注意事项不自动持久化脚本使用param:set()而非param:set_and_save()因此加载的参数仅在本次运行中生效重启后失效需要永久生效必须手动保存参数文件命名严格参数文件名必须为params.param以源码为准子目录名必须为1、2、3目录必须存在若目标子目录不存在脚本不会加载任何参数只发送告警消息RC 未建立时的行为RC 未就绪时脚本不会误触发加载默认按子目录 1 的语义处理直到检测到有效开关档位配合 Script_Controller 的注意事项若同时使用 Script_Controller 切换脚本目录注意它会在切换时清空主脚本目录中不属于当前子目录的.lua文件因此 Param_Controller.lua 需视使用方式保留在合适位置详见 Script_Controller.md。九、小结Param_Controller 以极简的辅助功能 302 三个子目录 一份params.param设计为 ArduPilot 用户提供了一套可在飞行现场快速切换参数组的完整方案。其实现虽然只有 170 余行 Lua 代码却涵盖了文件系统探测、分块读取、批量参数写入、异常反馈与调度器时序管理等多个工程细节是与 Script_Controller 配合构建任务化配置切换工作流的重要基础组件。【免费下载链接】ardupilotArduPlane, ArduCopter, ArduRover, ArduSub source项目地址: https://gitcode.com/GitHub_Trending/ar/ardupilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考