ArduPilot Lua脚本完整指南调度原理、关键参数与最小可运行示例【免费下载链接】ardupilotArduPlane, ArduCopter, ArduRover, ArduSub source项目地址: https://gitcode.com/GitHub_Trending/ar/ardupilot需要飞控周期性上报某项数据或在地面站指令到达时执行一段自定义动作——最笨的办法是改C代码、重刷固件。ArduPilot内置的Lua脚本子系统提供了另一条路开机时自动从磁盘加载.lua文件在独立线程里沙箱执行不碰固件源码就能读写飞控内部状态、输出参数与舵机信号。读完本文你可以在实飞硬件或SITL上打开脚本子系统写出一个自调度的脚本并验证其生效还能让脚本接收地面站下发的单次任务指令。 看懂Lua脚本的能力版图与调度机制先划清边界这个子系统能做什么、不能做什么一张表说清能力项解决什么问题典型场景自调度循环return fn, ms不占用主控循环脚本自己决定下次何时运行周期遥测、低频业务逻辑对象绑定vehicle、ahrs、battery等直接读取姿态、位置、模式等内部状态无需解析MAVLink条件判断、数据记录DO_SCRIPTING任务指令地面站或任务途中随时向脚本侧投递一次命令途中切换逻辑、触发自定义动作串口设备绑定SCR_SDEV系列脚本读写外部硬件接自制传感器、外挂设备SCR_USER1–6 用户参数不改代码就能给脚本传配置阈值、实例号、开关LD/RUN_CHECKSUM 校验防止SD卡里的脚本被误换定型后的部署环境图1脚本子系统默认只在flash超过1MB的平台上编译开启H7级主控是典型目标工作原理按输入→处理→输出三段看就够。输入有三路脚本目录下的.lua文件实飞硬件为SD卡的/APM/scripts/SITL为工作目录下./scripts/、MAVLink的DO_SCRIPTING任务指令、以及SCR_开头的参数写入。处理核心是一个名为Scripting的独立线程见 libraries/AP_Scripting/AP_Scripting.cpp它内置Lua 5.3.6沙箱源码在 libraries/AP_Scripting/lua/把所有脚本挂成一条按下次运行时间排序的链表逐个唤醒执行每次调用都受VM指令计数钩子约束单轮执行超过预算就被判为超时并中止错误以ERROR级别推给地面站。结构细节在 lua_scripts.h 的script_info链表里不必深读。输出则是GCS文本消息、DataFlash日志、PWM/参数/模式写入等副作用。任务指令这一路在 libraries/AP_Mission/AP_Mission_Commands.cpp 的start_command_do_scripting中入队脚本侧从队列中取出。能力边界清楚了下面按三步把文件变成运行中的脚本。️ 做出来从参数配置到脚本运行的三步图2先确认你的硬件在编译时已自动带上脚本支持flash1MB即开启第一步打开开关并确认脚本目录把SCR_ENABLE设为1后重启固件启动时会扫描脚本目录硬件上自动创建/APM/scripts/。关键参数与调整建议如下表定义集中在 libraries/AP_Scripting/AP_Scripting.cpp 的参数组里参数默认值说明与调整建议SCR_HEAP_SIZE43KB小内存档/100KB/200KB脚本堆大小1KB步进、上限1MB改后需重启频繁分配才调大SCR_VM_I_COUNT10000单轮执行的VM指令预算范围1000–1000000脚本被判超时先查这里SCR_ENABLE00关闭1启用Lua脚本重启生效SCR_DEBUG_OPTS0位掩码bit0全部脚本停止时提示bit1输出每轮内存与耗时bit3记录运行统计SCR_USER1–60.0通用配置项脚本内直接读取适合传阈值SCR_LD_CHECKSUM / RUN_CHECKSUM-1关闭已加载/运行中脚本CRC32的XOR值不符拒绝解锁SCR_THD_PRIORITY0Normal0–8级源码注释明确警告调高可能影响飞控稳定性SCR_DIR_DISABLE0bit0禁ROMFS、bit1禁APM/scripts目录第二步写一个自调度脚本脚本的骨架就一个约定顶层返回(函数, 毫秒数)请求首次运行函数每次执行完再返回一次就是自我重新排程。最小可跑的示例如下把它存为scripts/home-dist-pwm.lua-- scripts/home-dist-pwm.lua把到home的距离映射到舵机输出 function update() local pos ahrs:get_location() -- 当前位置 local home ahrs:get_home() -- home点 if pos and home then local d math.min(pos:get_distance(home), 1000) -- 截断到1000米 SRV_Channels:set_output_pwm(96, 1000 d) -- 功能96即scripting3 end return update, 1000 -- 1秒后再跑一轮 end return update, 1000 -- 加载后1秒首次运行第三步编译、运行并验证成功实飞硬件与SITL的入口不同但验证手段一致# 编译并刷入CubeBlack的ArduPlaneflash1MB自动启用脚本子系统 waf configure --boardCubeBlack waf plane waf plane --upload # 或者不碰硬件直接用SITL验证 Tools/autotest/sim_vehicle.py -v ArduPlane验证成功的标志有三个地面站控制台出现Scripting:开头的加载提示打开SCR_DEBUG_OPTS的bit1后可看到每个脚本每轮的内存占用与耗时用Mission Planner的脚本控制台或DataFlash日志确认输出值在变化。目录布局与更多可参考写法见 libraries/AP_Scripting/README.md 和 libraries/AP_Scripting/examples/。跑通第一个脚本只是起点价值在于把它用在具体任务里。 用好三个实战场景与避坑清单图3脚本能读写的对象最终都落到这些引脚与通道的实际输出上实战场景场景1周期性数据提醒。需求电池电压跌破阈值时地面站要有提示。思路这就是最标准的自调度循环每秒读一次电压、低于SCR_USER1传入的阈值就发一条GCS文本阈值不用改代码。核心就两行local v battery:voltage(0)读取主电池gcs:send_text(0, string.format(batt low %.1fV, v))发提示然后照例return update, 1000。预期效果地面站控制台每秒一条日志掉电前你至少能收到几次明确警告。场景2地面站触发单次逻辑。需求飞行途中由地面站决定让脚本执行哪一段逻辑。思路MAVLink的DO_SCRIPTING指令中param1是控制命令停止/停止并重启param2携带要执行的任务指令编号其余参数作为参数下发AP_Scripting.cpp 的handle_mission_command把指令压入队列脚本侧轮询取出。function update() local cmd mission:next() -- 从指令队列取一条没有则返回nil if cmd then print(cmd:, cmd.command, cmd.param1, cmd.param2) -- 指令号与参数 end return update, 100 -- 100ms轮询一次 end return update()预期效果地面站下发指令后100ms内脚本打印出指令号与参数据此分支到不同逻辑段。场景3途中切换飞行模式。需求脚本检测到某条件后把飞行器切到指定模式。思路用vehicle:set_mode(模式号)直接切切前先用vehicle:mode_number()确认当前模式避免重复切换。预期效果条件成立时地面站模式指示立即变化且可在SITL中反复验证切换序列。更完整的现成方案可直接看 libraries/AP_Scripting/applets/每个applet都配有同名.md说明。避坑清单性能类现象GCS报错提示脚本超出执行时段后被中止。对策先调大SCR_VM_I_COUNT再把单轮计算拆小字符串拼接是常见隐形开销。现象分配内存失败、脚本起不来。对策按1KB步进调SCR_HEAP_SIZE需重启循环中适时collectgarbage()释放。现象脚本一重其他子系统就受影响。对策SCR_THD_PRIORITY保持默认0除非确认真时需求并审计过全部脚本。安全类现象升级或换SD卡后加载了错误脚本。对策把当前脚本集的XOR校验值写入SCR_LD_CHECKSUM/SCR_RUN_CHECKSUM不符即拒绝解锁。现象历史残留目录干扰加载。对策用SCR_DIR_DISABLE按位禁用ROMFS或APM/scripts。调试类现象报错信息看不出原因。对策打开SCR_DEBUG_OPTSbit1看每轮内存与耗时bit3记入DataFlash再配合自己的gcs:send_text输出。现象不确定脚本是否还活着。对策bit0会在所有脚本停止时主动提示比默默消失好排查得多。 资源脚本的价值不在能跑而在它离业务逻辑最近改一行.lua比重刷固件快得多前提是你在SITL里把异常路径也跑过一遍。子系统总览与构建说明libraries/AP_Scripting/README.md官方示例脚本160余个libraries/AP_Scripting/examples/开箱即用的applet含说明文档libraries/AP_Scripting/applets/可复用的驱动封装MAVLink、CAN、CRSF等libraries/AP_Scripting/drivers/任务指令入口libraries/AP_Mission/AP_Mission_Commands.cpp【免费下载链接】ardupilotArduPlane, ArduCopter, ArduRover, ArduSub source项目地址: https://gitcode.com/GitHub_Trending/ar/ardupilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考