QMC5883L磁力计接Arduino,算航向角做数字指南针

2026-11-18 20:43:51 17阅读

QMC5883L磁力计引脚图

想让小车知道自己在往哪个方向走,GPS 在短距离内帮不上忙,IMU 里的陀螺仪又会漂。这时候最省事的方案,是给主控加一颗三轴磁力计,直接测地磁场的方向,做成数字指南针。QMC5883L 就是这类方案里最常见的一颗芯片,某宝上几块钱一片的 GY-271 模块,基本用的都是它。这篇把接线、读数、算航向角三步一次讲完,代码可以直接搬去用。

动笔前我把电路基础教程网站那篇磁力计教程完整过了一遍,本篇的接线表和示例代码都以它为准,代码逐字符搬运,只把头文件写法换成了站点能正常显示的引号形式,编译效果等价。

先分清 HMC5883L 和 QMC5883L,别买混了

这是绕不开的第一个坑。网上资料最多的是 HMC5883L,很多人照着它的教程和库去接线编程,结果怎么都读不出数。底稿作者也栽在这个坑里:他从 eBay 买回来的模块,丝印明明写着 HMC5883L,折腾半天才发现芯片实际是 QMC5883L。

这两颗是不同厂商的芯片,并不兼容:HMC5883L 的 I2C 地址是 0x1E,QMC5883L 是 0x0D,连寄存器定义都不一样,给 HMC5883L 写的库对 QMC5883L 完全无效。而市面上现在卖的 GY-271 小板,绝大多数已经是 QMC5883L 了,只是丝印还印着 HMC5883L。所以拿到手先按 QMC5883L 对待,找对库再动手,能少走很多弯路。

判断方法也简单:用 I2C 扫描程序扫一下地址,扫到 0x0D 就是 QMC5883L,扫到 0x1E 才是真的 HMC5883L。

五个引脚,I2C 四根线接完

QMC5883L 模块一共五个引脚:VCC、GND、SCL、SDA、DRDY。它走 I2C 通信,真正接数据的只有 SCL 和 SDA 两根,加上电源两根就够了;DRDY 是数据就绪信号引脚,教程里的用法没用到它,悬空即可。

用 Arduino Uno 接线如下:

  • VCC → 5V
  • GND → GND
  • SCL → A4
  • SDA → A5
  • DRDY → 悬空

QMC5883L与Arduino Uno接线图

Uno 的 A4、A5 就是硬件 I2C 的 SDA、SCL,这是固定映射,不用在代码里另外指定。另外注意模块上印的方向箭头:x、y、z 三个轴的指向是相对板上丝印定的,z 轴垂直于板面朝上,x、y 在板面内。之后算航向角靠的是 x 和 y,所以模块装到小车上时必须保持水平摆放,斜着装航向角就不准了。

装库,先读出三轴原始值

程序用的是 SunFounder 的 QMC5883L 库,在底稿页面的资源区可以下载到,装进 Arduino IDE 后就能用。第一段程序只做一件事:把三个轴的磁场读数打到串口监视器。

站点正文会把尖括号头文件吞掉,所以下面的 #include 统一写成了引号形式,#include "Wire.h" 等价于原来的 #include ,在 Arduino 里两种写法编译等价,直接复制可用:

#include "Wire.h"
#include "QMC5883L.h"

QMC5883L compass;

void setup() {
  Wire.begin();
  Serial.begin(9600);
  compass.init();
}

void loop() {
  int x, y, z;

  compass.read(&x, &y, &z);

  Serial.print("x: ");
  Serial.print(x);
  Serial.print("    y: ");
  Serial.print(y);
  Serial.print("    z: ");
  Serial.println(z);

  delay(250);
}

代码逻辑很短:因为模块走 I2C,先包含 Wire 库并 Wire.begin() 初始化总线;再建一个 QMC5883L 类的 compass 对象,setup() 里用 init() 初始化。loop() 里核心是 read() 这个函数,它一次带回三个轴的读数,三个参数分别是存 x、y、z 读数的变量地址,所以传的是取地址形式。每轮读完延时 250 毫秒,串口输出不至于刷得太快。

串口监视器输出的三轴原始磁场读数

上传后打开串口监视器,就能看到三轴数值在跳。这些原始值反映的是各轴磁场强度,单位是微特斯拉量级。底稿里给了个很直观的验证办法:拿一块条形磁铁的北极凑近模块 x 轴箭头所指的方向,x 读数会明显下降;换到 y、z 轴方向同理。就算没有任何磁铁,传感器也灵敏到能测出地球本身的磁场——这正是它能当指南针的原因。

从三轴读数到航向角:atan2(y, x)

有了 x、y 两个轴的读数,航向角就靠一个三角函数。把 x、y 看成平面坐标里的一个点,传感器 x 轴指向的那个方向就对应一个从北(0°)出发的角度,用 atan2() 把 y 除以 x 的比值换算成角度即可,返回的是弧度,再乘 180 除以 π 转成度。北 0°、东 90°、南 180°、西 270°,这套罗盘刻度和实体指南针完全一致。

单位圆上由x与y分量求航向角

算出来的角度如果为负,加 360 转回 0 到 360° 区间就行。再往下还可以做一层罗盘方位映射:把 360° 按 22.5° 一档切成 16 个方位,从 N、NNE、NE 一路排到 NNW,串口直接打出"方位名",比看小数度数直观得多。底稿的完整示例就是这么写的,代码如下,同样逐字符搬运:

#include "Wire.h"
#include "QMC5883L.h"

QMC5883L compass;

void setup() {
  Wire.begin();
  Serial.begin(9600);
  compass.init();
}

void loop() {
  int x, y, z;
  String cardinal;

  compass.read(&x, &y, &z);

  float headingRadians = atan2(y, x);
  float headingDegrees = headingRadians * 180 / PI;
  float declinationAngle = 11.41666666666667;

  headingDegrees += declinationAngle;

  if (headingDegrees < 0) {
    headingDegrees += 360;
  }

  if (headingDegrees > 348.75 || headingDegrees < 11.25) {
    cardinal = " N";
  }
  else if (headingDegrees > 11.25 && headingDegrees < 33.75) {
    cardinal = " NNE";
  }
  else if (headingDegrees > 33.75 && headingDegrees < 56.25) {
    cardinal = " NE";
  }
  else if (headingDegrees > 56.25 && headingDegrees < 78.75) {
    cardinal = " ENE";
  }
  else if (headingDegrees > 78.75 && headingDegrees < 101.25) {
    cardinal = " E";
  }
  else if (headingDegrees > 101.25 && headingDegrees < 123.75) {
    cardinal = " ESE";
  }
  else if (headingDegrees > 123.75 && headingDegrees < 146.25) {
    cardinal = " SE";
  }
  else if (headingDegrees > 146.25 && headingDegrees < 168.75) {
    cardinal = " SSE";
  }
  else if (headingDegrees > 168.75 && headingDegrees < 191.25) {
    cardinal = " S";
  }
  else if (headingDegrees > 191.25 && headingDegrees < 213.75) {
    cardinal = " SSW";
  }
  else if (headingDegrees > 213.75 && headingDegrees < 236.25) {
    cardinal = " SW";
  }
  else if (headingDegrees > 236.25 && headingDegrees < 258.75) {
    cardinal = " WSW";
  }
  else if (headingDegrees > 258.75 && headingDegrees < 281.25) {
    cardinal = " W";
  }
  else if (headingDegrees > 281.25 && headingDegrees < 303.75) {
    cardinal = " WNW";
  }
  else if (headingDegrees > 303.75 && headingDegrees < 326.25) {
    cardinal = " NW";
  }
  else if (headingDegrees > 326.25 && headingDegrees < 348.75) {
    cardinal = " NNW";
  }

  Serial.print("Heading: ");
  Serial.print(headingDegrees);
  Serial.println(cardinal);

  delay(250);
}

磁偏角与硬铁校准,决定准不准的最后两步

代码里有一行 float declinationAngle = 11.41666666666667,这是磁偏角修正。指南针指的是地磁北极,地图上的北是地理北极,两者现在相差约 310 英里,这个差值随所在地区变化,最大能差到 15 度左右。底稿给的查法是去 www.magneticdeclination.com 输入所在城市,查到的值是"度+分",把分除以 60 换算成小数度再加到度数上,填进 declinationAngle 那行。做小车循迹、航向保持这类应用,这十几度的偏差足够让车越走越歪,值得认真填。

另一个常见问题是读数不靠谱,多半是磁干扰。模块周边的铁件、电机(尤其是带永磁体的直流电机和舵机)、大电流走线都会叠加一个固定或随状态的磁场,让航向角整体偏掉。工程上通用的应对是硬铁校准:让模块在水平面内慢速转一整圈,记录 x、y 读数的最大最小值,算出中心偏移(两个极值的平均),之后每次读数先减掉这个偏移再用 atan2。软铁干扰(椭圆畸变)还可以进一步做缩放校正,但玩家级应用一般做完平移校正就有明显改善。

还有一个实操细节:校准和以后的使用环境要保持一致,装上车之后连车一起再转一圈重新标定,比空板标定准得多。

整套下来,一颗几块钱的 QMC5883L、四根杜邦线、两个现成的示例程序,就能给小车或遥控船装上一个能报方位的电子罗盘。真正花时间的往往不是代码,而是装机位置、磁偏角和校准这三件"环境活"——把它们做扎实,航向角才能稳定可用。


作者:电机传感器师
链接:https://www.aiddithome.com/p/f9ebb16cb92df.html
本作版权归作者所有,未经允许请勿转载。若存在违规行为,您可以点击 “举报”。


登录 后发表评论
4条评论
深圳打工人Alan
1楼 · 5小时前

atan2(y,x)这里讲得清楚,之前一直没搞明白为什么是y在前,看单位圆那张图就懂了,x、y当坐标点,角度从北边0°起算。

参数党小马
2楼 · 5小时前

磁偏角那个细节很实在,好多教程都让你直接用返回的角度,其实不修正的话小车跑直线会越走越歪,十来度偏差看着不多,走十米就偏出好几米了。

入门没多久的新手
3楼 · 5小时前

硬铁校准那段建议再强调一下:装上车之后要连车一起转一圈重新标,我一开始空板校准的,装上底盘读数直接飘了快30度。

阿伟不emo
4楼 · 5小时前

这个坑我踩过!去年买了个丝印印着HMC5883L的模块,照老教程折腾了一晚上读数全是0,最后才发现是QMC的芯片,库都不一样。文中说的I2C扫描地址区分法确实好使,扫到0x0D就别再纠结HMC的库了。