企业官网建设流程全解析

• 嵌入式
• 物联网
• 机器人
• 自动驾驶
• 智能硬件

磁力计（Magnetometer）是 PX4 Autopilot 姿态估计与航向解算的关键传感器之一。本文以 Modules Reference: Magnetometer (Driver) 为主体，系统梳理 PX4 内置的十余款磁力计驱动模块及其start / stop / status命令行用法、I2C/SPI 总线选择参数与默认地址，并结合仓库源码（src/drivers/magnetometer与src/modules/sensors）讲解驱动初始化状态机、传感器投票融合与标定相关参数。读完本文，你将能够读懂任意一款磁力计驱动的 CLI 参数，在 NuttX shell 中手动枚举、启动与诊断传感器，并理解磁力计数据从寄存器到 uORB 主题的完整链路。

磁力计驱动在 PX4 中的角色

PX4 将磁力计驱动归类为“Driver / Magnetometer”子类别，全部实现位于 src/drivers/magnetometer 目录，按厂商分子目录组织：

从 CMakeLists.txt 可以看到所有驱动默认纳入构建；而 Kconfig 中的COMMON_MAGNETOMETER选项一键启用一套默认的磁力计驱动集合，板级配置可通过.px4board裁剪。

驱动负责与具体芯片通信、把原始三轴磁场数据发布到sensor_maguORB 主题；后续由 src/modules/sensors/vehicle_magnetometer 模块（VehicleMagnetometer）完成多传感器投票、主传感器选择与vehicle_magnetometer主题发布。

通用命令与参数详解

所有磁力计驱动均遵循同一 CLI 规范：<driver> <command> [arguments...]，其中command固定为：

• start：枚举总线并启动驱动实例；
• stop：停止驱动；
• status：打印驱动状态信息（含寄存器校验计数、传输错误计数等）。

start支持的参数分为“总线选择”和“驱动特定”两类。

I2C 总线选择参数

I2C 型驱动（如 ak09916、bmm150、qmc5883l 等）支持：

SPI 总线选择参数

同时支持 SPI 的驱动（hmc5883、lis3mdl、lsm9ds1_mag、mmc5983ma、rm3100）额外支持：

其中lsm9ds1_mag是纯 SPI 驱动，CLI 中不含任何 I2C 参数；hmc5883还提供-T选项启用温度补偿。

reset 命令

部分驱动（lis3mdl、mmc5983ma）在start/stop/status之外额外提供reset命令，用于在运行中强制复位传感器，便于调试寄存器漂移或数据异常场景。

各磁力计驱动模块速查

下表汇总原文档全部驱动及其start关键差异（I2C 地址默认值、总线类型与特有选项），源码路径以仓库根目录为起点：

说明：地址默认值来源于文档；实际板级接线以各.px4board中的总线/地址配置为准。未列默认地址的驱动（如vcm1193l、SPI 型驱动）需要显式指定或由板级配置提供。

源码级工作原理：以 AK09916 为例

原文档只给出 CLI 接口，其背后的运行逻辑可从 akm/ak09916 源码中读出。驱动基于 PX4 的I2CSPIDriver框架实现（见 AK09916.cpp），_px4_mag负责把原始数据转换为标准传感器接口。

探测与设备识别

probe()读取WIA1（公司 ID0x48）与WIA2（设备 ID），同一驱动可识别 AK09916 / AK09915 / AK09918 多个变体，探测失败时重试 3 次（AK09916.cpp）。寄存器定义集中在 AKM_AK09916_registers.hpp：ST1（DRDY 数据就绪、DOR 数据溢出）、ST2（HOFL 磁场传感器溢出）、CNTL2（50 Hz 连续测量模式）、CNTL3（软件复位）。默认 I2C 地址0b0001100（即 0x0C）、I2C 速率 400 kHz 也在该头文件中定义，与文档默认值一致。

初始化状态机

驱动启动后按RESET → WAIT_FOR_RESET → CONFIGURE → READ状态机推进（AK09916.cpp）：

1. RESET：写CNTL3.SRST触发软复位，延迟 100 ms；
2. WAIT_FOR_RESET：轮询WIA1/WIA2确认复位完成，30 秒超时后重新复位；
3. CONFIGURE：配置连续测量模式寄存器，随后进入周期读取；
4. READ：以 20 ms 间隔（50 Hz）批量读取 ST1 + 三轴数据 + ST2 共 9 字节；ST2.HOFL置位表示磁场溢出，ST1.DRDY就绪才组合x/y/z数据并调用_px4_mag.update()发布。

此外驱动持续做寄存器校验（RegisterCheck）与失败计数：连续失败超过 10 次触发整机复位，保证传感器异常时的自恢复能力。

磁力计融合与相关参数

磁力计数据进入 VehicleMagnetometer.cpp 后由DataValidatorGroup _voter进行多传感器投票，选出主传感器并发布vehicle_magnetometer。该模块的构建期参数在 VehicleMagnetometer.hpp 中声明，参数定义见 sensor_params_mag.yaml：

其中SENS_MAG_MODE直接影响发布策略：代码中multi_mode = (_param_sens_mag_mode.get() == 0)（VehicleMagnetometer.cpp），单传感器模式下仅当存在已选主传感器时才发布（同文件 L549）。多传感器场景还会对主磁力计与其余传感器进行三维磁场向量夹角一致性检查（L705-L717），不一致即触发故障切换，这也是磁力计健康度监控的核心机制。

实战：在 shell 中手动枚举与启动磁力计

在 NuttX shell（通过串口控制台或mavlink_shell.py）中可直接使用上述命令，例如：

# 枚举全部内部 I2C 总线上的磁力计（静默启动） qmc5883l start -I # 指定外部 I2C 总线并覆盖地址与旋转 ak09916 start -X -b 1 -a 12 -R 5 # 查看运行状态（寄存器校验、错误计数） lis3mdl status # 强制复位 mmc5983ma reset # 停止驱动 bmm150 stop

status输出中的性能计数（如 AK09916 的reset、bad_register、bad_transfer、magnetic_sensor_overflow计数，见 AK09916.cpp）是诊断接线异常、寄存器漂移和磁场溢出最直接的证据。正常情况下板载驱动由 ROMFS/px4fmu_common/init.d 下的启动脚本自动调用，手动start主要用于调试与飞线扩展外置磁力计（外置传感器应使用-X并在标定时启用SENS_MAG_AUTOROT）。

小结

PX4 磁力计驱动采用统一的模块化 CLI 设计：start/stop/status三命令贯穿所有芯片，-I/-X/-s/-S区分内外总线，-a覆盖 I2C 地址，-R指定安装旋转。结合 modules_driver_magnetometer.md 的参数速查、src/drivers/magnetometer 的寄存器级实现与 sensor_params_mag.yaml 的融合参数，开发者既能快速定位板级磁力计问题，也能按需为新型号编写驱动，是理解 PX4 传感器子系统的最佳切入点之一。

• 嵌入式
• 物联网
• 机器人
• 自动驾驶
• 智能硬件