Johnny-Five 驱动 HT16K33 16x8 LED 矩阵:Led.Matrix 点阵绘图与动画实战
Johnny-Five 驱动 HT16K33 16x8 LED 矩阵:Led.Matrix 点阵绘图与动画实战
本篇指南基于 led-matrix-HT16K33-16x8.md 展开,讲解如何在 Johnny-Five 中通过 I2C 总线驱动 Adafruit HT16K33 驱动的 16x8 LED 矩阵模块,实现自定义点阵图形绘制与逐帧动画。读完本文,你将掌握 five.Led.Matrix 的 controller: "HT16K33" 配置、dims 与 rotation 参数语义、二进制字符串点阵数据的编码方式,以及如何利用内置 REPL 交互式地切换画面。
示例速览:运行一只会眨眼的"眼睛"
Johnny-Five 仓库中与本篇文档配套的可运行示例位于 eg/led-matrix-HT16K33-16x8.js,在硬件接好后,直接在命令行执行:
node eg/led-matrix-HT16K33-16x8.js
该示例会先在 16x8 点阵上绘制一双"睁开的眼睛",随后你可以在 REPL 中调用注入的 wink() 函数,让右眼闭合 500ms 后再睁开,形成眨眼动画。
模块的接线方式可参考仓库中随文档提供的面包板接线图与 Fritzing 工程文件:
Fritzing 电路图源文件:docs/breadboard/led-matrix-HT16K33-16x8.fzz
HT16K33 通过 I2C 通信,只需将模块的 SDA、SCL 分别接到开发板的 I2C 数据/时钟引脚,并接好 VCC 与 GND;I2C 地址默认由板载跳线/焊接点决定(详见下文"地址"一节)。
完整代码与逐段解析
原文档给出的示例完整代码如下,先整体把握再逐段拆解:
var five = require("johnny-five");
var board = new five.Board();
board.on("ready", function() {
var open = [
"0000000000000000",
"0011110000111100",
"0100001001000010",
"1001100110011001",
"1001100110011001",
"0100001001000010",
"0011110000111100",
"0000000000000000",
];
var wink = [
"0000000000000000",
"0011110000000000",
"0100001000000000",
"1001100111111111",
"1001100111111111",
"0100001000000000",
"0011110000000000",
"0000000000000000",
];
var matrix = new five.Led.Matrix({
addresses: [0x70],
controller: "HT16K33",
dims: "8x16",
rotation: 2
});
matrix.draw(open);
this.repl.inject({
wink: function() {
matrix.draw(wink);
setTimeout(function() {
matrix.draw(open);
}, 500);
}
});
});
点阵帧数据:一行一行的二进制字符串
open 和 wink 是两个 8 元素数组,每个元素是长度为 16 的 "0"/"1" 字符串,整体构成一帧 8 行 × 16 列的位图:
- 数组下标对应行号(0 到 7,自上而下);
- 字符串中的每一位对应该行某一列的点,
"1"点亮、"0"熄灭; - 每一帧共有
8 × 16 = 128个可独立控制的点。
对照画面可以直观理解:open 帧把 16 列平均分成左右两半,用 00111100(左半)与 00111100(右半)等行数据拼出两只"睁开的眼睛",瞳孔位置是 10011001;而 wink 帧把右半部分基本清零,仅保留中间两行的 11111111,模拟右眼闭合为一条水平亮线——这正是 500ms 后恢复的眨眼效果。
绘制只需一行调用:
matrix.draw(open);
draw() 是 Led.Matrix 的核心方法,在矩阵模式下它接受一个行数组(如上面的 open/wink),把每一行的 16 位数据逐列写入控制器(底层实现见后文"draw 的分发路径")。
构造函数参数说明
示例中 Led.Matrix 的配置项共四个,各自含义如下:
| 参数 | 示例值 | 说明 |
|---|---|---|
addresses |
<a href="https://link.gitcode.com/i/603a3f131fa68fb206e9e58d906c1bf1" target="_blank">0x70] |
HT16K33 的 I2C 地址列表,支持同时挂载多块模块(见 [lib/led/ledcontrol.js 中地址池的定义)。可用地址为 0x70~0x77,每实例化一个矩阵控制器,对应的地址会从可用池中扣除;若不传,则按 devices 数量从 0x70 起自动分配 |
controller |
"HT16K33" |
指定 LED 控制芯片为 HT16K33,启用其专属的 I2C 初始化与指令集(SHUTDOWN: 0x20、BRIGHTNESS: 0xE0、BLINK: 0x80)。缺省时走 MAX7219/MAX7221 的 SPI 模式 |
dims |
"8x16" |
点阵尺寸,按 "行数 x 列数" 书写,"8x16" 即 8 行、16 列。注意文档/文件名中的"16x8"指的是硬件模块的标称(16 列宽、8 行高),两者是同一块屏 |
rotation |
2 |
画面旋转方向,0/1/2/3 分别对应 0°/90°/180°/270°。示例设为 2,即画面旋转 180°,用于适配模块的物理安装方向 |
四个参数的解析与校验逻辑都在 lib/led/ledcontrol.js 的构造函数与 HT16K33 控制器的 initialize 中完成,下面两节深入展开。
REPL 注入:交互式动画
this.repl.inject({ ... }) 把 wink 函数注入 Johnny-Five 自带的 REPL 环境,程序运行后即可在终端直接输入 wink() 触发动画:
this.repl.inject({
wink: function() {
matrix.draw(wink);
setTimeout(function() {
matrix.draw(open);
}, 500);
}
});
这演示了"双缓冲帧切换"的最小实现:先 draw(wink) 立即绘制闭合帧,再通过 setTimeout(..., 500) 在 500ms 后 draw(open) 恢复睁眼帧,两张静态帧交替即构成动画。repl.inject 同时支持注入 matrix 实例本身,方便在终端里直接调用 matrix.clear()、matrix.row(...) 等底层方法做调试。
dims 尺寸约定:为什么文件名是 16x8、代码却写 "8x16"
这是一个容易踩坑的点。dims 的取值必须以 "rows x columns"(行 x 列) 的顺序传入,仓库在 lib/led/ledcontrol.js 中定义了三种合法尺寸:
LedControl.MATRIX_DIMENSIONS = {
"16x8": { rows: 16, columns: 8 },
"8x16": { rows: 8, columns: 16 },
"8x8": { rows: 8, columns: 8 }
};
因此本文示例使用的 dims: "8x16" 表示 8 行、16 列——也就是硬件厂商口中那块"16x8"(16 列宽、8 行高)的 Adafruit 双 8x8 拼接矩阵。文件名 led-matrix-HT16K33-16x8.md 沿用了硬件命名,代码里的 dims 则是软件坐标约定,两者指同一块屏。
构造函数会对尺寸做合法性校验,不满足 columns ∈ {8, 16}、rows ∈ {8, 16} 且 columns + rows !== 32 的组合时直接抛出错误(lib/led/ledcontrol.js):
throw new Error("Invalid matrix dimensions specified: must be 8x8, 16x8 or 8x16");
尺寸还会进入实例的只读属性 rows / columns(通过 Object.defineProperties 暴露,见 lib/led/ledcontrol.js),后续 led()、row()、column()、draw() 等方法的行列边界判断全部依赖这两个值。测试用例 test/ledcontrol.js 对 "16x8" 与 "8x16" 的 rows/columns 均有断言,可作交叉验证。
rotation:坐标旋转的底层实现
rotation 决定 led(addr, row, col, state) 在写入硬件缓冲前如何变换坐标。从源码看,HT16K33 控制器的 initialize 中做了两件事(lib/led/ledcontrol.js):
this.rotation = options.rotation || 1;
// 16 列矩阵未显式指定 rotation 时,默认用 0
if (this.columns === 16 && !options.rotation) {
this.rotation = 0;
}
也就是说:默认值为 1;若你的矩阵有 16 列(如本文的 8x16)且未传 rotation,则自动退化为 0。led() 方法中对应四种变换(lib/led/ledcontrol.js):
rotation: 0:不旋转,直接映射;rotation: 1:交换行列并翻转 x,等效顺时针旋转 90°;rotation: 2:x = columns - x - 1; y = rows - y - 1,等效旋转 180°(本文示例所用);rotation: 3:交换行列并翻转 y,等效逆时针旋转 90°。
另外,单色 8x8 矩阵存在列环绕修正(x = (x + columns - 1) % columns,见 lib/led/ledcontrol.js),8x16 双宽矩阵不需要此修正。row() 方法在内部逐列调用 led(),因此旋转逻辑对 draw() 的整帧数据同样生效——当你发现画面方向不对时,调整 rotation 即可,无需改点阵数据。
底层原理:HT16K33 控制器如何工作
指令集与 I2C 通信
HT16K33 控制器定义了三组操作码(lib/led/ledcontrol.js):
| 操作 | 操作码 | 用途 |
|---|---|---|
SHUTDOWN |
0x20 |
上电/关屏(on()/off() 写入 1/0) |
BRIGHTNESS |
0xE0 |
亮度寄存器,brightness() 把用户输入的 0–100 映射到 0–15 级 |
BLINK |
0x80 |
闪烁控制,配合 ` |
其中 blink() 支持 false(关闭)、"slow"(2 秒一次)、"normal"(1 秒一次)、"fast"(500ms 一次),映射到 HT16K33 数据手册规定的寄存器值(见 lib/led/ledcontrol.js)。
所有寄存器操作最终通过 send() 走 I2C 写出:
this.io.i2cWrite(this.addresses[addr], [opcode | data]);
初始化阶段(initialize)会依次完成:注册 I2C 配置 → 点亮设备 → 关闭残留闪烁 → 亮度设为 100 → 清屏(lib/led/ledcontrol.js)。
显示缓冲与 writeDisplay
每个设备在内存中维护一份行缓冲 buffer<a href="https://link.gitcode.com/i/20c7834a189fdb9af9ea1eaeaa9d28d6" target="_blank">addr],led() 通过位运算置位/清零对应像素后立即调用 writeDisplay() 刷新([lib/led/ledcontrol.js):
writeDisplay(addr) {
const bytes = [0x00];
// 始终写 8 行:8x16 时行值已在 led() 中完成旋转
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);
}
每个像素点按"低字节 + 高字节"两字节写入,8 行共 16 字节,恰好对应 HT16K33 的显示 RAM 布局,这也是它能驱动 16 列宽矩阵(每行需要 16 bit)的原因。clear() 则把 memory 与 buffer 的行数据清零后调用 writeDisplay()(lib/led/ledcontrol.js)。
draw 的分发路径
draw() 是矩阵模式的总入口(lib/led/ledcontrol.js):
- 只传一个参数时,遍历所有设备依次绘制(支持多块矩阵同步刷新);
- 若传入的是数组,直接当作帧数据;若传入的是字符串字符,则从内置字模表
ledCharacters.MATRIX_CHARS查表(lib/led/led-chars.js 起定义了空格、标点、数字、字母等 8 行字模,另外 lib/led/ledcontrol.js 还动态生成了 00–99 的两位数组合字模); - 校验帧长度必须等于
rows或columns,长度不足时用0补齐到rows; - 逐行调用
row(addr, idx, rowData)写入。
row() 接受数值(0–255 或 0–65535)或二进制字符串,内部统一转成二进制后按位交给 led()(lib/led/ledcontrol.js)。column() 则提供整列写入能力(8 位或 16 位值,见 lib/led/ledcontrol.js)。Matrix 类本身很薄,只在构造时设置 options.isMatrix = true 并暴露 CHARS 静态属性(lib/led/matrix.js),全部能力继承自 LedControl,并通过 lib/led/index.js 挂载为 five.Led.Matrix。
测试佐证:从测试看行为契约
仓库测试文件 test/ledcontrol.js 对 HT16K33 矩阵行为给出了完整契约,可用来验证上文结论:
- I2C 地址:
addressSingle/addressesMultiple等用例断言addresses: <a href="https://link.gitcode.com/i/6425ef620420da8a56df36e9013bbd2f" target="_blank">0x70, 0x71]能正确透传,未指定时按devices数量从0x70起自动分配并消耗可用地址池([test/ledcontrol.js); - 尺寸解析:
matrix["8x16"]的rows === 8、columns === 16(test/ledcontrol.js); - 旋转:测试中直接设置
this.lc.rotation = 2/= 3后断言led()的位写入结果(test/ledcontrol.js); - 绘制:
drawStringArray、drawSingleChar、drawByteArray等用例验证数组帧、字符查表与字节数组三种绘制路径对row()的调用序列(test/ledcontrol.js)。
延伸阅读与常见问题
- 8x8 单块 HT16K33 矩阵:参见 led-matrix-HT16K33.md 与 eg/led-matrix-HT16K33.js,配置去掉了
dims(默认 8x8),rotation: 3,可对比单宽与双宽矩阵在帧数据长度上的差异; - MAX7219/7221 矩阵(SPI 三线驱动,默认控制器):参见 led-matrix.md 与 eg/led-matrix.js,它改用
pins: { data, clock, cs }配置,不使用addresses/dims/rotation,底层走board.shiftOut串行移位; - 常见问题:画面方向不对 → 调整
rotation;画面全灭/全亮 → 检查 I2C 地址是否与板载跳线一致(0x70–0x77可用池会被已实例化的矩阵占用);点阵帧错位 → 确认dims是"行 x 列"顺序,8 行宽的帧必须给 8 个字符串、每个字符串 16 位。
至此,你已经掌握了从接线、配置、点阵编码到底层 I2C 写入的完整链路,可以在此基础上自由扩展自己的动画帧(例如滚动文字、进度条、双 8x8 表情切换),并把同样的知识迁移到仓库内其他 HT16K33 驱动的 LED 设备上。
