企业官网建设流程全解析

如何3步跑通 ArduPilot 脚本引擎：从零到第一个 Lua 脚本的最短路径

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

起飞前你需要多旋翼在电压低于 10.8V 时自动上报地面站，而不是改固件、重新编译、再烧录一遍。把 10 行 Lua 脚本丢进 ArduPilot 飞控，让它自己读电压、发报文——这正是内置脚本系统最直接的用法。下面按"先跑起来，再谈机制"的顺序带你过完一遍。

不用它，你会撞上什么墙 🧱

两个真实卡点：一是某个传感器越限要触发特定动作，固件里没有现成开关，为一条阈值改核心代码、重新编译验证，成本高到不划算；二是你想接一个自定义串口协议的配件，驱动迟迟没有合并进主线，工作流直接停在这里。这两种情况，都是脚本层的活，不该落到改 C++ 上。

脚本怎么上机的：调度链路与关键参数 ⚙️

机制就是一条循环链：输入是脚本目录里的.lua文件；核心处理是启动时扫描目录（见 libraries/AP_Scripting/lua_scripts.cpp 的load_all_scripts_in_dir），每个脚本顶层return 函数, 延迟把回调登记进队列，之后飞控调度线程周期性执行队列中的回调（入口是 libraries/AP_Scripting/AP_Scripting.cpp 的update()），并用 Lua hook 限制单次执行的 VM 指令数；输出是回调返回值(fn, delay)，执行完再按新延迟排回队列。是否编进固件由 libraries/AP_Scripting/AP_Scripting_config.h 里的AP_SCRIPTING_ENABLED决定：flash 超过 1024KB 的板子自动启用。

跑脚本前，这几个参数值得先认脸（6 个就够）：

最短配置路径：从 clone 到第一条 gcs:send_text 🚀

全部步骤如下，注释就是"为什么"：

git clone https://gitcode.com/GitHub_Trending/ar/ardupilot cd ardupilot Tools/environment_install/install-prereqs-ubuntu.sh -y # 一次性装齐 waf/Lua 等构建依赖 waf configure --board=sitl # 用 SITL 仿真目标，没硬件也能验证全流程 waf plane Tools/autotest/sim_vehicle.py -v ArduPlane # 拉起 ArduPlane 仿真

真机路线只差两处：waf configure --board=CubeBlack后waf plane --upload，且 flash ≥1MB 的板子（CubeBlack、Pixhawk 4 这类 H7/F7）才会带脚本引擎。然后做三件事：参数里设SCR_ENABLE=1并重启；把.lua放进脚本目录——SITL 在工作目录的scripts/，真机在 SD 卡的APM/scripts/；重启后脚本自动加载，无需其他注册。

首次验证用这个最小脚本，能收到 hello 就说明引擎、文件目录、GCS 通路三件事全通了：

-- first_run.lua：跑通判定标准 function hello() gcs:send_text(0, "Scripting is alive") -- 0 表示紧急级，地面站直接弹出 return hello, 2000 -- 每 2 秒喊一次，确认调度循环活着 end return hello

三个拿来就改的脚本：低电压报警、低空锁死、跳点 🛠️

场景一：低电压实时报警（对应官方frsky_battery.lua的思路）。电压跌破阈值时向地面站发一条紧急消息，每秒检查一次：

-- battery_low_alert.lua local min_volt = 10.8 function check() local batt = Battery() if batt then local v = batt[0]:voltage() -- 电组总压 if v > 0 and v < min_volt then gcs:send_text(0, "Battery low: " .. string.format("%.1f", v) .. "V") end end return check, 1000 -- 每秒复查 end return check

预期效果：接上 4S 电池，电压一过线，地面站立刻弹出报警文本，频率不刷屏（可再加状态位去重）。

场景二：VTOL 低空锁死固定翼模式（QuadPlane_Low_Alt_FW_mode_prevention.lua的精简版）。低空误切 FW 会直接摔机，这里每 500ms 巡逻一次：

-- low_alt_fw_guard.lua local min_alt = 10 -- 10 米以下禁止固定翼模式 function guard() if vehicle:is_quadplane() and vehicle:in_flight() and vehicle:get_altitude() < min_alt and vehicle:mode() == "FBWA" then vehicle:set_mode("QLOITER") -- 立即拉回多旋翼悬停 gcs:send_text(0, "Too low for FW mode") end return guard, 500 end return guard

预期效果：四旋翼在 10 米以下被误切到 FBWA 时，半秒内被打回 QLOITER 并有地面提示。

场景三：Auto 模式条件跳点（advance-wp.lua的思路）。当当前位置离当前航点太远（比如被强侧风推偏），请求跳去下一个，避免绕圈追不上：

-- advance_wp.lua function advance() if vehicle:in_mode("AUTO") then local wp = vehicle:waypoint() if wp and wp.distance() > 200 then -- 离当前航点超 200 米 vehicle:advance_waypoint() -- 请求推进到下一航点 end end return advance, 1000 end return advance

预期效果：偏航超标后任务自动推进，航线整体节拍不崩，地面站日志能看到跳点记录。

这些坑，帮你踩过了 📌

症状：SCR_ENABLE=1已保存，控制台提示 "No Scripts to run"。根因：该参数带@RebootRequired: True，不落盘重启不生效。解法：改完参数执行一次重启，再进参数页刷新。

症状：脚本文件确认在 SD 卡里，就是不加载。根因：只扫描APM/scripts/目录、只认.lua结尾、以.开头的隐藏文件直接跳过；SCR_DIR_DISABLE位 1 还会整体禁掉该目录。解法：小写命名、直接放APM/scripts/根目录，并确认SCR_DIR_DISABLE=0。

症状：脚本报Out of memory或堆分配失败。根因：F4 级板子默认堆只有 43KB，SITL/H7 才是 200KB。解法：把SCR_HEAP_SIZE调到 200000 并重启，同时精简脚本里的长生命周期变量。

症状：回调被掐断，日志出现 overtime 提示。根因：SCR_VM_I_COUNT默认 10000，单次执行累计 VM 指令超限就判"耗时过长"。解法：调高SCR_VM_I_COUNT（官方 Aerobatics 示例用到 200000），或把重逻辑挪到低频回调里。

下一步看什么 📚

• libraries/AP_Scripting/examples/：160 多个官方示例脚本（光流导航、NTNTP、Web 服务等），刚起步的抄一个读注释就能上手
• libraries/AP_Scripting/applets/：成品级即插即用脚本（电池监控、执行器扫频、参数锁），每个配了 .md 说明，适合直接搬走改两行
• ArduPilot Discourse 论坛的 scripting 板块：卡死时贴参数全集和控制台日志去问，比干读源码快

把第一个脚本跑起来，比读完十篇教程都管用。

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