Johnny-Five 驱动 HT16K33 LED 矩阵实战指南:8x8/8x16 点阵绘制与 I2C 控制
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,可直接参考进行物理接线:
接线完成后,确保主控板上已烧录支持 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 寄存器,opcode0x20);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() 即可看到眨眼动画。
相关文档与验证资源
- 通用矩阵示例(MAX7219 等默认控制器):docs/led-matrix.md
- 8x16 变体示例文档:docs/led-matrix-HT16K33-16x8.md
- 点阵入门教程:docs/led-matrix-tutorial.md
- 核心实现:lib/led/matrix.js、lib/led/ledcontrol.js
- 内置字模表:lib/led/led-chars.js
- 单元测试:test/ledcontrol.js(其中覆盖了 HT16K33 的单地址、多地址、
i2cConfig总线参数传递等场景,可作行为参考)
遵循以上步骤,你即可用 Johnny-Five 快速驱动 HT16K33 点阵屏:先按接线图完成 4 线 I2C 连接,再用 addresses + controller + rotation 实例化矩阵,最后用 draw() 传入二进制位图即可呈现自定义图案;结合 brightness、blink 与 REPL 注入,还能轻松扩展出动画、亮度渐变等交互效果。
