ArduPilot 入门教程：零硬件起步，3 条命令跑通从 SITL 仿真到真机首飞

ArduPilot 入门教程：零硬件起步，3 条命令跑通从 SITL 仿真到真机首飞

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

第一次让多旋翼在无人看管下自主返航时，多数人最担心的不是飞不起来，而是失联之后它会做什么：GPS 丢失后往哪飞、低电量在什么高度触发降高。这类问题的答案都写在飞控代码里，而 ArduPilot 正是把飞行逻辑全部开放的开源无人机飞控系统——GPLv3 许可，同一套代码库覆盖多旋翼、固定翼、地面车辆与水下机器人。

认知地图：一套代码库覆盖五类载具

先用下表建立整体概念，再决定从哪里读起：

条目	内容
载具平台	五大入口：ArduCopter / ArduPlane / Rover / ArduSub / AntennaTracker
许可证	GPLv3（全文见 COPYING.txt）
硬件抽象层	libraries/AP_HAL/，含 ChibiOS、SITL、Linux、ESP32 等
核心控制库	libraries/AC_AttitudeControl/、libraries/AP_AHRS/、libraries/AP_NavEKF3/ 等
测试体系	tests/ 单元测试、Tools/autotest/ SITL 自动化飞行测试

判断入口的方法很直接：多旋翼进 ArduCopter/，固定翼与 VTOL 进 ArduPlane/，轮式/履带/船进 Rover/，ROV 进 ArduSub/。每个目录里的mode_*.cpp是各模式实现，failsafe.cpp是安全逻辑，Parameters.cpp是参数定义，这三类文件是读代码的起点。

🚁 上手路线：零硬件跑通 SITL 仿真

第一步：克隆仓库并初始化子模块

git clone https://gitcode.com/GitHub_Trending/ar/ardupilot cd ardupilot && git submodule update --init --recursive

原因：构建脚本 waf、ChibiOS 系统、mavlink 协议库都在子模块里，跳过 init 步骤是构建失败最常见的原因。

第二步：构建 SITL 版 ArduCopter

./waf configure --board sitl && ./waf copter

原因：SITL（软件在环）跑的是和真机完全一致的飞行逻辑，只有硬件抽象层不同（AP_HAL_SITL 对比 AP_HAL_ChibiOS），在仿真里验证过的模式切换、failsafe 和参数设置可以原样带到真机。构建体系的完整说明见 BUILD.md。

第三步：启动仿真与地面站

./Tools/autotest/sim_vehicle.py -v ArduCopter

原因：该脚本同时拉起仿真载具和 MAVProxy 地面站（见 Tools/autotest/sim_vehicle.py 头部说明），在地面站里就能完成 arm、起飞、模式切换、RTL 返航这一整套真机最关心的动作，硬件成本为零。

第四步：硬件选型与真机首飞

准备上真机时，运行./waf list_boards查看可构建的板子列表，按载具需要的接口选型。仓库里每块板子在libraries/AP_HAL_ChibiOS/hwdef/下都有引脚图，以 CM4Pilot 为例：

确认板卡后，把 configure 的--board换成实际板名，重跑./waf copter，再用--upload选项刷入（完整流程见 BUILD.md）。真机首飞建议先拆桨做地面测试：完成传感器校准、确认 arming 检查项全部通过，再低空试飞。

📡 平台选型：按任务场景选模式，而不是按机型

航拍测绘：选 ArduCopter

• 核心模式：PosHold（GPS 位置悬停）、Loiter、Auto（任务执行）。
• 独有能力：相机触发与云台控制，实现在 libraries/AP_Camera/ 和 libraries/AP_Mount/；Auto 模式的任务逻辑见ArduCopter/mode_auto.cpp。
• 注意：起飞前确认 GPS 3D 定位和罗盘状态，RTL 返航依赖家点坐标。

长航时巡航：选 ArduPlane

• 核心模式：Cruise、Loiter、Auto、Autoland。
• 独有能力：TECS（总能量控制系统）用油门和升降舵共同管理总能量，代码在 libraries/AP_TECS/，是固定翼爬升平滑、能耗可控的关键。
• 注意：必须配置最低安全空速并安装空速传感器；抛伞逻辑在ArduPlane/parachute.cpp。

地面巡检：选 Rover

• 核心模式：Hold、Steering、Loiter、RTL。
• 独有能力：路径跟踪与自主导航（Rover/mode_auto.cpp），另有平衡机器人balance_bot.cpp、帆船sailboat.cpp。
• 注意：轮式载具没有"悬停"概念，姿态控制逻辑和多旋翼完全不同，不要直接套用多旋翼的调参经验。

水下作业：选 ArduSub

• 核心模式：Surface（水面）、SurfaceTrack（水面跟踪）、深度保持。
• 独有能力：浮力补偿——ArduSub/Parameters.cpp中提供 Buoyancy 相关参数，用于抵消不同深度下重力与浮力的失衡；深度保持依赖气压计，控制链路和多旋翼的高度保持不同。
• 注意：气压计失效后的行为与高度 failsafe 不同，水下作业的安全策略建议先在 SITL 里单独验证。

🛠️ 避坑清单：四轴调参、校准与安全设置的排查思路

• PID 震荡→ 排查思路：先不动 PID，用出厂默认参数飞行；一次只调一个轴（Roll/Pitch/Yaw），每次调整后用 DataFlash 日志回看；姿态控制参数在 libraries/AC_AttitudeControl/。
• 刷完机后定位不稳、姿态漂移→ 排查思路：加速度计和罗盘校准没做。先跑板载校准，再检查罗盘模型与磁偏角，最后排查电机、电源线的干扰源。
• failsafe 触发后行为意外→ 排查思路：GPS/遥控/电池 failsafe 触发后的动作全部由参数决定。先读默认行为（ArduCopter/failsafe.cpp），再逐项修改，改完先在仿真里触发一次确认。
• 飞行中丢 GPS 定位→ 排查思路：检查天线安装位置，远离金属与电机；起飞前确认 3D 定位；单独验证定位丢失后的 RTL 高度与目标点是否符合预期。
• 电调响应迟缓、电机转向错→ 排查思路：用 Copter 内置的 ESC 校准（ArduCopter/esc_calibration.cpp）校准信号范围；核对电机顺序与桨安装方向一致。
• 模式切换失败→ 排查思路：检查遥控通道映射（libraries/RC_Channel/），在地面站确认当前模式与通道数值，失败后回看日志定位是通道未触发还是模式被安全检查拦截。

生态与入口：文档、社区与贡献路径

• 文档入口：BUILD.md 讲构建与刷写，README.md 讲项目构成；docs/ 提供 doxygen 文档生成配置（Doxyfile.in）。
• 测试入口：tests/ 里的单元测试可本地运行；Tools/autotest/ 是完整的 SITL 自动飞行测试集，适合用它观察每个模式和 failsafe 的真实行为。
• 社区入口：README.md 中列有官方支持论坛与 Discord 频道，打开该文件即可获取地址。
• 贡献路径：从修已知 bug 开始，或为改动补单元测试、SITL 测试用例；代码风格有现成脚本Tools/CodeStyle/ardupilot-astyle.sh。

下一步建议：克隆仓库，配置 sitl 板，启动 ArduCopter 仿真，在地面站里完成一次 arm、起飞、RTL 返航的完整循环，然后对照ArduCopter/failsafe.cpp逐条核对默认安全参数的行为，再开始考虑真机。

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