Johnny-Five 驱动 HT16K33 16x8 LED 矩阵:Led.Matrix 点阵绘图与动画实战

原创2026-09-22 12:59:391,861 阅读
文章标签:IoT机器人嵌入式

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 工程文件:

HT16K33 16x8 LED 矩阵面包板接线图

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):

  1. 只传一个参数时,遍历所有设备依次绘制(支持多块矩阵同步刷新);
  2. 若传入的是数组,直接当作帧数据;若传入的是字符串字符,则从内置字模表 ledCharacters.MATRIX_CHARS 查表(lib/led/led-chars.js 起定义了空格、标点、数字、字母等 8 行字模,另外 lib/led/ledcontrol.js 还动态生成了 00–99 的两位数组合字模);
  3. 校验帧长度必须等于 rows 或 columns,长度不足时用 0 补齐到 rows;
  4. 逐行调用 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 设备上。

登录后查看全文
johnny-five