Johnny-Five 使用指南:用 Sensor 读取 TinkerKit Linear Potentiometer 线性电位器
Johnny-Five 使用指南:用 Sensor 读取 TinkerKit Linear Potentiometer 线性电位器
导读
本文基于 Johnny-Five(JavaScript Robotics and IoT 编程框架)仓库中的 tinkerkit-linear-pot.md 示例文档,系统讲解如何通过 Sensor 组件读取 TinkerKit 线性电位器(Linear Potentiometer,又称滑动电位器)的模拟量输出。读完本文你将掌握:TinkerKit 引脚命名(I0)到 Arduino 模拟引脚的自动映射机制、Sensor 的 .scale() 与 data/change 事件用法、ADC 采样分辨率与中位数噪声过滤的实现原理,并能直接运行 eg/tinkerkit-linear-pot.js 在终端实时观测电位器位置数据。
一、示例总览:线性电位器输出 0~255 的滑动位置
原文档给出了一段可以直接从命令行运行的最小可执行示例,代码保存在 eg/tinkerkit-linear-pot.js:
node eg/tinkerkit-linear-pot.js
var five = require("johnny-five");
var board = new five.Board();
board.on("ready", function() {
new five.Sensor("I0").scale(0, 255).on("data", function() {
console.log(Math.round(this.value));
});
});
该示例的逻辑链路非常清晰:
- 创建
five.Board(),等待开发板ready事件(此时 Firmata 固件已完成握手); - 在模拟输入引脚
I0上实例化一个Sensor; - 调用
.scale(0, 255)将原始 ADC 读数映射到 0~255 区间; - 监听
data事件,把经过缩放(scale)后的this.value取整后打印到终端。
运行后,当你来回滑动 TinkerKit 线性电位器的推杆时,终端会连续输出 0~255 之间的整数,直观反映推杆当前位置。
二、TinkerKit 引脚命名与 "I0" 的自动映射
示例中的 "I0" 并非 Arduino 原生引脚编号,而是 TinkerKit Shield 的标准化接口命名。Johnny-Five 在 lib/board.pins.js 中内置了专门针对 TinkerKit 的引脚翻译表:
- 输入引脚 I0~I5:映射到模拟引脚
A0~A5(在 UNO 与 MEGA 上一致,LEONARDO 复用 UNO 映射); - 输出引脚 O0~O5:映射到数字 PWM 引脚(如 O0→11、O1→10、O2→9、O3→6、O4→5、O5→3);
- 数字引脚 D2/D4/D7/D8/D12/D13:映射到对应数字引脚。
以 UNO 为例,Pins.translations.UNO.tinker 定义如下:
tinker: {
I0: "A0", I1: "A1", I2: "A2", I3: "A3", I4: "A4", I5: "A5",
O0: 11, O1: 10, O2: 9, O3: 6, O4: 5, O5: 3,
D13: 13, D12: 12, D8: 8, D7: 7, D4: 4, D2: 2
}
因此当 Board.Options 处理构造函数参数时,"I0" 会被 Pins.translate() 解析为 "A0",随后由 Pins.fromAnalog() 进一步转换为模拟引脚索引。这意味着只要把 TinkerKit 线性电位器接到 TinkerKit Shield 的任一输入口(I0~I5),并把 Shield 插到 Arduino 上,你都可以用 Ix 直接指代对应模拟输入,无需关心底层引脚编号。使用 MEGA 时输入口扩展为 I0~I9(对应 A0~A9)。
三、Sensor 组件的核心配置与事件机制
Sensor 是 Johnny-Five 中读取模拟/数字传感器信号的通用组件,实现在 lib/sensor.js。结合线性电位器这一应用场景,其核心机制如下。
3.1 引脚模式与采样分辨率
构造时默认以 analog 类型处理(lib/sensor.js),并将引脚设置为 io.MODES.ANALOG 输入模式(lib/sensor.js)。ADC 分辨率默认按 10 位处理,即 resolution = 0x3FF(1023,对应 Arduino UNO/MEGA 的 AVR ADC);如果底层 I/O 实例声明了不同的 io.RESOLUTION.ADC,则以该值为准(lib/sensor.js)。因此不调用 .scale() 时,Sensor 的原始读数范围是 0~1023。
3.2 freq 采样间隔与中位数噪声过滤
Sensor 通过定时器周期性批量处理累积的采样值,间隔由 freq(默认 25ms)控制(lib/sensor.js)。对模拟信号,每次触发时会对周期内累积的原始读数做中位数过滤再发出事件(lib/sensor.js),以显著抑制电位器等模拟信号源的电气噪声——这正是示例中电位器读数能保持平滑的直接原因。
3.3 data / change 事件
data:每个采样周期都会触发,携带当前滤波后的读数(示例中即缩放后的 0~255 值);change:仅当新读数与上一次change值之差达到阈值(threshold,默认 1)时才触发(lib/sensor.js),适合只关心“位置发生变化”的场景。
示例使用 data 连续输出,若要改为仅在推杆移动时输出,可将 "data" 换成 "change"。
3.4 scale() 与 value 的缩放语义
.scale(low, high) 设置缩放目标区间并返回实例本身以支持链式调用(lib/sensor.js):
sensor.scale(0, 180); // 电位器 → 0~180(常见于驱动舵机角度)
sensor.scale([0, 255]); // 也支持传入数组形式
设置缩放后,this.value 即返回按输入范围 this.range(默认 <a href="https://link.gitcode.com/i/a1dc298d4633e3bf38749783bf7c6e3f" target="_blank">0, resolution],即 0~1023)线性映射到目标区间的结果([lib/sensor.js)。映射逻辑使用 lib/fn.js 中的 Fn.map(仿 Arduino map() 的整数映射),并配合 Fn.constrain 将结果钳制在目标范围内(lib/sensor.js)。因此示例中 .scale(0, 255) 的含义是:推杆处于一端时输出 0,处于另一端时输出 255,中间位置线性对应。
除 .scale() 外,Sensor 还提供 scaleTo(low, high)(整数映射)与 fscaleTo(low, high)(Float32 精度映射)两个即时计算缩放方法(lib/sensor.js),以及 boolean、constrained、analog、raw 等只读属性,方便在不同场景下取值。
四、深入示例:把线性电位器变成滑动控制器
线性电位器的典型用途是充当“滑动控制器”,将物理推杆位置映射为亮度、音量或舵机角度。以下是将 I0 电位器直接驱动 O0 舵机的变体(思路参见同类 TinkerKit 示例 tinkerkit-rotary.md 与 tinkerkit-combo.md):
var five = require("johnny-five");
var board = new five.Board();
board.on("ready", function() {
var servo = new five.Servo("O0");
new five.Sensor("I0").scale(0, 180).on("change", function() {
servo.to(this.value);
});
});
要点拆解:
- 输入用
Sensor("I0"),输出用Servo("O0"),两个 TinkerKit 口在 lib/board.pins.js 中分别翻译为A0与数字引脚 11(PWM 引脚,Servo需要 PWM 能力); .scale(0, 180)把 0~1023 的原始 ADC 读数映射为舵机角度区间 0°~180°;- 改用
change事件,避免推杆静止时反复写入舵机。
五、接线实物与运行验证
下图是本示例对应的 TinkerKit 线性电位器模块实物(红色 PCB 上的滑动变阻器,推杆移动改变输出模拟电压,配合 TinkerKit Shield 即可接入 Arduino):
运行前请确认:
- Arduino 已烧录 StandardFirmata 固件并连接 USB;
- TinkerKit Shield 已正确插在 Arduino 上;
- 线性电位器模块插入 Shield 的任一输入口(示例默认 I0);
- 在仓库根目录执行
node eg/tinkerkit-linear-pot.js。
如果使用 MEGA 或 LEONARDO,其 TinkerKit 引脚映射同样被内置支持(LEONARDO 复用 UNO 映射,见 lib/board.pins.js)。示例仅依赖 Sensor 与 Board 两个公开 API,也可作为验证开发板与 Johnny-Five 通信是否正常的冒烟测试。仓库测试(如 test/board.js 中的 Sensor 用例)验证了多路模拟 Sensor 的实例化与数据流,可参考 test/board.js 了解 Sensor 在整板层面的行为。
六、小结
通过 docs/tinkerkit-linear-pot.md 这份文档与 eg/tinkerkit-linear-pot.js 示例,可以总结出读取 TinkerKit 线性电位器的完整套路:TinkerKit 引脚自动翻译(I0→A0)→ Sensor 模拟采样与中位数滤波 → .scale() 区间映射 → data/change 事件消费数据。这一模式可推广到全部 TinkerKit 模拟输入模块(旋转电位器、光敏电阻、摇杆等,参见 docs 目录下其余 tinkerkit-*.md 文档),是 Johnny-Five 中处理模拟量输入的通用基本功。
