电子罗盘模块HMC5883L与QMC5883L选型及代码实践

简介：资源面向嵌入式软硬件开发者与电子爱好者，系统讲解HMC5883L、QMC5883L三轴磁力计及GY-271电子罗盘模块的应用。内容涵盖传感器工作原理、寄存器配置、I2C/SPI通信协议与校准流程，并针对两种芯片的差异进行了说明，便于选型与移植。包内提供STC51单片机测试代码、Arduino示例及配套数据手册、原理图，可帮助读者快速理解驱动逻辑并搭建指南针应用。压缩包共81个文件、3.12MB，以C源码、hex可烧录固件、PDF手册、电路图纸及工程文件为主，结构清晰，适合直接拿来参考或二次开发。已有6943人学习，尤其适合需要对比国产与进口磁力计、完成三轴方向测量的初中级开发者。

1. 电子罗盘模块选型先搞清：HMC5883L 与 QMC5883L 到底差在哪

某巡检小车项目里，GPS 在楼宇间完全抓不到稳定信号，车头朝向只能靠电子罗盘模块撑起来。当时手头有两颗长得几乎一样的芯片——HMC5883L 和 QMC5883L，都是三轴磁场传感器，都能输出航向角，但 I2C 地址、寄存器布局、数据读取顺序甚至坐标轴方向都不同，直接套网上现成代码必然翻车。这份资源把两套测试代码、数据手册和常见坑放在一起，读完能在一小时内搞清楚该选哪颗、怎么接线、怎么读原始磁场值并换算成 0°~359.9° 的方位角。适合正在做机器人导航、手持测向仪、气象百叶箱或任何需要罗盘航向输出的开发者，从 Arduino 到 STM32 都能套。

2. 硬件准备与寄存器差异：接线、地址探测和两颗芯片的数据手册对照

2.1 芯片差异与选型对照

HMC5883L 是老牌磁力计方案，早年几乎垄断了民用三轴罗盘市场，I2C 地址是 0x1E，ADC 位宽 12 位，量程通过配置寄存器 B 分档，输出速率最高只能到 75Hz。QMC5883L 是后来出现的兼容型方案，引脚定义差不多，但 I2C 地址改成了 0x0D，把过采样档位、输出速率、量程全部塞进一个配置寄存器里，最高跑到 200Hz，数据手册里的寄存器布局和 HMC 完全不兼容。

选型上我的判断是：如果你在做一个低速巡检小车或者手持测向设备，HMC 完全够用，而且市面上老代码最多，抄起来快；如果要做航模、需要高刷新率配合陀螺仪做姿态解算，QMC 的 200Hz 输出和过采样设计更对症。两者的数据手册在资源包里都有，下面这张表是我实际对着手册整理出来的差异。

需要提醒的是，某些模块虽然印着 HMC5883L 兼容的丝印，实际焊的却是 QMC5883L，所以不能只看模块标签，得靠后面介绍的地址探测来确认。

2.2 接线与 I2C 地址探测

模块一般引出 VCC、GND、SCL、SDA、DRDY 五个引脚，DRDY 是数据就绪信号，轮询读取时可以不接。VCC 我一般接 3.3V，很多模块板载了稳压芯片也能吃 5V，但手册的电气特性是按 3.3V 写的，接 5V 时注意别让 I2C 上拉电阻也拉到 5V，否则和 3.3V 主控通信时可能超出逻辑电平范围。

接线就四根：VCC 接 3.3V，GND 接 GND，SCL 接主控 I2C 时钟，SDA 接数据线。多数开发板默认把 SCL/SDA 接了上拉电阻，但如果走线很长，建议在 SCL、SDA 上各加一个 4.7kΩ 上拉到 3.3V，这是我处理很多传感器模块的常规做法。先用一段扫描代码确认芯片地址：

#include <Wire.h> void setup() { Serial.begin(115200); Wire.begin(); } void loop() { Serial.println("scan start..."); for (byte addr = 1; addr < 127; addr++) { Wire.beginTransmission(addr); if (Wire.endTransmission() == 0) { Serial.print("found: 0x"); Serial.println(addr, HEX); } } delay(3000); }

这段代码对 1~127 的全部 7 位地址逐一发起 I2C 通信，能收到 ACK 就认为有设备应答。扫描结果是 0x1E 就是 HMC5883L，0x0D 就是 QMC5883L。注意 8 位地址和 7 位地址的区别：比如 HMC 用 7 位地址 0x1E，换算成 8 位写地址是 0x3C、读地址是 0x3D，有些库函数要的是 8 位地址，搞混了会一直通信失败。

如果扫描结果不稳定，优先怀疑供电和上拉。模块的 VCC 不要从电机驱动板的同一路电源取，电机启动瞬间压降会拉低 VCC 导致 I2C 直接掉线。另外，I2C 总线比较长时，信号上升沿会变缓，可以把 Wire.setClock 降到 100000 甚至 10000 再扫一次，排除时钟速率问题。

2.3 寄存器映射速查

HMC5883L 的寄存器从 0x00 开始，0x00 是配置寄存器 A，控制采样平均次数、数据输出速率和测量模式；0x01 是配置寄存器 B，控制增益档位；0x02 是模式寄存器，写入 0x00 进入连续测量模式。真正的数据在 0x03~0x08 六个字节，顺序是 X 高字节、X 低字节、Z 高字节、Z 低字节、Y 高字节、Y 低字节，这一点特别反直觉，很多抄来的代码都写成了 X、Y、Z。

QMC5883L 的寄存器是另一套：0x00~0x05 是 X、Y、Z 的原始数据，每个轴两字节，低字节在前；0x09 是状态寄存器，bit0 为 1 表示新数据就绪；0x0A 是配置寄存器 1，一次写入输出速率、过采样、量程和测量模式；0x0B 是配置寄存器 2，用于软复位和硬复位；0x0D 是标识寄存器，正常通信时读回 0xFF。

建议拿到模块后第一件事就是读 0x0D，如果读到 0xFF，说明 I2C 通路没问题，再往下写配置才有意义。HMC 没有这个标识寄存器，这也是区分两颗芯片最直接的手段。QMC 的 0x0B 寄存器里有一个软复位位，写 1 可以让芯片重新上电初始化，如果程序跑着跑着读数卡死，先软复位一次再配置，比直接断电重启更快。

HMC 的模式寄存器也值得多说一句：写 0x00 是连续测量模式，芯片会按照配置好的输出速率持续更新数据；写 0x01 是单次测量模式，每次测量前需要重新写一次 0x01 触发，适合低功耗场景，代价是多一次 I2C 操作的延时。做手持设备时用单次模式省电，做实时导航就老老实实用连续模式。

3. 核心代码拆解：HMC5883L/QMC5883L 磁力计代码从 I2C 读值到航向角输出的完整链路

3.1 HMC5883L 数据读取：从 0x03 开始连读 6 字节

HMC 的驱动代码核心就是把 0x03 以后的六个寄存器连续读出来。先写一个通用的寄存器写函数，用来配置三个控制寄存器：

#include <Wire.h> #define HMC_ADDR 0x1E void writeReg(byte reg, byte val) { Wire.beginTransmission(HMC_ADDR); Wire.write(reg); Wire.write(val); Wire.endTransmission(); } void setup() { Wire.begin(); Wire.setClock(400000); // 模块支持 100kHz ~ 400kHz writeReg(0x00, 0x70); // 采样平均 8 次，输出速率 15Hz writeReg(0x01, 0x20); // 增益档位按手册推荐值 writeReg(0x02, 0x00); // 连续测量模式 }

0x00 寄存器写入 0x70，二进制的采样平均位是 11，对应平均 8 次，输出速率位是 100，对应 15Hz，这样能让数据更稳，代价是单次数据之间的间隔略长。0x01 写入 0x20 是手册推荐的默认增益档位，不同的增益对应不同的灵敏度和量程，换算成磁场强度时要用对应的每 LSB 高斯数。0x02 写入 0x00 就是连续测量模式，省去每次读取前再发单次触发命令。

bool readHMC(int16_t* x, int16_t* z, int16_t* y) { Wire.beginTransmission(HMC_ADDR); Wire.write(0x03); // 定位到数据寄存器起始 Wire.endTransmission(); Wire.requestFrom(HMC_ADDR, 6); // 连续读 6 字节 if (Wire.available() < 6) return false; *x = Wire.read() << 8 | Wire.read(); // X 高字节在前 *z = Wire.read() << 8 | Wire.read(); // Z *y = Wire.read() << 8 | Wire.read(); // Y return true; }

这里的关键是读取顺序。HMC 的数据寄存器从 0x03 到 0x08，对应的物理量是 X、Z、Y，Z 排在 Y 前面。如果按 X、Y、Z 的顺序组装，Z 和 Y 会互相交换，角度计算结果会彻底乱掉。int16_t 是有符号 16 位整数，这样读出来的值能保留磁场的正负方向，方便后面的象限判断。

读取完成后，前面 0x01 增益档位对应的灵敏度会告诉你每个 LSB 代表多少高斯，换算公式是 磁场强度 = 原始整数 / 灵敏度，其中灵敏度单位是 LSB/Gauss。资源包里的数据手册有一整张增益与量程对照表，不同增益档位查表用，不要从上往下猜。一个常见的现实问题是，主循环里 requestFrom 后立刻读 6 字节，如果 I2C 总线忙或者模块还没就绪，可用字节可能不足 6 个，所以我总是让函数返回 bool，读不到完整一帧就跳过本次循环，而不是原地阻塞等待。

3.2 QMC5883L 数据读取：低字节在前，别忘了状态寄存器

QMC 的读取流程要简单一些，数据寄存器从 0x00 开始，同样六字节一次读完：

#include <Wire.h> #define QMC_ADDR 0x0D void setup() { Wire.begin(); Wire.setClock(400000); Wire.beginTransmission(QMC_ADDR); Wire.write(0x0A); Wire.write(0x1D); // 常用组合：连续测量、高输出速率、大量程 Wire.endTransmission(); } bool readQMC(int16_t* x, int16_t* y, int16_t* z) { Wire.beginTransmission(QMC_ADDR); Wire.write(0x00); Wire.endTransmission(true); Wire.requestFrom(QMC_ADDR, 6); if (Wire.available() < 6) return false; // QMC 低字节在前，和 HMC 完全相反 *x = Wire.read() | Wire.read() << 8; *y = Wire.read() | Wire.read() << 8; *z = Wire.read() | Wire.read() << 8; return true; }

0x0A 配置寄存器 1 写 0x1D，这个数是从数据手册的配置表里抄来的常用组合，代表连续测量模式、较高的输出速率以及 ±8G 量程。过采样档位越高，内部平均次数越多，等效噪声越小，代价是每次输出前处理时间长一点。量程选 ±8G 是为了在地磁场约 0.5G 的背景下留足余量，传感器不会饱和。如果只在地面水平场景用，量程也可以降下来换取更细的分辨率。

两个细节容易踩坑：第一，QMC 的字节序是低字节在前，和高字节在前的 HMC 正好相反，直接套 HMC 代码读出的数据会错一大截；第二，0x00 开始读 6 字节之前，可以先读 0x09 状态寄存器，bit0 为 1 说明新数据已经准备好，再发起六字节读取更稳。我一般会在主循环里加上这个状态判断，避免读到同一帧旧数据。

另外，QMC 的 0x0D 标识寄存器读出来应该是 0xFF，如果实际读到的不是这个值，要么芯片型号不对，要么 I2C 通信已经出错。软件复位可以写 0x0B 寄存器的软复位位，然后延迟几毫秒再重新配置 0x0A，这一招在处理芯片偶发锁死时很管用。

3.3 航向角换算与磁偏角修正

拿到 X、Y 轴磁场分量后，航向角用这个公式算：

float heading = atan2((float)my, (float)mx) * 180.0f / PI; if (heading < 0) { heading += 360.0f; // 让输出范围落在 0~360 } // 磁偏角按所在地查询后填入，单位是弧度 float declination = 0.0457f; // 示例值约 2.62° heading += declination * 180.0f / PI; if (heading >= 360.0f) heading -= 360.0f;

atan2 是四象限反正切，能根据 X、Y 的正负自动判断角度落在哪个象限，比 atan 只返回一个象限范围要省很多事。磁偏角是地理北极和磁北极之间的夹角，不同城市差好几度，在线查一下当地磁偏角填进去，方向才会指向真北。中国境内常见磁偏角大致在正负几度到十几度范围，地图资料里的“磁偏角在线查询工具”输入经纬度就能查到。

一个玄学一点的坑：同样的公式在 HMC 和 QMC 上跑出来，角度可能是镜像的，因为两颗芯片的坐标轴方向定义不同，模块丝印方向也不一定一致。处理逻辑是，如果发现水平旋转模块时输出角度和实际转向相反，把公式里的 my 换成 -my 重算即可；如果差 180°，把 mx 变成 -mx。这个符号问题没有统一答案，和数据手册里的轴方向图示以及模块安装方式都有关，只能放到实际环境里转一圈验证。

4. 校准方法与实践：绕 8 字采集三轴范围，消除硬磁偏移

4.1 为什么磁力计必须校准以及“8 字”怎么绕

磁力计测的是磁场矢量，但芯片周围只要有铁磁性材料，比如螺丝、电池、电机外壳、PCB 上的铜皮，就会叠加一个固定的偏置磁场。这个偏置会让原本应该以原点为中心的圆形采样点变成偏离原点的圆，换算出来的角度就会周期性偏移。校准这件事的本质，就是把这个偏置的圆心、半径找回来。

做法是手持模块或者把模块固定在小车末端，在空中反复画 8 字，也就是让 X、Y、Z 三个轴尽可能都朝向各个方向，过程中持续采集原始值。HMC 和 QMC 的原始值单位不同，但这不影响校准逻辑，因为校准用到的只是最大值和最小值，不涉及单位换算。只在一个平面上转不行，那样 Z 轴的上下范围完全覆盖不到，倾斜之后角度照样飘。

4.2 校准采集与修正代码

我在实际项目里会把采集和修正拆成两个阶段，采集阶段用结构体记录每个轴的范围：

struct CalData { float mn[3] = { 9999.0f, 9999.0f, 9999.0f }; float mx[3] = { -9999.0f, -9999.0f, -9999.0f }; float offset[3]; float scale[3]; }; CalData cal; void collectCalibration() { int16_t x, y, z; unsigned long start = millis(); while (millis() - start < 30000) { // 持续 30 秒 if (readHMC(&x, &z, &y)) { float fx = x, fy = y, fz = z; if (fx < cal.mn[0]) cal.mn[0] = fx; if (fx > cal.mx[0]) cal.mx[0] = fx; if (fy < cal.mn[1]) cal.mn[1] = fy; if (fy > cal.mx[1]) cal.mx[1] = fy; if (fz < cal.mn[2]) cal.mn[2] = fz; if (fz > cal.mx[2]) cal.mx[2] = fz; } delay(20); } for (int i = 0; i < 3; i++) { cal.offset[i] = (cal.mn[i] + cal.mx[i]) / 2.0f; cal.scale[i] = (cal.mx[i] - cal.mn[i]) / 2.0f; } } void applyCalibration(int16_t rawX, int16_t rawY, int16_t rawZ, float* cx, float* cy, float* cz) { *cx = (rawX - cal.offset[0]) / cal.scale[0]; *cy = (rawY - cal.offset[1]) / cal.scale[1]; *cz = (rawZ - cal.offset[2]) / cal.scale[2]; }

offset 就是硬磁偏置，scale 是半个量程，修正后的三个分量会被压缩到 -1 到 1 之间，相当于把偏心球拉回原点并归一化成单位球。采集 30 秒、每 20 毫秒采一次，总共 1500 个左右样本，正常情况下足够覆盖各种姿态；如果绕 8 字绕得很敷衍，只在一个平面上转，Z 轴范围会明显小于 X、Y，导致倾斜后角度误差变大。

采样间隔 20ms 是我常用的值，对应 50Hz 的采集频率，既能保证样本量，又不会让串口刷屏刷到没法看。用 QMC 的时候输出速率本来就到 200Hz，可以跑到 5ms 间隔采样，但传感器自身的随机噪声会被保留更多，不如把过采样档位调高、用稍慢的采样率取平均更干净。

4.3 校准完成后的应用顺序

校准的前提是使用环境变化不大。模块固定在机器人和固定在桌面上，周围铁磁环境完全不一样，所以每次换安装位置都要重新校准。另外校准修正要在航向角计算之前做，也就是先用修正后的 cx、cy 去算 atan2，顺序反了的话，偏置依然会污染角度。

看到修正确实有效的一个简单验证方法是，在水平桌面让模块旋转一整圈，把修正后的 X、Y 值输出到一个串口绘图工具上，显示出来的图形应该是一个以原点为圆心、半径接近 1 的圆。如果圆心明显偏移，说明采集没覆盖全姿态；如果圆压扁了，那要考虑软磁效应，需要引入椭圆拟合，普通项目用硬磁校准就够用。

我习惯把 offset 和 scale 存到主控的掉电保存区域或者 SD 卡里，冷启动时直接读出来，不需要每次上电都绕 8 字。如果后续发现角度依然有固定偏差，问题通常出在磁偏角没更新，而不是校准失效。校准参数是跟着安装环境走的，换了安装位置、换了固定螺丝长度、甚至换了电池位置，都应该重新采一次。

5. 踩坑与排查：磁力计代码最常见的 5 个数据异常

5.1 现象、原因与解决办法

第一条：I2C 扫描扫不到任何设备。现象是扫描代码跑完一个地址都没返回，或者每次都卡死在 endTransmission。原因多数是 SCL/SDA 接反了，或者模块 VCC 实际没供上电，也有可能是模块上的 I2C 上拉电阻和主控上拉电阻叠加导致信号畸形。解决办法是先按 2.2 的接线表重新核对四根线，再用万用表量 VCC 和 GND 之间有没有 3.3V，最后把 Wire.setClock 降到 10000 试试低速模式，很多软硬件握手问题降速就能暴露出来。

第二条：HMC 读出来的三个数完全对不上，X 轴很大、Y 轴很小且 Z 轴像噪声。原因就是读取顺序写成了 X、Y、Z 而不是 X、Z、Y，这是抄驱动代码最容易翻车的地方。解决办法是严格按照数据手册 0x03~0x08 的顺序组装，别信网上流传的二手代码。我最早也在这里栽过，后来每次写 HMC 驱动都会先翻前面那张寄存器速查表。

第三条：买的模块标着 HMC5883L，但按 0x1E 怎么都读不通。这是市场上很常见的货不对板，部分模块背面焊的其实是 QMC5883L，只是丝印还留着 HMC 的型号。解决办法是用 I2C 扫描器看真实地址，扫到 0x0D 就按 QMC 的流程走；进一步确认可以读 0x0D 寄存器，返回 0xFF 就是 QMC。从此我拿到模块第一件事永远是扫描地址加读标识寄存器，这个习惯帮我避开了两次类似的大坑。

第四条：角度输出在 0 到 360 之间来回跳，方向完全不受控制。原因通常是没做校准，或者是公式里用了 atan 而不是 atan2，导致角度只在 -90°~90° 范围变化。解决办法是先把输出换算成 atan2 并加上象限处理；如果还是乱，把模块放在远离金属物体的桌面重新做一次 8 字校准。还有一种情况是角度本来正常，但磁偏角正负弄反了，表现为整个角度固定偏一个常量，把 declination 取相反数重试即可。

第五条：电机一转，角度马上乱跳。原因是电机的永磁体和大电流导线产生的磁场直接叠加在地磁场上，磁力计离电机越近影响越大。解决办法是模块远离电机和电源线，至少隔开 10 厘米以上；如果结构上没法拉开距离，就在航向角输出后加一个移动平均滤波，窗口取 5~10 个样本，能把高频抖动压下去，代价是响应变慢。车载场景还要注意，金属车架会改变磁场分布，校准必须在整车装配完成之后做，单独校准模块再上车等于白校。

5.2 硬件排查顺序：先地址、再原始值、最后谈角度

数据异常时不要一头扎进代码逻辑里，我习惯按三层排查：第一层确认通信，扫描地址、读标识寄存器，保证 I2C 通路是好的；第二层确认原始值，让模块水平静置，观察三轴读数是否稳定、大小是否在合理范围，地磁场大约 0.25G 到 0.65G，如果某个轴读数长期为 0 或者数值大到离谱，先怀疑焊接和供电；第三层才轮到角度公式和校准问题。

这种排查顺序能省下大量时间。通信没通之前，任何校准和滤波都是白费，因为输入数据本身就是坏的黑匣子。另外，串口输出的时候建议把原始三轴值和计算后的航向角一起打出来，方便对比到底是原始数据坏了还是算法坏了。串口绘图时最好一行输出原始整数、一行输出换算后的角度，中间用制表符分隔，观察起来比十六进制直观得多。

6. 二次开发思路：从 HMC 到 QMC 的迁移与姿态融合

6.1 HMC 到 QMC 的迁移要点

如果你手头代码是给 HMC 写的，想换 QMC，照着下面这张表改就能省去大部分排查时间。

除了表格这些，还要记得对称重写数据组装语句，因为低字节在前和高字节在前的移位方向完全相反。角度公式不用变，只需根据实际转向决定是否对 my 取负号。

6.2 配合加速度计做倾斜补偿

如果小车上下坡或者颠簸，磁力计没有保持水平，直接用 X、Y 计算的角度会偏。常见做法是引入加速度计算出俯仰角和滚转角，再把磁场矢量投影回水平面。我一般用这种形式的补偿公式：

float pitch = atan2(accX, accZ); float roll = atan2(accY, accZ); float cosP = cos(pitch); float sinP = sin(pitch); float cosR = cos(roll); float sinR = sin(roll); float xh = mx * cosP + mz * sinP; float yh = mx * sinR * sinP + my * cosR - mz * sinR * cosP; float heading = atan2(yh, xh) * 180.0f / PI + declinationDeg;

注意先用校准后的磁场值再进这个公式，加速度计的值也要先做低通滤波去掉振动噪声。这套东西再往下扩展就是把合成后的 heading 当作一维输入喂给 PID 控制器，用来做直线行驶的航向保持。

6.3 输出滤波与工程习惯

最后补一个我常用的轻量低通滤波，直接套在航向角上：

float filtered = filterAlpha * maxNoWrap + (1.0f - filterAlpha) * lastValidHeading;

处理 0°/360° 接缝处角度跨越时会先转成角度的 sin/cos 累加再还原，或者判断前后差值超过 180° 时补偿 360° 偏移，否则滤波输出会在正北方向抖一下。这算是我踩过的最有迷惑性的坑之一。

从那以后，我每次拿到磁力计模块都强制先走一遍“扫地址、读标识、读原始值、再算角度”的流程，芯片确认清楚之前不写任何应用逻辑，血泪经验换来的习惯，希望帮到你。

本文还有配套的精品资源，点击获取