Johnny-Five 驱动 Tessel 2 + Grove RGB LCD(JHD1313M1)实战指南
Johnny-Five 驱动 Tessel 2 + Grove RGB LCD(JHD1313M1)实战指南
本文以 Johnny-Five 仓库中的 docs/lcd-rgb-tessel-grove-JHD1313M1.md 为骨架,讲解如何在 Tessel 2 上通过 I2C 总线驱动 Seeed Studio Grove RGB LCD(控制器芯片 JHD1313M1):从接线准备、环境搭建、完整可运行示例,到 lib/lcd.js 中 JHD1313M1 控制器的底层实现原理。读完本文,你将掌握使用 Johnny-Five 的 five.LCD 模块完成字符显示、光标定位与 RGB 背光变色,并能理解其背后的 I2C 寄存器协议。
一、方案概览:Tessel 2 + Grove RGB LCD
Grove RGB LCD 是 Seeed Studio 出品的 16×2 字符型液晶屏,板载 JHD1313M1 控制器。它与普通 HD44780 兼容 LCD 的关键差异在于:显示与背光分别挂在两条 I2C 地址上,不需要占用 GPIO 数据引脚,非常适合 Tessel 2 这类以 I2C 为主要扩展方式的板卡。
从 lib/lcd.js 的 JHD1313M1 控制器实现可以看到两个固定地址:
- LCD 显示控制器:
0x3E(可通过options.address覆盖,见this.address.lcd = options.address || 0x3E); - RGB 背光控制器:
0x62(固定值)。
Tessel 2 侧通过 tessel-io 插件接入 Johnny-Five 的 Board,从而实现「硬件 IO 插件 + Johnny-Five 组件库」的标准组合模式。
二、接线与硬件准备
Grove 生态使用标准 4 线 Grove 接口,RGB LCD 模块与 Tessel 2 的连接方式为:
| Grove RGB LCD 引脚 | 连接目标 |
|---|---|
| VCC | Tessel 2 的 3.3V 电源引脚 |
| GND | Tessel 2 的 GND |
| SCL | Tessel 2 的 I2C 时钟引脚 |
| SDA | Tessel 2 的 I2C 数据引脚 |
原文档附带了该方案的接线示意图与 Fritzing 工程文件,可在仓库的 docs/breadboard/ 目录中查找 lcd-rgb-tessel-grove-JHD1313M1 对应的 .png 与 .fzz 文件作为实物接线参考。由于模块内部已集成 I2C 上拉电阻与电平转换,通常无需额外外接元件。
三、环境搭建与依赖
示例程序运行在 Tessel 2 的 Node.js 环境中,需要两个核心依赖:
- johnny-five:机器人/物联网编程框架,提供
Board、LCD等组件抽象; - tessel-io:Tessel 2 的 Johnny-Five IO 插件,负责把 Johnny-Five 的抽象 API 翻译成 Tessel 2 的硬件操作。
安装方式:
npm install johnny-five tessel-io
将 Tessel 2 通过 USB 连接开发机后,即可将本项目中的示例直接部署运行。
四、完整示例:Hello World + 红色背光
以下是原文档提供的核心示例(与仓库中的 eg/lcd-rgb-tessel-grove-JHD1313M1.js 一致):
var five = require("johnny-five");
var Tessel = require("tessel-io");
var board = new five.Board({
io: new Tessel()
});
board.on("ready", function() {
var lcd = new five.LCD({
controller: "JHD1313M1"
});
lcd.bgColor("#ff0000");
lcd.cursor(0, 0).print("Hello");
lcd.cursor(1, 0).print("World!");
});
从命令行运行:
node eg/lcd-rgb-tessel-grove-JHD1313M1.js
代码逐段拆解
- 创建 Board 并注入 IO 插件:
new five.Board({ io: new Tessel() })告知 Johnny-Five 使用 Tessel 2 作为物理平台,这是所有 Johnny-Five 程序在非 Arduino 硬件上运行的标准写法; - 等待板卡就绪:
board.on("ready", ...)回调在所有底层 IO 初始化完成后触发; - 实例化 LCD:仅需声明
controller: "JHD1313M1",无需指定引脚——因为该控制器完全通过 I2C 通信,Johnny-Five 会为它自动配置 I2C 总线; - 设置背光颜色:
lcd.bgColor("#ff0000")将背光置为纯红; - 定位并输出文本:
cursor(0, 0)定位到第 0 行第 0 列打印Hello,cursor(1, 0)定位到第 1 行第 0 列打印World!。
五、JHD1313M1 控制器源码级解析
5.1 双地址 I2C 初始化
lib/lcd.js 中的 initialize 方法展示了初始化过程:
// LCD: 0x3E
// RGB: 0x62
this.address = {
lcd: options.address || 0x3E,
rgb: 0x62
};
options.address = this.address;
this.io.i2cConfig(options);
this.lines = options.lines || 2;
this.rows = options.rows || 2;
this.cols = options.cols || 16;
this.dots = options.dots || "5x8";
可以看到:
- 默认显示尺寸为 2 行 × 16 列,字符点阵为 5×8,可通过
lines、rows、cols、dots选项覆盖; i2cConfig(options)会把上面的地址配置注册到底层 IO 插件,之后所有读写都通过this.io.i2cWrite()完成。
初始化时序中有一段阻塞式等待:根据 JHD1313M1 数据手册,电源电压超过 2.7V 后需要至少 40ms 才能安全发送命令,因此源码在发送功能设置命令前先 sleep(50),随后连续发送 3 次 DIMENSIONS | LINE[2](即 2 行模式的功能设置指令),再设置 Entry Mode、开启显示、清屏并回到原点(见 lib/lcd.js#L198-L225)。这段逻辑与 Grove 官方库保持一致,注释也明确指出“SEE PAGE 45/46 FOR INITIALIZATION SPECIFICATION!”。
5.2 背光颜色如何写入:bgColor 的寄存器协议
bgColor 是 JHD1313M1 控制器区别于普通 LCD 的核心能力。其实现位于 lib/lcd.js:
bgColor: {
value(red, green, blue) {
const rgb = RGB.ToRGB(red, green, blue);
const address = this.address.rgb;
this.io.i2cWrite(address, [0x00, 0]);
this.io.i2cWrite(address, [0x01, 0]);
// TRY THIS IN ONE CALL!
this.io.i2cWrite(address, [0x04, rgb.red]);
this.io.i2cWrite(address, [0x03, rgb.green]);
this.io.i2cWrite(address, [0x02, rgb.blue]);
return this;
}
}
底层协议非常直观:
0x00寄存器写0用于解除背光控制的寄存器选择模式;0x01寄存器写0同理;- 随后分别向寄存器
0x04、0x03、0x02写入 Red / Green / Blue 三个通道的 0~255 亮度值。
这样设计的好处是支持任意 24 位颜色,而不是只能切换几种预设色。
5.3 颜色解析:RGB.ToRGB
bgColor 参数会先经 lib/led/rgb.js 的 RGB.ToRGB 统一解析为 { red, green, blue }。它支持多种输入格式,这意味着你的 bgColor 调用可以非常灵活:
| 输入格式 | 示例 | 说明 |
|---|---|---|
| 十六进制字符串 | "#ff0000" 或 "ff0000" |
最常见的写法 |
| CSS 颜色名 | "red"、"yellow"、"hotpink" |
通过 color-convert 的 keyword.rgb() 解析 |
rgb()/rgba() |
"rgb(255, 0, 0)"、"rgba(255,0,0,0.5)" |
支持百分比值与透明度换算 |
| 对象 | { red: 255, green: 0, blue: 0 } |
直接传三通道数值 |
| 数组 | [255, 0, 0] |
数组顺序为 [R, G, B] |
| 三参数 | bgColor(255, 0, 0) |
分离的红绿蓝数值 |
例如以下写法等价于示例中的 "#ff0000":
lcd.bgColor(255, 0, 0); // 三参数
lcd.bgColor([255, 0, 0]); // 数组
lcd.bgColor("red"); // CSS 颜色名
lcd.bgColor("rgb(255, 0, 0)"); // rgb() 字符串
5.4 背光开关:bgOn / bgOff
lib/lcd.js 提供了背光开关控制:
bgOn: {
value() {
this.io.i2cWrite(this.address.rgb, [this.REGISTER.BACKLIGHT_ON, 0xAA]);
return this;
}
},
bgOff: {
value() {
this.io.i2cWrite(this.address.rgb, [this.REGISTER.BACKLIGHT_ON, 0x00]);
return this;
}
}
向背光控制器的 BACKLIGHT_ON(0x08)寄存器写入 0xAA 开启背光、写入 0x00 关闭背光。值得注意的是,initialize 流程在完成显示初始化后会先调用 bgOn(),再根据是否传入 color 选项决定调用 bgColor(指定色) 还是默认 bgColor("black")(见 lib/lcd.js#L231-L237)——即默认背光为黑色(关闭),需要显示效果必须显式设置颜色。
5.5 显示控制:clear、setCursor、print
JHD1313M1 控制器的清屏、光标与打印实现如下(lib/lcd.js#L240-L318):
clear: {
value() {
return this.command(this.REGISTER.CLEAR); // 0x01
}
},
setCursor: {
value(col, row) {
return this.command(row === 0 ? col | 0x80 : col | 0xc0);
}
}
clear()向 LCD 发送0x01指令,清空全部字符并复位光标;setCursor(col, row)通过设置 DDRAM 地址定位光标:第 0 行基地址0x80,第 1 行基地址0xC0(16×2 显示器的两行 DDRAM 起始地址)。
print 则在更上层的 LCD.prototype.print 中实现(lib/lcd.js#L852-L891):逐字符调用 command(DATA, charCode) 写入字符码,同时支持 :heart: 这类自定义字符替换语法(匹配正则 /:\w+:/)。示例中的 lcd.cursor(0, 0).print("Hello") 之所以可以链式调用,是因为这些方法都返回 this。
六、进阶实战:自动循环预览全色域
仓库中的 eg/lcd-rgb-bgcolor-previewer-tessel.js 展示了同一控制器下的进阶玩法——遍历 css-color-names 包中全部颜色名,每秒切换一次背光并同步打印颜色名,实现一个「颜色预览器」:
var five = require("../");
var Tessel = require("tessel-io");
var board = new five.Board({
io: new Tessel()
});
var colors = Object.keys(require("css-color-names"));
board.on("ready", () => {
var lcd = new five.LCD({
controller: "JHD1313M1"
});
lcd.bgColor("yellow");
var interval = null;
var index = 0;
board.repl.inject({
preview() {
if (interval) {
clearInterval(interval);
index = 0;
}
interval = setInterval(() => {
if (index === colors.length) {
clearInterval(interval);
return;
}
var color = colors[index++];
lcd.bgColor(color).cursor(0, 0).clear().print(color);
}, 1000);
}
});
});
这个示例引入了两个值得掌握的技巧:
- REPL 注入:通过
board.repl.inject({ preview })把preview函数注入 Johnny-Five 提供的交互式 REPL,程序运行后可直接在终端输入preview()触发循环,无需重启程序; - 方法链式调用:
lcd.bgColor(color).cursor(0, 0).clear().print(color)一次完成变色、定位、清屏、打印四个操作,充分体现了 Johnny-Five LCD 组件「一切方法返回实例本身」的设计。
同时它验证了 5.3 节的结论:bgColor 可以直接接收 CSS 颜色名——bgColor("yellow") 会被 RGB.ToRGB 正确解析为 { red: 255, green: 255, blue: 0 }。
七、运行与调试要点
- 运行方式:示例既可放在本地工程中通过
node执行,也可以把代码部署到 Tessel 2 的运行时上;Johnny-Five 在board.on("ready")之前不会触碰硬件,便于提前发现接线问题; - 背光默认黑色:若不显式调用
bgColor(),背光处于关闭状态(初始化默认bgColor("black")),但显示内容依然可见于对比度较高的面板上; - I2C 地址冲突:LCD 使用
0x3E、背光使用0x62,若总线上有其他设备占用相同地址需排查;LCD 地址可通过new five.LCD({ controller: "JHD1313M1", address: 0x3E })显式指定; - 维度选项:默认 2 行 16 列、5×8 点阵,如需其他规格可传入
rows、cols、lines、dots选项(参见 docs/lcd.md 中关于并行 LCD 的选项说明,选项体系与 JHD1313M1 一致)。
八、总结
Tessel 2 + Grove RGB LCD(JHD1313M1)是 Johnny-Five 生态中「IO 插件 + 组件库」协作模式的典型样例:tessel-io 屏蔽硬件差异,five.LCD 的 JHD1313M1 控制器封装了双地址 I2C 协议——显示走 0x3E、背光走 0x62。通过 bgColor 的寄存器写入与 RGB.ToRGB 的灵活颜色解析,开发者可以用一行代码实现任意背光颜色;结合 cursor、print、clear 等链式 API,可快速构建信息展示类物联网应用。本文所有代码均可直接从仓库的 eg/ 目录取用,源码细节可继续深入阅读 lib/lcd.js 与 lib/led/rgb.js。