企业官网建设流程全解析

• 无人机
• 智能硬件

本文基于仓库中的用户指南文档 docs/tr/qgc-user-guide/analyze_view/logging_setup.md（土耳其语版，与 英文版 内容一致），结合 QGroundControl 源码中 ArduPilot 日志配置组件的实际实现展开讲解。

导读

本文讲解 QGroundControl（QGC）中面向 ArduPilot 载具的Log Setup（Vehicle Config > Logging）配置页面：它解决"飞行控制器记录什么、以什么方式记录、以多高速率记录"这一核心问题。读完本文，你将掌握该页面暴露的 11 个日志相关参数（LOG_BACKEND_TYPE、LOG_BITMASK、EK3_LOG_LEVEL等）的作用与推荐取值，理解这些参数如何通过 QGC 标准参数系统（Facts）下发到飞控，并学会使用官方故障排查清单定位日志缺样、存储不足等典型问题。

页面入口与适用范围

Log Setup页面位于Vehicle Config > Logging，仅对 ArduPilot 系列载具可用（包括 Copter、Plane、Rover、Sub 等机型）。它用于配置飞控"记录什么内容、写到哪些后端、以多大速率记录"。

从源码结构看，该页面由APMLoggingComponent组件承载：

• 组件注册：在 src/AutoPilotPlugins/APM/APMAutoPilotPlugin.cc#L174-L176 中，APMAutoPilotPlugin::vehicleComponents()创建APMLoggingComponent实例并加入组件列表，随后与其他 Vehicle Config 页面一起按名称排序展示；
• 组件属性：在 src/AutoPilotPlugins/APM/APMLoggingComponent.h 中可以看到，该组件name()为 "Logging"，description()为 "Configure ArduPilot logging parameters."，且allowSetupWhileArmed()与allowSetupWhileFlying()均返回true——意味着飞行中或已解锁状态下也可打开该页面查看/调整日志配置，无需降落。

页面如何构建：VehicleConfig.json 驱动的代码生成

QGC 的 ArduPilot 配置页面并非手写 QML，而是由 JSON 页面定义 + 代码生成器自动生成。日志页面的定义文件是 src/AutoPilotPlugins/APM/VehicleConfig/APMLogging.VehicleConfig.json，它声明了三个分区（sections）：Storage、Rate Limits、Options。

组件的vehicleConfigJson()返回该 JSON 的 Qt 资源路径（见 src/AutoPilotPlugins/APM/APMLoggingComponent.cc#L9-L12）。构建阶段，src/AutoPilotPlugins/APM/CMakeLists.txt#L81-L100 通过qgc_add_qml_codegen调用tools.generators.config_qml.generate_pages，把*.VehicleConfig.json生成APMLoggingComponent.qml等页面文件。

对用户而言，这意味着两件事：

• JSON 中所有控件都标注了optional: true，当连接的固件/机型不支持某参数时，对应控件会自动隐藏，页面只会展示当前固件实际存在的参数；
• 使用 bitmask（位掩码）控件和 combobox（下拉框）控件直接呈现多选/枚举型参数，例如LOG_BACKEND_TYPE、LOG_BITMASK以 bitmask 形式勾选，LOG_DISARMED、EK3_LOG_LEVEL等以下拉框形式选择。

核心参数详解

页面暴露的参数共 11 个，按下表分组。以下默认值来自仓库中的 ArduPilot 固件离线参数文件 src/FirmwarePlugin/APM/Copter.OfflineEditing.params#L552-L565（Copter 机型默认值，其他机型略有差异），供参考。

Storage（存储）分区

要点说明：

• LOG_BACKEND_TYPE：默认值1与 ArduPilot 的位定义吻合（1 = 文件后端，写入 SD 卡；2 = MAVLink 流；4 = 板载 Flash），可以按需组合。若选择 MAVLink 后端，日志会通过遥测链路持续下发，需配合LOG_MAV_RATEMAX控制速率，避免挤占遥测带宽；
• LOG_BITMASK：控制"记什么"。位掩码中不同的位对应 IMU、GPS、磁力计、控制输出等数据组；完整位含义由 ArduPilot 固件定义，QGC 仅以位掩码形式呈现。如需减少日志体积，可在此取消不需要的数据组；
• LOG_MAX_FILES/LOG_FILE_MB_FREE：共同保障"写不爆"——前者限制文件数量防止无限增长，后者在剩余空间低于阈值时停止写入，避免 SD 卡写满影响其他功能。

Rate Limits（速率限制）分区

要点说明：

• 速率为 0 通常表示使用固件内置的默认速率上限；
• 三者的共同逻辑是背压保护：文件写入、Flash 写入、MAVLink 下发各自独立限速。当出现"日志缺样"（记录间隔异常、采样丢失）时，优先下调对应后端的速率上限，而不是盲目调高，这与下文故障排查清单的建议一致；
• 若使用高分辨率 IMU 数据组（LOG_BITMASK中开启），单位时间内数据量很大，需要确保文件速率上限足以承接，否则会丢样本。

Options（选项）分区

其中EK3_LOG_LEVEL在页面 JSON 中明确枚举了四个取值（见 src/AutoPilotPlugins/APM/VehicleConfig/APMLogging.VehicleConfig.json#L103-L113）：

要点说明：

• LOG_DISARMED、LOG_REPLAY均为调试专用：解锁日志与重放数据都会显著增大文件体积，只在排查问题时按需开启（与故障排查清单的建议一致）；
• LOG_FILE_DSRMROT开启后每次 disarm/rearm 生成独立文件，便于按起降架次归档与分析，代价是文件数量增多，建议配合LOG_MAX_FILES控制保留数量；
• EK3_LOG_LEVEL影响 EKF3 状态估计日志的信息量，通常保持默认的 Full logging，仅在分析特定新息问题时才降级以减小体积。

补充：固件离线参数文件（如 Copter.OfflineEditing.params）中还包含LOG_FILE_BUFSIZE、LOG_MAV_BUFSIZE、LOG_DARM_RATEMAX、LOG_FILE_TIMEOUT等更多日志相关参数，它们不在此页面暴露，但可通过 QGC 的Parameter页面（Vehicle Config > Parameters）直接编辑，本页面聚焦于上文 11 个最常用的配置项。

参数编辑如何落地：QGC Facts 参数系统

原文档明确指出：所有参数编辑都通过 QGC 标准参数系统（Facts）应用。这意味着 Log Setup 页面上的每次改动与你在 Parameters 页面手动修改同名参数完全等价，共享同一套底层链路：

• 页面控件绑定到Fact对象，参数值与类型由FactMetaData描述；
• 写入请求经由ParameterManager通过 MAVLinkPARAM_SET下发到飞控，读取则走PARAM_REQUEST_READ/ 参数缓存；
• 相关实现位于 src/FactSystem/Fact.cc、src/FactSystem/ParameterManager.cc，参数元数据定义见 src/FactSystem/factmetadata.schema.json。

因此，你在 Log Setup 页面做的任何修改，都会真实写入飞控的非易失参数存储；与手动改参数相比，Log Setup 的优势在于按场景分组、给出人类可读标签（如 "Logging backends"、"Maximum retained log files"）并以位掩码/下拉框形式避免手输错值。

故障排查清单

原文档附带的排查清单（结合上文参数含义扩充）是日志问题的第一处置步骤：

1. 使用已知良好的 SD 卡并验证其可写：多数日志写入问题源于 SD 卡损坏、接触不良或文件系统异常；先确认LOG_BACKEND_TYPE包含文件后端（默认值1），再更换已知良好的卡复测；
2. 预留足够的剩余空间：根据预期飞行时长估算日志体积，确保空间高于LOG_FILE_MB_FREE（默认 500 MB）设置的阈值，否则日志不会开始写入；
3. 日志缺样时降低速率上限：若日志中出现缺失样本、记录间隔跳变，下调LOG_FILE_RATEMAX（文件后端）或LOG_BLK_RATEMAX（Flash 后端），使写入速率低于存储介质实际吞吐；使用 MAVLink 后端时还需检查LOG_MAV_RATEMAX与链路带宽的匹配；
4. 仅在调试需要时开启解锁/重放日志：LOG_DISARMED（解锁记录）与LOG_REPLAY（EKF 重放数据）都会显著增大日志体积，平时保持关闭，排查 pre-arm 或 EKF 问题时再开启，问题解决后记得关闭；
5. 对低容量板载 Flash 定期下载并清理日志：若使用板载 Flash 后端，注意其容量远小于 SD 卡，需通过 QGC 定期下载日志并清空（可在 Analyze View 的 Log Files 区域操作），并合理设置LOG_MAX_FILES让旧日志自动轮转，防止 Flash 写满导致后续飞行日志丢失。

参考与进一步阅读

• 完整参数说明（分组表格版）：docs/tr/qgc-user-guide/setup_view/logging_ardupilot.md（英文版见 docs/en/qgc-user-guide/setup_view/logging_ardupilot.md）；
• 页面定义 JSON：src/AutoPilotPlugins/APM/VehicleConfig/APMLogging.VehicleConfig.json（含各控件的位掩码/下拉框/枚举定义）；
• 组件实现：src/AutoPilotPlugins/APM/APMLoggingComponent.cc 与 src/AutoPilotPlugins/APM/APMLoggingComponent.h；
• 组件注册位置：src/AutoPilotPlugins/APM/APMAutoPilotPlugin.cc#L174-L176；
• 固件默认参数（含各日志参数出厂默认值）：src/FirmwarePlugin/APM/Copter.OfflineEditing.params#L552-L565（Plane/Rover/Sub 对应文件在同目录下）；
• 参数系统底层：src/FactSystem/Fact.cc、src/FactSystem/ParameterManager.cc。

• 无人机
• 智能硬件