HMC5883L 是一款常用的 三轴数字磁力计，内部集成磁阻传感器与 12-bit ADC，可通过 I²C 接口输出磁场在三个正交方向上的分量数据。
该芯片通常用于：
- 电子指南针（Heading / 航向角）
- 姿态解算中的磁航向参考
- 移动机器人、无人设备的方向感知
HMC5883L 输出的并非“方向角”，而是 X / Y / Z 三轴磁场强度数据，方向信息需要通过计算得到。
XYZ 数据含义说明
HMC5883L 输出的 X、Y、Z 数据表示磁场在芯片内部坐标系上的三个分量：
- X 轴：磁场在芯片 X 方向上的投影
- Y 轴：磁场在芯片 Y 方向上的投影
- Z 轴：磁场在芯片 Z 方向上的投影（垂直于 X–Y 平面）
注意： X / Y / Z 坐标系为 芯片本体坐标系，与地理坐标系（东、南、西、北）无直接对应关系，其方向取决于模块在 PCB 上的安装朝向。
在模块水平放置的情况下，通常使用 X、Y 两轴数据计算航向角（Heading），Z 轴主要用于倾斜判断或倾斜补偿。
航向角（Heading）说明
在不考虑倾斜的情况下，航向角可由 X、Y 两轴磁场数据计算：
heading = atan2(Y, X)
计算结果表示磁场方向相对于芯片 X 轴的夹角，通常需要转换为角度制并归一化到 0° ~ 360° 范围。
当模块存在倾斜时，需要结合 Z 轴及姿态信息进行倾斜补偿，否则航向角会产生明显误差。
校准与环境影响
HMC5883L 对周围环境非常敏感，实际测量中常见以下问题：
- 零偏（Offset）：数据中心点偏离 0
- 比例失真（Scale）：旋转一周后数据呈椭圆而非圆形
- 环境干扰：电机、电流、螺丝、铁磁材料都会影响读数
在本测试工程中，可通过旋转模块、观察 X/Y 数据变化及上位机指示效果，用于验证和修正磁力计数据的可用性。