Johnny-Five 驱动 HT16K33 LED 矩阵实战指南:8x8/8x16 点阵绘制与 I2C 控制

原创2026-09-22 14:09:591,813 阅读
文章标签:IoT机器人嵌入式

Johnny-Five 驱动 HT16K33 LED 矩阵实战指南:8x8/8x16 点阵绘制与 I2C 控制

HT16K33 是 Adafruit 等厂商常用的 I2C 接口 LED 驱动芯片,可驱动 8x8、8x16、16x8 点阵屏与 7 段数码管。本文以 Johnny-Five 官方文档 docs/led-matrix-HT16K33.md 为核心骨架,完整讲解在 Johnny-Five 框架下用 five.Led.Matrix 实例化 HT16K33 矩阵、通过二进制位图绘制图形(如心形)的完整流程,并深入 lib/led/ledcontrol.js 源码剖析地址管理、旋转(rotation)、亮度、闪烁等底层机制。读完本文,你将能独立接线并编写代码驱动 HT16K33 点阵屏显示任意自定义图形或字符。

硬件与接线准备

HT16K33 矩阵模块通过 I2C 总线与主控板通信,通常只需 4 根导线即可完成接线:

模块引脚 主控板(以 Arduino UNO 为例)
VCC 5V
GND GND
SDA A4(I2C 数据线)
SCL A5(I2C 时钟线)

官方为本文档配套了面包板接线示意图 docs/breadboard/led-matrix-HT16K33.png 与 Fritzing 源文件 docs/breadboard/led-matrix-HT16K33.fzz,可直接参考进行物理接线:

HT16K33 驱动的 8x8 LED 矩阵面包板接线示意图

接线完成后,确保主控板上已烧录支持 Firmata 的固件,即可通过 Johnny-Five 的 Board 对象访问 I2C 总线。

运行官方示例:点亮一颗心

原文档给出的完整示例位于 eg/led-matrix-HT16K33.js,在命令行中直接执行:

node eg/led-matrix-HT16K33.js

完整代码如下:

var five = require("johnny-five");
var board = new five.Board();

board.on("ready", function() {

  var heart = [
    "01100110",
    "10011001",
    "10000001",
    "10000001",
    "01000010",
    "00100100",
    "00011000",
    "00000000"
  ];

  var matrix = new five.Led.Matrix({
    addresses: [0x70],
    controller: "HT16K33",
    rotation: 3,
  });

  matrix.clear();
  matrix.draw(heart);
});

程序逻辑分三步:Board 就绪后,先以 controller: "HT16K33" 声明驱动芯片类型并指定 I2C 地址 0x70;然后 matrix.clear() 清空显示缓冲区;最后 matrix.draw(heart) 将心形位图刷入点阵。

位图数据格式:每行一个二进制串

heart 数组的 8 个字符串元素,恰好对应 8x8 点阵的 8 行。每个字符串是 8 个字符的二进制表示,1 表示该 LED 点亮,0 表示熄灭。例如第一行 "01100110" 表示心形顶部的两个凹陷。这也是所有矩阵绘制 API 的统一输入约定:行数由字符串数量决定,每行宽度由二进制串长度决定。

构造参数详解:地址、控制器与旋转

five.Led.Matrix 的 HT16K33 分支支持以下核心构造参数(对应 lib/led/ledcontrol.js 的 JSDoc 注释):

参数 类型 说明 默认值
controller String 驱动控制器,HT16K33 必须设为 "HT16K33" 默认(MAX7219 等)
address Number 单个 I2C 设备地址,如 0x70 无
addresses Array 多块矩阵的 I2C 地址数组 无
devices Number 连接的设备数量(用于推断地址个数) 由 addresses.length 决定
dims String 点阵尺寸:"8x8"、"8x16"、"16x8" "8x8"
rotation Number 显示旋转,取值 0/1/2/3 1(16 列矩阵为 0)
isBicolor Boolean 是否为双色矩阵 false

I2C 地址:0x70 ~ 0x77

HT16K33 的地址并非任意取值。源码在 lib/led/ledcontrol.js 处维护了一个合法地址集合:

let addresses = new Set([0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77]);

在初始化(lib/led/ledcontrol.js)时,如果传入了 addresses 或 address 会逐一校验,非法地址会直接抛出 Invalid HT16K33 controller address;未指定时则按 devices 数量从可用地址池中顺序分配。值得注意的是,已被占用的地址会从集合中移除,因此同一进程内多块矩阵可以自动避免地址冲突。

rotation:解决"方向不对"的关键

HT16K33 矩阵模块的物理方向与逻辑行列并不总是一致,rotation 参数负责坐标变换。源码 lib/led/ledcontrol.js 中 led() 方法对四种旋转值做了明确的坐标映射:

  • 0:不做旋转(16 列矩阵的默认值,适配 Adafruit 16x8 矩阵)
  • 1:交换行列并水平翻转(默认)
  • 2:水平与垂直同时翻转(180 度)
  • 3:交换行列并垂直翻转

本文示例选择 rotation: 3,正是为了把按"正上正下"方向设计的 heart 位图正确映射到实际矩阵的物理排布上。当显示内容出现镜像或颠倒时,调整此参数即可修正,无需重画位图。

核心 API:从清屏到位图绘制

clear():清空缓冲区

clear() 会把当前设备的内存与缓冲全部清零并立即刷新显示(lib/led/ledcontrol.js)。不带参数时作用于所有已连接设备,也可传入设备索引只清理单块。

draw():画数组或字符

draw() 是矩阵的核心方法,由基类 lib/led/ledcontrol.js 实现,支持两种入参:

1. 传位图数组(本文示例的用法)——数组的每个元素(如 "01100110")作为一整行交给 row() 方法逐列点亮。若数组行数与矩阵行数不一致,会抛出 Invalid character 错误。

2. 传单个字符——按字符从 lib/led/led-chars.js 预置的 MATRIX_CHARS 字模表中查找对应的 8 位行数据。该表内置了数字 0-9、大写/小写字母与常用标点(!、?、# 等)的完整字模,例如:

// 显示字母 H
matrix.draw("H");

这让你可以像操作文本一样驱动点阵。此外 Led.Matrix.CHARS 静态属性(lib/led/matrix.js)也暴露了同一字模表,便于自行扩展字符集。

设备级 API:on / off / brightness / blink

除绘制外,HT16K33 控制器还支持整屏控制:

  • on() / off():开关显示(对应芯片的 SHUTDOWN 寄存器,opcode 0x20);
  • brightness(value):亮度调节,源码 lib/led/ledcontrol.js 通过 Board.map(val, 0, 100, 0, 15) 把 0-100 的百分比映射为芯片的 0-15 级亮度,例如 matrix.brightness(50) 为半亮;
  • blink(mode):闪烁控制,见 lib/led/ledcontrol.js,支持 "slow"(每 2 秒一次)、"normal"(每秒一次)、"fast"(每 500ms 一次)与 false(关闭闪烁)。

初始化时(lib/led/ledcontrol.js),库会自动完成开机、关闭闪烁、设置 100% 亮度与清屏,因此你无需手动初始化即可直接绘制。

底层原理:缓冲区与 I2C 写屏

HT16K33 的显示数据并非逐 LED 发送,而是先写入内部缓冲区再整体刷新。writeDisplay()(lib/led/ledcontrol.js)会为每个设备构造 17 字节数据包——首字节 0x00 为起始地址,随后 8 行各取低 8 位和高 8 位(兼容 16 列点阵),一次 i2cWrite 完成整屏刷新:

writeDisplay: {
  value(addr) {
    const bytes = [0x00];
    for (let i = 0; i < 8; i++) {
      bytes.push(this.buffer[addr][i] & 0xFF);
      bytes.push(this.buffer[addr][i] >> 8);
    }
    this.io.i2cWrite(this.addresses[addr], bytes);
  },
},

这也解释了为什么连续调用 led(row, col, state)、row()、column() 等方法绘制大量点时依然流畅——所有修改都落在内存缓冲,最终一次性刷屏。

单点与行列控制

除整图绘制外,你还可以逐点操作:

  • matrix.led(row, col, state):控制单颗 LED 亮灭,支持 true/false 或 1/0;
  • matrix.row(row, value):用 8 位数值(0-255)或二进制字符串设置一整行;
  • matrix.column(col, value):类似地设置一整列。

draw() 的位图数组最终就是通过逐行调用 row() 落盘的。

进阶:8x16 与 16x8 矩阵与 REPL 交互

HT16K33 同样支持更宽的 8x16 点阵(如 Adafruit 1.2" 8x16 双色矩阵)。对应文档 docs/led-matrix-HT16K33-16x8.md 与示例 eg/led-matrix-HT16K33-16x8.js 展示了如何通过 dims 参数切换尺寸——注意此时每行二进制串为 16 位:

var matrix = new five.Led.Matrix({
  addresses: [0x70],
  controller: "HT16K33",
  dims: "8x16",
  rotation: 2
});

dims 支持 "8x8"、"8x16"、"16x8" 三种取值,映射关系定义在 lib/led/ledcontrol.js 的 MATRIX_DIMENSIONS 常量中;构造时若传入其他组合,会在 lib/led/ledcontrol.js 抛出 Invalid matrix dimensions specified。默认 "8x8",16 列矩阵未显式指定 rotation 时会自动设为 0。

该示例还演示了 Johnny-Five 的 REPL 注入技巧——把自定义函数注入交互式命令行,实现"睁眼/闭眼"动画切换:

this.repl.inject({
  wink: function() {
    matrix.draw(wink);
    setTimeout(function() {
      matrix.draw(open);
    }, 500);
  }
});

运行后脚本不会退出,在终端里输入 wink() 即可看到眨眼动画。

相关文档与验证资源

遵循以上步骤,你即可用 Johnny-Five 快速驱动 HT16K33 点阵屏:先按接线图完成 4 线 I2C 连接,再用 addresses + controller + rotation 实例化矩阵,最后用 draw() 传入二进制位图即可呈现自定义图案;结合 brightness、blink 与 REPL 注入,还能轻松扩展出动画、亮度渐变等交互效果。

登录后查看全文
johnny-five