HMC5883L三轴指南针模块：从I2C通信到航向解算的Arduino实战指南

1. 项目概述：Grove - 三轴指南针 V1.0

如果你玩过Arduino或者树莓派，大概率听说过Grove这个生态系统。它最大的好处就是把各种传感器、执行器都模块化了，用统一的四针接口连接，省去了焊接和复杂的杜邦线连接，特别适合快速原型开发。今天要聊的这块“Grove - 三轴指南针 V1.0”，就是其中非常经典的一款地磁传感器模块。它的核心是一颗HMC5883L芯片，通过I2C总线和你手头的开发板（比如Arduino Uno）通信，告诉你当前它感知到的磁场强度，进而换算成方向角。

简单来说，这就是一个电子罗盘。但它的价值远不止告诉你“北在哪”。在智能小车导航、无人机姿态参考、手持设备的方向检测，甚至是结合加速度计做九轴姿态融合（IMU）时，它都是不可或缺的一环。我最初接触它是因为一个户外探险记录仪的项目，需要在不依赖GPS信号的情况下（比如丛林或隧道里）持续记录行进方向。市面上数字罗盘模块不少，但Grove版本的集成度和易用性确实对新手和快速验证想法的开发者非常友好。

这个模块虽然标注是V1.0，但因其核心HMC5883L的稳定性和Grove接口的普及，至今仍在大量项目中被使用。接下来，我会从硬件拆解、通信原理、驱动编写、数据处理到实际应用中的坑，为你完整梳理一遍。无论你是想把它装到小车上实现循迹中的方向纠正，还是想做一个酷炫的电子指南针，这篇文章都能给你提供从接线到代码、从原理到调试的全程参考。

2. 硬件拆解与接口定义

2.1 核心芯片：HMC5883L探秘

模块的核心是美国霍尼韦尔（Honeywell）的HMC5883L三轴磁阻传感器。这是一颗表面贴装的芯片，采用I2C数字接口输出。它的“三轴”指的是能同时测量X、Y、Z三个相互垂直方向上的磁场强度分量。地球磁场其实很微弱，大约在0.25至0.65高斯之间（即25至65微特斯拉），HMC5883L的测量范围可以软件配置，默认是±1.3高斯（±130微特斯拉），分辨率为5毫高斯（0.5微特斯拉），这个精度对于检测地磁并计算航向角已经绰绰有余。

芯片内部除了三个正交的磁阻传感元件，还集成了信号放大、模数转换（ADC）和I2C接口电路。这意味着它直接输出数字量，省去了我们处理模拟信号的麻烦。需要注意的是，HMC5883L对周围环境非常敏感。你手边的手机、电脑显示器、甚至是一块有磁性的螺丝刀，都会干扰它的读数。所以在实际安装时，要尽量远离电机、扬声器、电源变压器等强磁或大电流器件。

2.2 Grove接口与电气连接

Grove接口标准化为四根线：VCC（红色）、GND（黑色）、SDA（白色）、SCL（黄色）。对于这个指南针模块：

• VCC：工作电压为3.3V或5V。模块内部有稳压电路，两种电压都兼容，但官方推荐使用3.3V以获得最佳性能，因为HMC5883L芯片的核心电压是3.3V。如果你接5V，模块上的LDO（低压差线性稳压器）会将其降至3.3V给芯片供电，但可能会产生一点额外的热量。
• GND：电源地，必须与主控板共地。
• SDA：I2C数据线。这是一个双向开漏引脚，意味着模块内部不会主动将线路拉高，需要主控板或外部电路提供上拉电阻。幸运的是，大多数Arduino开发板（如Uno）的I2C接口（A4/SDA, A5/SCL）已经在板子上集成了上拉电阻（通常是4.7kΩ）。如果你使用的是某些没有内置上拉电阻的MCU（比如一些裸STM32最小系统板），你就必须在SDA和SCL线上各接一个上拉电阻（通常4.7kΩ到10kΩ）到VCC，否则通信会失败。
• SCL：I2C时钟线，特性与SDA相同。

注意：I2C总线是共享总线。你可以将多个I2C设备（如这个指南针、一个OLED屏幕、一个温湿度传感器）的SDA和SCL分别并联在一起，通过不同的设备地址来区分它们。HMC5883L的默认I2C设备地址是0x1E（7位地址格式）。这是一个固定值，无法通过硬件修改，所以一个I2C总线上通常只能挂一个HMC5883L模块。

2.3 模块布局与安装要点

拿到模块，你会看到除了Grove接口，板子上还有几个重要的焊盘和元件：

1. HMC5883L芯片：通常位于板子中央，覆盖着一层黑色的环氧树脂保护层。
2. 跳线帽或焊盘：有些版本的模块会有一个“I2C地址选择”的焊盘。如果短接，可能会将地址切换到另一个备用地址（如0x1F）。但Grove V1.0版本通常没有这个设计，地址固定为0x1E。使用前最好用I2C扫描程序确认一下。
3. LED电源指示灯：通电后会亮起，方便判断模块是否上电。
4. 安装方向：模块PCB上通常会用丝印标出X、Y轴的方向（例如一个十字坐标）。这一点至关重要！计算航向角依赖于X、Y轴的测量值。你必须明确知道在你的项目中，模块是如何安装的。通常约定：模块平放时，X轴指向板子上的箭头或标记方向，Y轴垂直于X轴向右，Z轴垂直板面向外。后续的所有计算都基于这个坐标系。

在实际安装到小车或设备上时，尽量用塑料或铜柱固定，避免使用含铁螺丝。如果必须用金属螺丝，确保它们是非磁性的（如不锈钢）。安装位置应尽可能远离电机和电池。我曾在一个四轴飞行器项目中将模块安装在飞控板旁边，结果电机一转动，读数就完全乱套，后来不得不通过一根塑料支柱将模块架高，远离电调和大电流走线，情况才好转。

3. I2C通信协议与寄存器配置

要让HMC5883L工作，我们必须通过I2C协议与它“对话”。I2C是一种同步、半双工、多主从的串行总线，协议本身不难，但对于初次接触的朋友可能会觉得时序有点绕。理解它对于排查通信故障非常有帮助。

3.1 I2C通信基础与HMC5883L的地址

I2C通信由两根线完成：串行数据线（SDA）和串行时钟线（SCL）。每个设备都有一个唯一的7位地址。通信总是由主设备（我们的Arduino）发起。一次典型的读取数据过程如下：

1. 主设备发送起始条件（S）。
2. 主设备发送从设备地址（7位）加写标志位（0），即(0x1E << 1) | 0 = 0x3C。
3. 从设备（HMC5883L）应答（ACK）。
4. 主设备发送要访问的寄存器地址（例如，数据寄存器X轴高8位的地址是0x03）。
5. 从设备应答。
6. 主设备发送重复起始条件（Sr）。
7. 主设备发送从设备地址加读标志位（1），即(0x1E << 1) | 1 = 0x3D。
8. 从设备应答。
9. 从设备开始连续发送该寄存器及其后续寄存器的数据（对于HMC5883L，连续读取时地址会自动递增）。
10. 主设备在接收完最后一个字节后，发送非应答（NACK）然后发送停止条件（P）。

在Arduino环境中，我们有强大的Wire库来封装这些底层操作，使得读写寄存器变得非常简单。但了解这个过程，当你用逻辑分析仪抓取波形排查“为什么读不到数据”时，就能一眼看出问题出在哪一步。

3.2 关键寄存器详解

HMC5883L内部有一组控制寄存器，我们需要配置它们来设定模块的工作模式、数据输出速率和测量范围。以下是几个最关键的寄存器：

配置寄存器A (0x00)： 通常我们设置为0x70（二进制01110000）。这表示：

• 平均样本数(MA)：11= 8个样本平均。取平均可以降低噪声。
• 数据输出速率(DO)：100= 15 Hz。即每秒输出15组数据。对于小车导航，这个速率足够了。如果需要更快，可以设置为75Hz甚至更高，但噪声可能会增大。
• 测量模式(MS)：00= 正常测量模式。这是默认值。

配置寄存器B (0x01)： 这个寄存器设置增益（GN），也就是量程。增益值越小，灵敏度越高，但更容易饱和（超出量程）。默认值是0x20（二进制00100000），对应增益1，量程为±1.3高斯。这是最常用的设置。如果你的环境磁场干扰较强，读数经常接近±2047（溢出），就需要调低增益（增大数值）来扩大量程。例如，0xE0（增益7）对应±8.1高斯。

模式寄存器 (0x02)： 我们通常希望模块持续测量，所以设置为连续测量模式：0x00。如果设置为单次模式（0x01），模块在完成一次测量后会自动进入空闲模式以省电，需要再次写指令才会触发下一次测量。

3.3 数据读取流程与字节顺序

配置好寄存器后，模块就会按照设定的速率持续测量。读取数据的标准流程是：

1. 检查状态寄存器（0x09）的RDY位（第0位），或者简单地等待大于等于1/输出速率的时间（如15Hz对应约66ms），确保新数据已就绪。
2. 告诉HMC5883L我们要从数据寄存器X轴高8位（0x03）开始读取。
3. 连续读取6个字节。这里有一个非常重要的细节：HMC5883L的数据输出顺序是X, Z, Y，而不是X, Y, Z！很多初学者在这里栽跟头，算出的角度莫名其妙。
   • 字节0: X轴高8位
   • 字节1: X轴低8位
   • 字节2: Z轴高8位
   • 字节3: Z轴低8位
   • 字节4: Y轴高8位
   • 字节5: Y轴低8位
4. 将这6个字节组合成三个16位有符号整数（范围-32768 ~ +32767）。注意，这些是原始ADC读数。
5. 根据当前设置的增益（GN），将原始读数转换为实际的磁场强度（单位为高斯或微特斯拉）。转换公式是：实际值 = 原始读数 / (增益 * 灵敏度)。对于默认增益1，灵敏度是1370 LSb/Gauss（数据手册值）。所以磁场强度(Gauss) = 原始读数 / 1370。

在实际编程中，为了简化，我们有时会跳过单位转换，直接用原始读数来计算航向角，因为角度计算是一个比值（Y/X），单位换算的系数在比值运算中会被约掉。但如果你需要真实的磁场强度值，或者需要比较不同增益下的数据，就必须进行转换。

4. Arduino驱动编写与校准实践

理论讲完了，我们动手写代码。这里我会提供一个经过实战检验的、包含基本校准功能的Arduino驱动示例。

4.1 基础驱动代码实现

首先，包含Wire库并定义设备地址和寄存器地址。

#include <Wire.h> #define HMC5883L_ADDR 0x1E // 7位I2C地址 // 寄存器地址 #define REG_CONFIG_A 0x00 #define REG_CONFIG_B 0x01 #define REG_MODE 0x02 #define REG_DATA_X_H 0x03 #define REG_STATUS 0x09 // 全局变量存储原始数据 int16_t magX, magY, magZ; void setup() { Serial.begin(9600); Wire.begin(); // 初始化I2C，Arduino Uno的SDA=A4, SCL=A5 // 初始化HMC5883L initHMC5883L(); } void loop() { readHMC5883L(); // 读取数据 float heading = calculateHeading(magX, magY); // 计算航向角 Serial.print("X: "); Serial.print(magX); Serial.print(" Y: "); Serial.print(magY); Serial.print(" Z: "); Serial.print(magZ); Serial.print(" Heading: "); Serial.println(heading); delay(100); // 控制输出频率 } void initHMC5883L() { Wire.beginTransmission(HMC5883L_ADDR); Wire.write(REG_CONFIG_A); Wire.write(0x70); // 8平均，15Hz，正常模式 Wire.endTransmission(); Wire.beginTransmission(HMC5883L_ADDR); Wire.write(REG_CONFIG_B); Wire.write(0x20); // 增益1 (±1.3 Ga) Wire.endTransmission(); Wire.beginTransmission(HMC5883L_ADDR); Wire.write(REG_MODE); Wire.write(0x00); // 连续测量模式 Wire.endTransmission(); } void readHMC5883L() { // 请求读取6个字节，从X高字节开始 Wire.beginTransmission(HMC5883L_ADDR); Wire.write(REG_DATA_X_H); Wire.endTransmission(false); // 发送重复起始条件 Wire.requestFrom(HMC5883L_ADDR, 6); // 注意字节顺序：X高，X低，Z高，Z低，Y高，Y低 if (Wire.available() >= 6) { magX = (Wire.read() << 8) | Wire.read(); // X高 <<8 | X低 magZ = (Wire.read() << 8) | Wire.read(); // Z高 <<8 | Z低 magY = (Wire.read() << 8) | Wire.read(); // Y高 <<8 | Y低 } } float calculateHeading(int16_t x, int16_t y) { // 使用atan2函数计算角度，结果在 -π 到 π 弧度之间 float headingRad = atan2((float)y, (float)x); // 转换为0到2π弧度 if (headingRad < 0) { headingRad += 2 * PI; } // 转换为0到360度 float headingDeg = headingRad * 180 / PI; return headingDeg; }

这段代码完成了最基础的功能：初始化、读取原始数据、计算航向角。但直接用它，你会发现指南针指向可能不准，而且转动模块时，角度变化不线性。这是因为我们还没有进行校准。

4.2 硬铁与软铁干扰校准

传感器读数不准主要受两种干扰：“硬铁干扰”和“软铁干扰”。

• 硬铁干扰：来自固定在设备上的永久磁铁或磁化材料（如磁化螺丝）。它会在原始读数上增加一个固定的偏移量。校准方法是找出每个轴的最大值和最小值，计算偏移量：偏移量 = (最大值 + 最小值) / 2。
• 软铁干扰：来自设备中磁性材料（如铁壳）在地磁场中被磁化后产生的感应磁场。它会导致各轴读数之间产生交叉耦合，表现为椭圆形的数据分布。校准它需要更复杂的椭圆拟合或最小二乘法，但对于要求不高的应用，我们可以使用简单的“最大值-最小值”缩放法来近似补偿。

下面是一个简单的校准程序。你需要将模块在水平面上缓慢旋转至少360度，同时代码会记录每个轴的最大最小值。

// 全局校准变量 int16_t magX_min = 32767, magX_max = -32768; int16_t magY_min = 32767, magY_max = -32768; int16_t magZ_min = 32767, magZ_max = -32768; float magX_offset, magY_offset, magZ_offset; float magX_scale, magY_scale, magZ_scale; void calibrationLoop() { readHMC5883L(); // 更新最大值和最小值 magX_min = min(magX_min, magX); magX_max = max(magX_max, magX); magY_min = min(magY_min, magY); magY_max = max(magY_max, magY); magZ_min = min(magZ_min, magZ); magZ_max = max(magZ_max, magZ); // 实时打印当前范围，方便观察 Serial.print("X:["); Serial.print(magX_min); Serial.print(","); Serial.print(magX_max); Serial.print("] "); Serial.print("Y:["); Serial.print(magY_min); Serial.print(","); Serial.print(magY_max); Serial.print("] "); Serial.print("Z:["); Serial.print(magZ_min); Serial.print(","); Serial.print(magZ_max); Serial.println("]"); } void calculateCalibrationParams() { // 计算硬铁偏移（中心点） magX_offset = (magX_max + magX_min) / 2.0; magY_offset = (magY_max + magY_min) / 2.0; magZ_offset = (magZ_max + magZ_min) / 2.0; // 计算软铁缩放比例（使各轴范围对称） // 先计算平均半径 float avg_delta_x = (magX_max - magX_min) / 2.0; float avg_delta_y = (magY_max - magY_min) / 2.0; float avg_delta_z = (magZ_max - magZ_min) / 2.0; float avg_delta = (avg_delta_x + avg_delta_y + avg_delta_z) / 3.0; magX_scale = avg_delta / avg_delta_x; magY_scale = avg_delta / avg_delta_y; magZ_scale = avg_delta / avg_delta_z; Serial.println("\n=== 校准参数 ==="); Serial.print("偏移量 X: "); Serial.print(magX_offset); Serial.print(" Y: "); Serial.print(magY_offset); Serial.print(" Z: "); Serial.println(magZ_offset); Serial.print("缩放比例 X: "); Serial.print(magX_scale); Serial.print(" Y: "); Serial.print(magY_scale); Serial.print(" Z: "); Serial.println(magZ_scale); } // 使用校准参数修正读数 void applyCalibration(int16_t &x, int16_t &y, int16_t &z) { float xf = (float)x; float yf = (float)y; float zf = (float)z; x = (int16_t)((xf - magX_offset) * magX_scale); y = (int16_t)((yf - magY_offset) * magY_scale); z = (int16_t)((zf - magZ_offset) * magZ_scale); }

在校准模式下运行calibrationLoop()，同时手动旋转模块。观察串口输出的各轴范围，直到X和Y轴的最大最小值基本稳定且范围接近（例如X和Y的范围都接近[-500, 500]），而Z轴范围可能不同（因为模块平放旋转时Z轴基本不变）。然后调用calculateCalibrationParams()计算并保存参数。在正常测量循环中，先readHMC5883L()，再applyCalibration(magX, magY, magZ)，最后用修正后的值计算航向角。

实操心得：校准最好在最终安装位置进行。比如你的指南针要装在小车里，那就把整个小车放在无磁干扰的开放空间（远离建筑和汽车），然后让小车原地缓慢旋转进行校准。这样校准结果包含了车体本身的所有磁性干扰，是最准确的。

4.3 航向角计算的进阶处理

基础的atan2(y, x)计算存在两个问题：

1. 倾斜误差：当模块不是绝对水平时（比如小车在坡上），Z轴的磁场分量会投影到X-Y平面，导致计算出的水平航向角不准。解决这个问题需要引入加速度计进行倾斜补偿（即制作一个电子罗盘IMU），这涉及到传感器融合，比较复杂。
2. 磁偏角：地理北极（真北）与地磁北极（磁北）并不重合，它们之间的夹角叫磁偏角。这个角度随地理位置和时间变化。如果你需要非常精确的真北方向，就需要查询当地的磁偏角进行修正。修正公式很简单：真北航向 = 磁北航向 + 磁偏角。东偏为正值，西偏为负值。可以在网上搜索“磁偏角计算”找到相关服务。

对于大多数机器人或小车项目，我们只需要一个稳定的、可重复的相对方向参考，磁偏角和轻微的倾斜误差可以忽略。但如果你在做导航，尤其是与GPS航向结合时，就必须考虑它们。

5. 典型应用场景与项目集成

5.1 智能小车的航向锁定

在自动循迹或遥控小车中，加入指南针可以实现在长直道上保持航向，或者在指定角度转弯。思路是设定一个目标航向角，然后通过PID控制器调整左右轮速差，使当前航向角逼近目标角。

// 伪代码示例：简单的航向PD控制 float targetHeading = 90.0; // 目标朝向东方 float currentHeading; float lastError = 0; float Kp = 0.5, Kd = 2.0; // PID参数需调试 void headingControlLoop() { readAndCalibrateCompass(); // 读取并校准指南针数据 currentHeading = calculateHeading(magX, magY); float error = targetHeading - currentHeading; // 处理角度跨越360°的突变 if (error > 180) error -= 360; if (error < -180) error += 360; float derivative = error - lastError; float steeringAdjust = Kp * error + Kd * derivative; lastError = error; // 根据steeringAdjust调整左右电机速度 // 例如：leftSpeed = baseSpeed + steeringAdjust; // rightSpeed = baseSpeed - steeringAdjust; }

5.2 结合OLED屏幕制作电子罗盘

这是一个很好的可视化项目。使用一个128x64的OLED屏幕（也是I2C接口，地址通常为0x3C），可以同时显示数字航向角和模拟的罗盘指针。

1. 硬件连接：将指南针模块和OLED屏幕的VCC、GND、SDA、SCL分别并联，接到Arduino的对应引脚。
2. 软件库：需要Wire.h、Adafruit_GFX.h和Adafruit_SSD1306.h。
3. 显示逻辑：在loop()中读取指南针数据，计算角度，然后在OLED上绘制一个圆形表盘，根据角度画一条从圆心指向边缘的线作为指针，同时在屏幕顶部或底部打印角度数值。

这个项目能直观地展示传感器数据，也是调试校准效果的好方法。如果指针跳动严重，说明校准没做好或环境干扰大；如果转动模块时指针反应迟钝或有偏差，就需要检查计算和校准代码。

5.3 姿态参考系统中的磁力计

在无人机或平衡车的姿态解算中，磁力计（指南针）与加速度计、陀螺仪组成九轴传感器（MPU9250等芯片已集成）。加速度计可以感知重力方向，从而知道俯仰和横滚角，但无法感知绕垂直轴的旋转（偏航角）。陀螺仪可以测量角速度，积分得到角度变化，但存在累积误差（漂移）。磁力计正好可以提供绝对的偏航角参考，用来校正陀螺仪的漂移。

这个过程称为传感器融合，常用算法有互补滤波、卡尔曼滤波（Kalman Filter）或更先进的Madgwick、Mahony滤波。虽然实现起来有门槛，但有很多开源库（如Arduino的MadgwickAHRS库）可供使用。你需要将校准后的磁力计数据（单位向量）和加速度计数据一起输入滤波算法，就能得到稳定的四元数或欧拉角，其中就包含了准确的偏航角。

6. 常见问题排查与调试技巧

即使按照教程操作，你也可能会遇到各种问题。下面是我在多个项目中总结出来的“排坑指南”。

6.1 I2C通信失败：读不到数据或地址不对

症状：Wire.requestFrom返回0，或者读取的数据全是0或255（0xFF）。排查步骤：

1. 检查接线：这是最常出错的地方。确保VCC、GND、SDA、SCL四根线连接正确且牢固。SDA和SCL不要接反。
2. 检查上拉电阻：如果你用的主控板I2C引脚没有内置上拉电阻（比如某些STM32核心板），必须在SDA和SCL线上各接一个4.7kΩ的电阻到3.3V。没有上拉，信号无法被拉高，通信必然失败。
3. 运行I2C扫描程序：在Arduino IDE中上传一个I2C扫描程序（示例->Wire->Scanner），查看串口监视器。如果能看到设备地址0x1E（或显示为0x3C，这是包含读写位的8位地址），说明通信链路基本正常。如果扫描不到，回到步骤1和2。
4. 检查电源：尝试用3.3V而不是5V为模块供电。虽然模块兼容5V，但在某些情况下3.3V更稳定。
5. 逻辑分析仪抓包：如果以上都不行，用逻辑分析仪（或示波器）连接SDA和SCL线，抓取一次完整的通信波形。看起始条件、地址、应答位是否正常。这是终极排查手段。

6.2 数据跳动剧烈或指向不准

症状：静止时航向角数值也在不断跳动（噪声大），或者转动模块时角度变化不连续、有固定偏差。可能原因与解决：

1. 环境磁干扰：这是首要原因。将模块拿到户外开阔地测试。远离电脑、手机、电源适配器、金属桌子。如果户外读数稳定，说明室内干扰太强。
2. 未校准或校准不充分：必须执行完整的校准流程。在校准过程中，要确保模块在所有可能的方向都缓慢旋转过，让每个轴都能采集到最大最小值。只水平旋转只能校准X和Y轴。
3. 安装位置不当：模块离电机、电源线太近。尝试重新布线或用屏蔽材料隔离。
4. 电源噪声：使用电池供电测试，排除开关电源带来的高频噪声干扰。可以在模块的VCC和GND之间并联一个100nF的陶瓷电容进行滤波。
5. 数据输出速率过高：尝试在配置寄存器A中降低输出速率（如从15Hz降到1.25Hz），并增加平均样本数（如8平均改为16平均），可以显著降低噪声，但会牺牲响应速度。

6.3 计算出的航向角象限错误或范围不对

症状：角度只在0-90°或0-180°之间变化，而不是0-360°。排查：

1. 检查atan2函数的使用：确保第一个参数是Y轴读数，第二个参数是X轴读数，即atan2(y, x)。参数顺序反了会导致象限错误。
2. 检查字节顺序：再次确认你读取的6个字节组合顺序是X高、X低、Z高、Z低、Y高、Y低。把X和Y的数据弄混是最常见的错误。
3. 检查数据类型：确保将两个8位字节组合成16位整数时，正确处理了符号位。int16_t类型能正确表示负数。(Wire.read() << 8) | Wire.read()这个写法在Arduino上是没问题的。
4. 角度转换公式：使用atan2得到的是弧度值，范围是-π到+π。要转换成0-360度，需要判断结果是否为负，为负则加2π，然后再乘以180/π。

6.4 模块发热或功耗异常

症状：模块摸起来温热，或者电池消耗很快。可能原因：

1. 工作模式：检查是否错误地设置为了连续测量模式下的最高速率（如75Hz）且高增益，这会增加功耗。如果不是必要，使用默认的15Hz和增益1即可。
2. 电源电压：如果你用5V供电，模块上的LDO线性稳压器会将5V降至3.3V，多余的电压（1.7V）会以热量的形式耗散。如果模块电流为1mA，那么LDO的功耗就是1.7mW，通常不会明显发热。如果发热严重，检查是否有短路或模块损坏。优先使用3.3V供电。

最后，分享一个调试小技巧：在串口绘图仪（Serial Plotter）中同时绘制原始的magX和magY值。当你水平旋转模块时，你应该看到两条相位相差大约90度的正弦波曲线。如果曲线形状怪异、幅度不对称或者有平顶（饱和），那肯定是校准或干扰问题。这个可视化工具比单纯看数字直观得多。