文档版本历史

V1.0（2026-10-10）

开源初版文档，包含 RGB 矩阵灯模块 M（中号）灯板的开源说明，以及灯板识别与左右插入检测说明。

项目简介

RGB 矩阵灯模块 M（中号） 是为 ESP-Mosaico 主板设计的全彩 LED 灯板。灯板搭载 8 × 8 RGB LED 矩阵，共 64 个全彩像素，可以侧插在 ESP-Mosaico 主板的左侧或右侧，为设备增加炫酷灯效和 LED 点阵显示能力。

通过主板程序控制，灯板可用于氛围灯、像素动画、表情显示和状态反馈等创意应用。板载 EEPROM 保存灯板识别信息，主板可读取灯板类型、型号及版本，并判断左右安装位置。

本文介绍该灯板的功能、硬件参数、连接方式、识别原理、电路设计、开源软件及复刻调试方法。

灯板识别与左右插入检测

RGB 矩阵灯模块配备 EEPROM，保存灯板类型、型号 ID 和版本等信息。主板通过 I²C 读取这些数据，识别灯板并加载对应驱动，同时通过 EEPROM 的设备地址确定灯板插在主板左侧还是右侧。

主板通过 Board Type（类型码）与 Board ID（型号 ID）共同识别灯板。

左右插入检测通过 EEPROM 的 A0 地址引脚实现：A0 经 0Ω 电阻连接侧接口 GPIO，左侧对应 GPIO14，右侧对应 GPIO39，A1、A2 均接地。检测时，主板将 GPIO14 置为低电平、GPIO39 置为高电平，使灯板在左侧和右侧插入时具有不同的 I²C 地址。

AT24C02 的 7 位地址格式为 1010 A2 A1 A0。按上述连接与检测电平，地址对应如下：

安装位置	主板控制引脚	A0 电平	7 位 I²C 地址	含读写位的总线地址字节（写／读）
左侧	GPIO14	低（0）	0x50	0xA0／0xA1
右侧	GPIO39	高（1）	0x51	0xA2／0xA3

主板分别访问左侧的 0x50 和右侧的 0x51，读取有效的灯板描述数据，即可确认灯板是否接入及其安装侧。固件使用 7 位地址接口时，应传入 0x51 或 0x50。I²C 地址用于区分安装侧，EEPROM 中的 Board Type 与 Board ID 用于识别灯板类型与型号。

模块名称	Board Type（类型码）	Board ID（型号 ID）
RGB 矩阵灯模块 M（中号）	0x11	0x0001

RGB 矩阵灯模块的类型码为 0x11，当前 M 号（中号）的 Board ID 为 0x0001。完整数据格式将通过开源附件或配套网页提供。

RGB 矩阵灯模块 M（中号）

核心特点

8 × 8 全彩矩阵：64 个 RGB 像素，可分别控制颜色，组合出丰富的灯光与图案。
左右侧插连接：可根据设备造型和使用场景，安装在 ESP-Mosaico 主板左侧或右侧。
灯效与显示结合：既可以作为动态灯光模块，也可以作为小型 LED 点阵显示区域。
单线级联控制：64 颗 WS2812 灯珠（型号为 WS2812C-2020-V6）依次级联，前一颗灯珠的 DO 接后一颗的 DI，由主板通过一条数据线控制整块 8 × 8 RGB 矩阵。
板载 EEPROM 自动识别：存储灯板描述与参数，主板通过 I²C 读取 EEPROM 识别灯板类型、型号和版本，并判断其左右安装位置。

硬件参数

项目	说明
适配主板	ESP-Mosaico
模块型号	ESP_Mosaico_Module_RGB_Matrix_M（M 表示中号）
硬件版本	V1.0
矩阵规格	8 × 8，共 64 个 RGB LED
LED 型号	WS2812C-2020-V6
LED 位号	U1～U64
LED 供电	灯板 5V 电源输入，来自 ESP-Mosaico 主板的 5V 输出（原理图网络名：5V_OUT）
LED 控制	由主板 GPIO48／GPIO47 控制：左侧 GPIO48，右侧 GPIO47（RGB_CTRL）
侧插连接器	H2，HX PZ2.54-1x10P WT，单排 1 × 10P、2.54 mm 间距；插入主板双排侧接口的下排
EEPROM	U65，AT24C02BS(GMIC)
3.3V 稳压器	LDO1，ME6211C33M5G-N
硬件设计标识	ESP_Mosaico_Module_RGB_Matrix_M_V1_0

3D 外壳模型下载

RGB 矩阵灯模块 M（中号）的 3D 外壳模型下载链接：ESP-Mosaico RGB 矩阵灯模块 3D 外壳模型。

灯效与显示玩法

配合相应的主板程序，RGB 矩阵灯模块可以实现以下效果：

炫酷灯效：彩虹渐变、呼吸灯、流水灯、追逐灯和色彩波纹等。
像素动画：以 8 × 8 像素画布绘制图案，逐帧播放简单动画。
表情与图标：显示笑脸、爱心、箭头及其他像素符号，让设备具备更直观的视觉反馈。
LED 屏幕显示：显示简单数字、字母或滚动内容，适合计数、提示和小型信息展示。
状态反馈：通过颜色、图案和闪烁节奏表达运行状态、操作结果或通知信息。

以上为硬件可承载的应用方向，具体效果需要配套固件实现。单块灯板的显示分辨率为 8 × 8，适合简洁图案与像素风格内容。

RGB 矩阵灯模块连接与使用

侧插安装

RGB 矩阵灯模块使用单排侧插连接器，可安装在 ESP-Mosaico 主板左侧或右侧。主板侧接口为双排结构，灯板应插入双排接口的下排。

关闭主板电源，确认灯板与主板接口的安装方向。
将灯板的单排连接器对准主板双排侧接口的下排后插入，确认针脚对齐、接口完全就位，避免插错排或错位插接。
使用支持灯板识别的主板固件，由主板读取 EEPROM，识别灯板并判断当前安装侧，再按对应接口配置控制引脚与显示方向。
上电后先以低亮度测试，再运行灯效或显示程序。

左右侧接口的 GPIO 对应关系应结合主板原理图和固件配置核对。安装位置或朝向变化时，可以通过软件调整像素坐标映射，使图案保持正确方向。

接口信号说明

下表按灯板原理图中的 H2 引脚编号整理；网络名称沿用原理图标注。5V_OUT 中的 OUT 表示主板输出，对灯板而言该引脚是 5V 电源输入。

H2 引脚	原理图网络	灯板连接用途
1	未连接	未使用
2	GPIO_48/47、RGB_CTRL	RGB 矩阵数据输入：左侧由主板 GPIO48 控制，右侧由 GPIO47 控制
3	未连接	本页原理图未连接
4	未连接	本页原理图未连接
5	GPIO_14/39	经 R7（0Ω）连接 EEPROM 的 A0
6	未连接	本页原理图未连接
7	GPIO_1	EEPROM 的 SCL
8	GPIO_0	EEPROM 的 SDA
9	5V_OUT	灯板 5V 电源输入，来自主板 5V 输出
10	GND	电源与信号公共地

原理图中的 GPIO_48/47 对应左侧 GPIO48、右侧 GPIO47，用于 RGB 数据控制；GPIO_14/39 对应左侧 GPIO14、右侧 GPIO39，用于 EEPROM 地址选择。

RGB 矩阵灯模块硬件电路设计

RGB 矩阵电路

灯板采用 64 颗 WS2812C-2020-V6，组成 8 × 8 全彩矩阵。各 LED 的 VDD 接入由主板提供的 5V 电源（原理图网络名为 5V_OUT），GND 接公共地。

数据从 RGB_CTRL 进入第一颗 LED（U1）的 DI 引脚，再由前一颗 LED 的 DO 连接至后一颗 LED 的 DI，按 U1 → U2 → … → U64 串联。主板通过这一条数据链路更新整块灯板的像素颜色。

8 × 8 矩阵的灯珠排列与灯序如下图所示。软件绘制图案时，应根据图中的灯序，将二维像素坐标映射到对应灯珠序号。

8x8 矩阵灯灯序图.png

调试时可通过逐灯点亮核对灯序与坐标映射；根据模块安装朝向调整旋转或镜像，使显示图案方向正确。

5V 转 3.3V 电源电路

灯板上的 ME6211C33M5G-N 将主板送入灯板的 5V 电源（5V_OUT）转换为 VCC_3V3，用于 EEPROM 供电。稳压器输入与输出分别配置 C1、C4（均为 1 μF）。

5V 转 3.3V 电源电路

LED 矩阵由 5V 网络供电，EEPROM 使用板载稳压后的 3.3V 网络。

EEPROM 电路

板载 AT24C02BS(GMIC) 通过 SDA、SCL 与主板连接，用于存储灯板标识与配置数据。

EEPROM 电路

SDA 接 GPIO_0，SCL 接 GPIO_1。
A0 经 R7（0Ω）接 GPIO_14/39，A1、A2 接地。
WP 通过 R10（10kΩ）下拉至地；R11 标注为 10kΩ/NC，为可选上拉位置。

灯板 EEPROM 使用 V1.0 数据格式，主板通过读取描述数据识别灯板，识别原理见前文“灯板识别与左右插入检测”，完整数据格式见配套规范。

开源软件

配套开源软件运行在 ESP-Mosaico 主板上，提供两个示例程序：

灯板识别与灯效显示示例：主板识别插入的灯板后，驱动 8 × 8 RGB 矩阵显示炫酷的动态灯效。通过控制 64 颗级联 WS2812 灯珠的颜色与亮度，呈现全彩灯光效果，实际效果可参考前文的展示动图。

软件地址：matrix_rgb_led

EEPROM 数据烧写示例：由主板向灯板 EEPROM 烧写识别数据，包括类型码 0x11、M 号 Board ID 0x0001 等信息，为灯板识别提供数据基础。

软件地址：module_eeprom_programmer

复刻灯板时，可先使用 EEPROM 数据烧写示例写入识别信息，再运行灯板识别与灯效显示示例进行测试。

开发环境、编译烧录步骤及使用方法以链接中的项目说明为准。

RGB 矩阵灯模块复刻与调试指南

准备材料

材料	说明
RGB 矩阵灯模块 PCB 与元器件	按对应版本的 PCB、BOM 和原理图准备
ESP-Mosaico 主板	为灯板提供连接、供电和控制
侧插连接器	核对型号、间距与安装方向
主板供电及下载调试工具	用于运行灯板控制程序

复刻步骤

在嘉立创 EDA 中核对灯板原理图、PCB 与 BOM 的版本一致性，再进行 PCB 打样及元器件采购或 SMT 贴装。
检查 LED 的方向和焊接质量，重点检查第一颗灯珠、级联数据链路和侧插连接器。
上电前检查电源与地之间是否短路，确认连接器方向正确。
断电状态下，将灯板的单排连接器插入 ESP-Mosaico 主板左侧或右侧双排接口的下排。
按配套规范烧录灯板 EEPROM 数据并校验 CRC；使用支持该灯板的主板固件，确认正确识别灯板类型与安装侧，再核对 RGB 控制 GPIO、64 个像素及 LED 驱动参数。
先低亮度逐灯测试，再测试红、绿、蓝单色和简单图案，最后运行动态灯效。

调试要点

灯板未识别或安装侧识别异常：检查 EEPROM 供电、SDA/SCL、A0 连接和侧接口访问配置，并核对 Magic、灯板型号及描述区 CRC。
全部不亮：检查 5V 供电、公共地、RGB 控制引脚和第一颗 LED 的输入连接。
部分灯珠不亮：检查故障位置前后灯珠的焊接与 DO/DI 数据链路。
颜色不正确：核对程序的颜色通道顺序与 LED 驱动配置。
图案倒置或错位：核对像素序号与二维坐标映射，并调整旋转或镜像方向。
高亮度时闪烁或主板重启：检查供电能力与接口连接，并降低全局亮度后复测。

64 颗 LED 同时点亮时，功耗会随颜色和亮度变化。使用时应结合主板供电能力设置亮度上限，首次调试建议从低亮度开始。

8×8 RGB matrix light module

Comments (0)