Johnny-Five 驱动 Tessel 2 + Grove RGB LCD(JHD1313M1)实战指南

原创2026-09-22 10:47:361,644 阅读
文章标签:IoT机器人嵌入式

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 环境中,需要两个核心依赖:

  1. johnny-five:机器人/物联网编程框架,提供 Board、LCD 等组件抽象;
  2. 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

代码逐段拆解

  1. 创建 Board 并注入 IO 插件:new five.Board({ io: new Tessel() }) 告知 Johnny-Five 使用 Tessel 2 作为物理平台,这是所有 Johnny-Five 程序在非 Arduino 硬件上运行的标准写法;
  2. 等待板卡就绪:board.on("ready", ...) 回调在所有底层 IO 初始化完成后触发;
  3. 实例化 LCD:仅需声明 controller: "JHD1313M1",无需指定引脚——因为该控制器完全通过 I2C 通信,Johnny-Five 会为它自动配置 I2C 总线;
  4. 设置背光颜色:lcd.bgColor("#ff0000") 将背光置为纯红;
  5. 定位并输出文本: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);
    }
  });
});

这个示例引入了两个值得掌握的技巧:

  1. REPL 注入:通过 board.repl.inject({ preview }) 把 preview 函数注入 Johnny-Five 提供的交互式 REPL,程序运行后可直接在终端输入 preview() 触发循环,无需重启程序;
  2. 方法链式调用: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。

登录后查看全文
johnny-five