Johnny-Five 实战:在 Tessel 2 上驱动 MAG3110 三轴磁力计指南针(Compass 组件详解)
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 中的headinggetter 实时调用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,可用来精确核对引脚连接。
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 中实现了完整的自动校准流程:
- 初始化状态:
state.isCalibrated = false、state.measurements = 20,即默认采集 20 次测量后完成校准(见 lib/compass.js); - 每次读到新数据后,若尚未校准,则用
Math.min/Math.max持续更新 X/Y/Z 三轴各自的low与high极值,并用(low + high) / 2计算 offset(见 lib/compass.js); - 采集满
state.measurements次后置isCalibrated = true; - 校准完成后,将三轴 offset 按 MAG3110 数据手册要求的高 8 位 / 低 8 位拆分写入
OFFSETS(0x09)寄存器组(见 lib/compass.js),并通过i2cWrite下发; - 触发
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。
