ArduPilot 参数锁定Parameter LockdownLua 脚本实战指南基于 MAVLink 白名单的参数写入防护【免费下载链接】ardupilotArduPlane, ArduCopter, ArduRover, ArduSub source项目地址: https://gitcode.com/GitHub_Trending/ar/ardupilot导读ArduPilot 是支持固定翼、多旋翼、地面车与水下潜航器等载具的开源自动驾驶仪项目其固件参数Parameters承载了飞控的全部调参与配置逻辑任何错误的参数写入都可能导致严重后果。param-lockdown.lua是 ArduPilot 官方脚本应用applet中一个面向安全场景的 Lua 脚本它拦截所有来自地面站GCS的 MAVLinkPARAM_SET消息仅允许写入一份预定义的白名单参数其余参数一律拒绝。阅读本文后你将掌握该脚本的启用流程、白名单机制、底层实现原理包括gcs:set_allow_param_set()接口的调用关系并能在自动化测试、共享数传环境等参数完整性敏感的场景中正确部署与排障。背景为什么需要参数锁定在常规状态下任何能够通过 MAVLink 连接飞控的地面站都可以自由调用PARAM_SET修改飞控参数ArduPilot 的 GCS 库会直接处理这些写入请求。但在以下场景中参数完整性变得至关重要自动化测试测试脚本或外部工具批量下发参数时一旦误写调参类参数如 PID、增益会破坏测试基准载荷托管型地面站payload-hosted GCS第三方地面站软件与飞控共用一个数传链路需要限制其写入权限共享数传环境多个操作者共用同一数传链路时需要防止无意中改动关键安全参数。param-lockdown.lua正是为这些场景设计的安全过滤层——它不禁止读取参数只约束写入且放行哪些参数完全由脚本内的白名单决定。依据本脚本随 ArduPilot 官方脚本应用目录发布源码位于 param-lockdown.lua说明文档位于 param-lockdown.md。工作原理拦截、校验、放行/拒绝脚本的核心工作流可以概括为三个步骤对应脚本内update()函数拦截通过 Lua 绑定注册 MAVLink 消息接收捕获目标为飞控的PARAM_SET消息消息 ID 为 23校验解析出参数名param_id与脚本内硬编码的白名单parameters_which_can_be_set比对执行命中白名单 → 调用param:set_and_save()写入并保存向 GCS 发送param set applied提示未命中 → 拒绝写入向 GCS 发送param set denied (参数名)提示并向发送方回传 MAVLinkPARAM_ERROR消息错误码PERMISSION_DENIED。关键的一点是脚本启用后ArduPilot 会关闭 GCS 库默认的参数写入通道改由脚本独占接管参数写入职责。这一机制在脚本源码中有明确注释-- When this script runs and ENABLE is true ArduPilot will stop -- processing parameter-sets via the GCS library. Instead, this -- script becomes responsible for setting parameters, and it will -- only set parameters which are whitelisted.这种接管设计保证了没有旁路即使脚本自身存在竞态或消息积压GCS 库默认通道已关闭参数只能经由脚本白名单过滤后写入。底层接口gcs:set_allow_param_set()脚本动态切换 ArduPilot 的 GCS 参数写入许可依赖两个底层接口gcs:set_allow_param_set(bool)强制 GCS 库忽略PARAM_SET及 MAVLink FTPmavftp文件上传中的参数写入gcs:get_allow_param_set()读取当前许可状态。这两个接口在 GCS.h 中有清晰定义注释明确指出其作用是控制通过 PARAM_SET 或 mavftp 文件上传设置参数是否被 GCS 库采纳。同时bindings.desc 中的singleton GCS method set_allow_param_set void boolean声明表明该接口已对 Lua 脚本层开放这构成了脚本能接管 GCS 参数写入的底层能力基础该接口依赖 ArduPilot 4.7 及以上版本支持。在 GCS 库侧PARAM_SET消息的常规处理入口位于 GCS_Param.cpp 的handle_common_param_message()当allow_param_set为 false 时此默认处理路径不再生效从而将写入权完全让渡给脚本。启用前置条件脚本的运行依赖 ArduPilot 的 Lua 脚本框架需要满足以下条件条件说明固件版本ArduPilot 4.7 或更高版本且编译时包含 Lua 脚本支持SCR_ENABLE必须设置为1启用脚本执行引擎脚本目录将param-lockdown.lua复制到飞控 SD 卡的scripts目录参数表支持固件需支持 Lua 脚本自定义参数表param:add_table提示当前仓库中该脚本位于 libraries/AP_Scripting/applets/param-lockdown.lua部署时可将此文件复制到飞控 SD 卡scripts/目录下。仓库还提供了大量其他脚本应用见 libraries/AP_Scripting/applets可作为参考。脚本自带的参数表PARAM_LOCK_脚本通过param:add_table(92, PARAM_LOCK_, 7)注册了一张名为PARAM_LOCK_的自定义参数表表中预留 7 个槽位当前仅使用第 1 个。表中参数如下名称类型默认值说明PARAM_LOCK_ENAB整数int1值为1启用参数锁定0禁用将PARAM_LOCK_ENAB置0即可临时关闭锁定功能脚本会恢复 GCS 库默认的参数写入许可即重新允许正常PARAM_SET。重要警告原文档与脚本源码均明确指出——当脚本处于启用状态正在拦截参数写入时不建议通过关闭SCR_ENABLE来停用脚本。因为SCR_ENABLE0会让 Lua 引擎整体停止而脚本已经关闭了 GCS 默认参数通道届时参数写入将处于无人接管的状态。正确做法是先设PARAM_LOCK_ENAB0让脚本自行恢复 GCS 许可再考虑关闭脚本引擎。脚本自定义参数表实现细节可参考源码中的绑定与注册逻辑local PARAM_TABLE_KEY 92 local PARAM_TABLE_PREFIX PARAM_LOCK_ assert(param:add_table(PARAM_TABLE_KEY, PARAM_TABLE_PREFIX, 7), could not add param table)白名单参数完整清单白名单在脚本中以 Lua 表形式硬编码见 param-lockdown.lua。以下为完整清单按功能分组整理MAVLink / 板级选项参数说明MAV_OPTIONSMAVLink 协议行为选项BRD_OPTIONS板级Bootloader/硬件选项PARAM_LOCK_ENAB本脚本的开关保证启用后可自行解锁电池监测BATT参数说明BATT_ARM_MAH解锁所需最低剩余电量mAhBATT_ARM_VOLT解锁所需最低电压VBATT_CAPACITY电池额定容量mAhBATT_CRT_MAH临界剩余电量mAhBATT_CRT_VOLT临界电压VBATT_FS_CRT_ACT电池临界失效保护动作BATT_FS_LOW_ACT电池低压失效保护动作BATT_LOW_MAH低电量告警阈值mAhBATT_LOW_VOLT低电压告警阈值V罗盘与围栏COMPASS / FENCE参数说明COMPASS_USE3是否使用第三个罗盘FENCE_ACTION触发围栏后的动作FENCE_ALT_MAX围栏最大高度mFENCE_ENABLE围栏总开关FENCE_RADIUS围栏半径mFENCE_TYPE围栏类型返航RTL参数说明RTL_ALT_MRTL 返航高度mRTL_LOIT_TIMERTL 返航后悬停时间sRTL_SPEED_MSRTL 返航速度m/s日志与指示灯LOG / LIGHTS参数说明LOG_BITMASK日志记录掩码LOG_DISARMED是否在未解锁时记录日志LOG_FILE_DSRMROT未解锁时日志文件轮转策略LIGHTS_ON灯光控制观察可见白名单的取舍逻辑非常务实允许运维类日志、围栏、电池保护阈值、返航参数与安全监视类参数在飞行中被调整而禁止控制回路类参数如 PID、姿态、电机混控等被地面站随意改写。如果你需要调整白名单必须直接编辑脚本源码中的parameters_which_can_be_set表。使用步骤部署与启用按以下步骤完成部署复制脚本将 param-lockdown.lua 复制到飞控 SD 卡的scripts目录不同载具的 SD 卡路径可能略有差异通常为APM/scripts或scripts启用脚本引擎将SCR_ENABLE设为1启用锁定确认PARAM_LOCK_ENAB为1默认值即为1重启飞控重启自动驾驶仪或重新加载脚本使脚本生效。脚本加载成功后地面站会收到一条欢迎信息[param-lockdown] param set applied说明脚本以约 100 HzUPDATE_INTERVAL_MS 10的频率轮询 MAVLink 接收队列并采用protected_wrapper()pcall的容错包装即使update()内部出现异常脚本也不会停止而是降频至每秒重试一次并发送Internal Error紧急消息避免错误刷屏。这一设计保证了锁定逻辑的高可用性。日志与调试读懂 GCS 提示脚本通过gcs:send_text()向地面站发送诊断消息是判断参数写入是否被拦截的直接依据场景GCS 提示含义参数命中白名单[param-lockdown] param set applied参数已写入并保存参数未命中白名单[param-lockdown] param set denied (LOG_BACKEND_TYPE)该参数被拒绝括号内为被拒参数名脚本加载成功[param-lockdown] script loaded脚本进入运行态脚本内部异常Internal Error: errupdate()执行出错脚本容错重试原文档给出的示例输出[param-lockdown] param set applied [param-lockdown] param set denied (LOG_BACKEND_TYPE)其中LOG_BACKEND_TYPE是典型被拒案例——它不属于白名单白名单仅含LOG_BITMASK、LOG_DISARMED、LOG_FILE_DSRMROT三个日志参数。除了文本提示脚本还会向发起写入的一方GCS回传 MAVLinkPARAM_ERROR消息消息 ID 345当参数被拒绝时携带PERMISSION_DENIED错误码脚本内MAV_PARAM_ERROR枚举值 3以及目标系统/组件 ID 和被拒参数名使地面站能够从协议层感知写入失败的原因。完整错误码枚举为local MAV_PARAM_ERROR { NO_ERROR 0, DOES_NOT_EXIST 1, VALUE_OUT_OF_RANGE 2, PERMISSION_DENIED 3, COMPONENT_NOT_FOUND 4, READ_ONLY 5 }已知限制使用本脚本前需要明确以下限制源自原文档并与源码实现一致仅覆盖PARAM_SET脚本只拦截参数设置消息不处理PARAM_REQUEST_*参数读取/请求类消息参数读取不受影响白名单硬编码白名单写死在脚本源码中调整放行参数必须修改脚本并重新部署无法通过参数表在运行时配置固件接口依赖ArduPilot 必须提供gcs:set_allow_param_set()接口支持对应 ArduPilot 4.7禁止 mavftp 参数上传脚本运行期间通过 MAVLink FTP 上传参数文件的方式同样被禁止GCS 库的allow_param_set开关同时管辖PARAM_SET与 mavftp 上传两条路径见 GCS.h 注释禁用顺序要求SCR_ENABLE与PARAM_LOCK_ENAB的关闭顺序有讲究务必先置PARAM_LOCK_ENAB0再考虑关闭脚本引擎。总结param-lockdown.lua通过注册PARAM_SET接收 白名单校验 接管 GCS 参数通道三层设计为 ArduPilot 提供了一个轻量而可靠的参数写入防护方案。它特别适合自动化测试、载荷托管地面站、共享数传等对参数完整性敏感的部署环境。理解其白名单机制、PARAM_LOCK_参数表与gcs:set_allow_param_set()底层接口的配合关系将帮助你在实际项目中安全、正确地运用这一防护能力。【免费下载链接】ardupilotArduPlane, ArduCopter, ArduRover, ArduSub source项目地址: https://gitcode.com/GitHub_Trending/ar/ardupilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考