Johnny-Five 实战:在 Tessel 2 上驱动 MAG3110 三轴磁力计指南针(Compass 组件详解)

原创2026-09-21 09:53:541,741 阅读
文章标签:IoT机器人嵌入式

Johnny-Five 实战:在 Tessel 2 上驱动 MAG3110 三轴磁力计指南针(Compass 组件详解)

导读

本文围绕 docs/compass-MAG3110-tessel.md 展开,讲解如何在 Tessel 2 开发板上通过 Johnny-Five 的 Compass 组件驱动 NXP MAG3110 三轴磁力计,实时读取航向角(heading)与方位(bearing),并利用磁力计的自动校准能力获取稳定、可复用的偏移数据。读完本文,你将掌握 MAG3110 在 Tessel 2 上的完整接线、示例运行方式、offsets 预校准参数的含义,以及 Johnny-Five 底层如何通过 I²C 寄存器配置与轮询实现航向计算。


一、MAG3110 与 Compass 组件简介

MAG3110 是 NXP 出品的一款低功耗三轴数字磁力计,通过 I²C 总线与主控通信。它常被用来构建电子罗盘、航向参考系统与磁场探测应用。在 Johnny-Five 中,MAG3110 被封装为 Compass 组件的一个控制器(controller),在 lib/compass.js 中与 HMC5883L、HMC6352、BNO055、LSM303C 等并列注册(见 lib/compass.js 的 MAG3110 定义),相关数据手册索引记录在 lib/datasheets.md。

Compass 组件对外暴露三个只读属性:

  • heading:以度为单位的航向角(方位角,azimuth),取值范围 0–360,由 lib/compass.js 中的 heading getter 实时调用 toScaledHeading(raw) 计算得到;
  • bearing:将 heading 映射到 32 点罗盘(32-point compass)上的方位对象,包含 name、abbr、low、high、heading 字段(见 lib/compass.js 与 Compass.Points 定义 lib/compass.js);
  • raw:当前未处理的 X/Y/Z 原始读数(见 lib/compass.js)。

此外,组件会以 freq(默认 25ms)为周期检查航向是否发生变化,并触发 data 与 change 事件(见 lib/compass.js)。


二、硬件准备与接线(Breadboard)

本文示例运行在 Tessel 2 上,接线方式与 Arduino 版(见 docs/compass-MAG3110.md)不同之处仅在于 Tessel 2 使用 tessel-io 作为 IO 插件,MAG3110 同样通过 I²C 与主控连接。

官方文档提供的面包板接线图为 docs/breadboard/compass-MAG3110-tessel.png,Fritzing 工程文件为 docs/breadboard/compass-MAG3110-tessel.fzz,可用来精确核对引脚连接。

Compass MAG3110 在 Tessel 2 上的面包板接线图

MAG3110 模块(常见于 Adafruit 等分线板)典型连接如下:

MAG3110 引脚 Tessel 2 引脚 说明
VIN / 3V3 3.3V 供电
GND GND 共地
SDA SDA(I²C 数据线) 数据
SCL SCL(I²C 时钟线) 时钟

注意:MAG3110 只有一个可能的 I²C 地址 0x0E,无需、也无法通过引脚跳线修改地址。这一点在源码中有明确注释(见 lib/compass.js),测试用例也验证了“即使显式传入 address: 0xff,控制器仍会强制覆盖为 0x0E”(见 test/compass.js)。


三、运行官方示例

1. 环境准备

Tessel 2 场景下需要两个 npm 包:

  • johnny-five:本仓库对应的机器人框架;
  • tessel-io:Tessel 2 的 IO 插件,负责把 Johnny-Five 的抽象 IO 调用映射到 Tessel 2 的硬件资源。

示例源码位于 eg/compass-MAG3110-tessel.js,它与文档中的示例代码一致,唯一的差别是示例文件通过 require("../lib/johnny-five.js") 引用仓库源码,而文档示例按发布后的包名写作 require("johnny-five")。

2. 从命令行运行

node eg/compass-MAG3110-tessel.js

运行前请确保 Tessel 2 已通过 USB 连接并被系统识别,且 tessel-io 已安装到当前 Node.js 项目。

3. 完整代码

const Tessel = require("tessel-io");
const { Board, Compass } = require("johnny-five");
const board = new Board({
  io: new Tessel()
});

board.on("ready", () => {
  const compass = new Compass({
    controller: "MAG3110",
    // Optionally pre-load the offsets
    offsets: {
      x: [-819, -335],
      y: [702, 1182],
      z: [-293, -13],
    },
  });

  compass.on("calibrated", offsets => {
    // Use this data with the optional "offsets" property above
    // console.log("calibrated:", offsets);
  });

  compass.on("change", () => {
    const {bearing, heading} = compass;
    console.log("Compass:");
    console.log("  bearing     : ", bearing);
    console.log("  heading     : ", heading);
    console.log("--------------------------------------");
  });
});

关键点说明:

  • controller: "MAG3110" 指定使用 MAG3110 控制器,驱动逻辑见 lib/compass.js;
  • offsets 为可选参数,用于直接载入此前校准得到的偏移量,避免每次上电都重新校准(详见下一节);
  • calibrated 事件在自动校准完成时触发一次,回调参数包含 X/Y/Z 三轴各自的 [low, high] 区间,可直接复制回 offsets;
  • change 事件在航向角发生变化时触发,示例在此打印 bearing 与 heading。

四、校准机制与 offsets 参数详解

1. 自动校准流程(源码级)

MAG3110 控制器在 lib/compass.js 的 initialize 中实现了完整的自动校准流程:

  1. 初始化状态:state.isCalibrated = false、state.measurements = 20,即默认采集 20 次测量后完成校准(见 lib/compass.js);
  2. 每次读到新数据后,若尚未校准,则用 Math.min / Math.max 持续更新 X/Y/Z 三轴各自的 low 与 high 极值,并用 (low + high) / 2 计算 offset(见 lib/compass.js);
  3. 采集满 state.measurements 次后置 isCalibrated = true;
  4. 校准完成后,将三轴 offset 按 MAG3110 数据手册要求的高 8 位 / 低 8 位拆分写入 OFFSETS(0x09)寄存器组(见 lib/compass.js),并通过 i2cWrite 下发;
  5. 触发 calibrated 事件,事件参数为三轴各自的 <a href="https://link.gitcode.com/i/cd3c5ee8d90b2dfec36011018b9050d4" target="_blank">low, high] 区间(见 [lib/compass.js)。

2. offsets 预载入

文档示例中的 offsets 就是一次真实校准的输出:

offsets: {
  x: [-819, -335],
  y: [702, 1182],
  z: [-293, -13],
},

当传入 offsets 时,源码会设置 isCalibrated = true 且 isPreCalibrated = true,跳过自动校准等待过程,直接以 (low + high) / 2 计算三轴 offset 并用于航向计算(见 lib/compass.js)。同时源码也兼容 offsets 以数组形式传入(依次对应 x、y、z),会自动转换为对象形式(见 lib/compass.js)。

推荐工作流是:首次运行时不做任何配置,让模块自动校准并把 calibrated 事件打印出的区间值固化到代码的 offsets 中,后续每次上电即可直接获得稳定航向。

3. 手动触发重新校准

控制器还提供了 calibrate(measurements) 方法:将 isCalibrated 置回 false 并重置采样次数,从而在运行时触发新一轮自动校准(见 lib/compass.js)。当传感器所处磁场环境发生变化(如靠近电机、磁铁)时,可以调用它重新校准。


五、航向计算原理

MAG3110 控制器的 toScaledHeading(见 lib/compass.js)是航向角计算的核心:

const scale = {
  x: 1 / (state.accum.x.high - state.accum.x.low),
  y: 1 / (state.accum.y.high - state.accum.y.low),
};

let heading = Math.atan2(-y * scale.y, x * scale.x);

if (heading < 0) {
  heading += TAU;
}

return Math.trunc(heading * RAD_TO_DEG);

要点:

  • 先利用校准得到的 X/Y 极值区间对原始读数做归一化(scale),消除两轴增益不一致带来的椭圆误差;
  • 再用 Math.atan2(-y, x) 计算方位角,负号用于适配磁力计的坐标方向约定;
  • 结果为负时加上 TAU(2π)折算到 0–360 范围,最后乘以 RAD_TO_DEG 并取整,得到以度为单位的整数航向。

底层 I²C 寄存器操作同样值得关注:初始化时控制器按数据手册 4.2.7 节“Setup Examples”写入 CTRL_REG2 = 0x80(启用自动磁传感器复位)与 CTRL_REG1 = 0x01(激活模式、80Hz ODR、OSR=1),见 lib/compass.js。随后通过轮询 DR_STATUS(0x00)寄存器,仅在 0x0F(完整新数据就绪)或 0xFF(所有轴均为新写入数据)时读取 6 字节原始数据(X、Y、Z 各 16 位有符号数),并以 80Hz 的周期(1000 / 80 ms)继续循环读取(见 lib/compass.js)。


六、事件与属性速查

Compass 组件的事件与属性在 lib/compass.js 中定义,针对 MAG3110 场景总结如下:

名称 类型 触发/返回内容 源码位置
calibrated 事件 自动校准完成,参数为 {x:<a href="https://link.gitcode.com/i/818e654eed503fd36744a0264f074ff9" target="_blank">low,high], y:[low,high], z:[low,high]} [lib/compass.js
data 事件 每个 freq 周期触发一次,参数含 {heading} lib/compass.js
change 事件 航向角发生变化时触发,参数含 {heading} lib/compass.js
heading 只读属性 0–360 的整数航向角 lib/compass.js
bearing 只读属性 方位对象(name/abbr/low/high/heading) lib/compass.js
raw 只读属性 {x, y, z} 原始读数 lib/compass.js
calibrate(n) 方法 重新校准,指定采样次数 n lib/compass.js

关于 freq:构造函数中 const freq = opts.freq || 25;(见 lib/compass.js),即事件轮询周期默认为 25ms。校准完成前的原始数据不会被下发到 dataHandler(见 lib/compass.js 中“仅在校准完成后才 dataHandler(measured)”的分支),因此 data/change 事件在校准完成前不会产生有效航向。


七、验证与测试

仓库为 MAG3110 控制器提供了完整的单元测试,位于 test/compass.js,覆盖以下行为:

  • shape:验证实例具备 bearing、heading、raw 三个属性(见 test/compass.js);
  • fwdOptionsToi2cConfig:验证 address 与 bus 选项正确转发到 i2cConfig,且控制器强制使用 0x0E 地址(见 test/compass.js);
  • data:模拟 DR_STATUS 就绪与一组真实原始数据(<a href="https://link.gitcode.com/i/4d32c36bbc7f08bd57a2a6ccdf1fa31f" target="_blank">0, 153, 255, 247, 0, 102],即 x: 153, y: -9, z: 102),断言 heading === 3、raw 正确解析(见 [test/compass.js);
  • change:模拟两组连续数据,断言 change 事件按航向变化触发两次,且 bearing 与 Compass.Points 中对应方位点一致(见 test/compass.js)。

这些测试以真实输出数据为输入,验证了从原始字节到航向、方位计算的整条链路,可作为理解本文示例输出格式的直接参考。


八、小结

在 Tessel 2 上使用 Johnny-Five 驱动 MAG3110 指南针,核心步骤可以概括为:按面包板图接线 → 安装 tessel-io 与 johnny-five → 以 controller: "MAG3110" 创建 Compass 实例 → 监听 calibrated 事件固化偏移 → 监听 change/data 事件消费航向与方位数据。底层由 lib/compass.js 完成寄存器初始化、状态轮询、自动校准与航向换算,开发者无需关心 I²C 细节。如需在 Arduino 等其他平台上使用相同传感器,可参考同目录下的 docs/compass-MAG3110.md 与 eg/compass-MAG3110.js。

登录后查看全文
johnny-five