HUB75 RGB LED 点阵显示屏

hub75 显示平台允许您在 ESPHome 中使用 HUB75 RGB LED 点阵面板。该组件使用高性能的基于 DMA 的驱动程序，可高效、低 CPU 开销地驱动 LED 点阵面板。

HUB75 显示屏是使用并行行更新来创建动态、多彩显示屏的 RGB LED 点阵面板。常见的尺寸有 64×32、64×64，并且可以级联以创建更大的显示屏。

硬件要求

支持的 ESP32 变体：

ESP32（原始版本）
ESP32-S2
ESP32-S3
ESP32-P4

WARNING

此组件不适用于 ESP32-C3、ESP32-C2 或 ESP32-H2。

内存注意事项：

使用大量内部 SRAM 用于 DMA 缓冲
较大的显示屏或更长的级联需要更多内存
带有 PSRAM 的 ESP32-S3 可以帮助解决内存限制
内存使用量随面板分辨率和级联长度增加

电源供应：

需要 LED 面板的专用电源
ESP32 和面板之间的正确接地连接至关重要
在电源线上添加电容器以防止闪烁

支持的面板类型：

“双扫描”面板（1/16 和 1/32 扫描率）
带有各种驱动芯片的面板（FM6124、FM6126A、ICN2038S、MBI5124、DP3246 等）

引脚连接

HUB75 面板使用带有以下引脚的标准连接器：

HUB75 引脚	描述	ESPHome 配置
R1	红色数据（上半部分）	`r1_pin`
G1	绿色数据（上半部分）	`g1_pin`
B1	蓝色数据（上半部分）	`b1_pin`
R2	红色数据（下半部分）	`r2_pin`
G2	绿色数据（下半部分）	`g2_pin`
B2	蓝色数据（下半部分）	`b2_pin`
A	行地址位 0	`a_pin`
B	行地址位 1	`b_pin`
C	行地址位 2	`c_pin`
D	行地址位 3	`d_pin`
E	行地址位 4	`e_pin`
LAT	锁存/选通	`lat_pin`
OE	输出使能	`oe_pin`
CLK	时钟	`clk_pin`
GND	接地	N/A

NOTE

E 引脚仅用于 1/32 扫描面板（具有 32 或 64 行的面板）。对于 1/16 扫描面板可以省略。

TIP

使用开发板预设自动配置常见硬件的引脚，或在使用自定义接线时手动指定所有引脚。

用法

# 使用开发板预设的示例（推荐）
display:
  - platform: hub75
    id: matrix_display
    board: adafruit-matrix-portal-s3
    panel_width: 64
    panel_height: 32
    lambda: |-
      it.print(0, 0, id(font), "Hello World!");

NOTE

与某些其他显示组件不同，HUB75 不需要 SPI 总线配置。它在内部使用 DMA 进行高效的显示更新。

开发板预设

开发板预设自动配置流行 HUB75 控制板的所有引脚映射。这是支持硬件的推荐方法。

可用的开发板预设：

adafruit-matrix-portal-s3 - Adafruit Matrix Portal S3
apollo-automation-m1-rev4 - Apollo Automation M1 (Rev 4)
apollo-automation-m1-rev6 - Apollo Automation M1 (Rev 6)
huidu-hd-wf1 - Huidu HD-WF1
huidu-hd-wf2 - Huidu HD-WF2
esp32-trinity - ESP32-Trinity

使用开发板预设

display:
  - platform: hub75
    id: matrix_display
    board: adafruit-matrix-portal-s3
    panel_width: 64
    panel_height: 32

覆盖特定引脚

您可以在使用开发板预设的同时覆盖单个引脚：

display:
  - platform: hub75
    id: matrix_display
    board: apollo-automation-m1-rev4
    panel_width: 64
    panel_height: 32
    r2_pin: GPIO21  # 只覆盖一个引脚
    g2_pin: GPIO22

手动引脚配置

如果您不使用支持的开发板，请手动指定所有引脚：

display:
  - platform: hub75
    id: matrix_display
    panel_width: 64
    panel_height: 32
    r1_pin: GPIO25
    g1_pin: GPIO26
    b1_pin: GPIO27
    r2_pin: GPIO21
    g2_pin: GPIO22
    b2_pin: GPIO32
    a_pin: GPIO23
    b_pin: GPIO19
    c_pin: GPIO5
    d_pin: GPIO17
    e_pin: GPIO18  # 可选，对于 1/16 扫描面板省略
    lat_pin: GPIO4
    oe_pin: GPIO15
    clk_pin: GPIO16

配置变量

开发板配置（推荐）

board (可选, 字符串)：开发板预设名称。可选：adafruit-matrix-portal-s3、apollo-automation-m1-rev4、apollo-automation-m1-rev6、huidu-hd-wf2。指定时自动配置所有引脚映射。

面板尺寸（必填）

panel_width (必填, int)：单个面板的宽度（像素）（如 64）。
panel_height (必填, int)：单个面板的高度（像素）（如 32）。

多面板布局（可选）

用于通过级联多个面板创建更大的显示屏：

layout_rows (可选, int)：垂直排列的面板数量。默认为 1。
layout_cols (可选, int)：水平排列的面板数量。默认为 1。
layout (可选, 枚举)：物理面板级联模式。默认为 HORIZONTAL。可选：
- HORIZONTAL - 简单的从左到右水平级联（单行）
- TOP_LEFT_DOWN - 蛇形：从左上开始，行从上到下
- TOP_RIGHT_DOWN - 蛇形：从右上开始，行从上到下
- BOTTOM_LEFT_UP - 蛇形：从左下开始，行从下到上
- BOTTOM_RIGHT_UP - 蛇形：从右下开始，行从下到上
- TOP_LEFT_DOWN_ZIGZAG - 锯齿形：从左上开始（所有面板直立）
- TOP_RIGHT_DOWN_ZIGZAG - 锯齿形：从右上开始（所有面板直立）
- BOTTOM_LEFT_UP_ZIGZAG - 锯齿形：从左下开始（所有面板直立）
- BOTTOM_RIGHT_UP_ZIGZAG - 锯齿形：从右下开始（所有面板直立）

NOTE

总显示尺寸将是 panel_width × layout_cols 乘以 panel_height × layout_rows 像素。

面板硬件（可选）

scan_wiring (可选, 枚举)：面板扫描接线模式。默认为 STANDARD_TWO_SCAN。可选：
- STANDARD_TWO_SCAN - 标准 1/16 或 1/32 扫描（最常见）
- SCAN_1_4_16PX_HIGH - 16px 高面板的 1/4 扫描
- SCAN_1_8_32PX_HIGH - 32px 高面板的 1/8 扫描
- SCAN_1_8_40PX_HIGH - 40px 高面板的 1/8 扫描
- SCAN_1_8_64PX_HIGH - 64px 高面板的 1/8 扫描
shift_driver (可选, 枚举)：LED 移位寄存器驱动芯片类型。默认为 GENERIC。可选：
- GENERIC - 标准移位寄存器（默认）
- FM6124 - FM6124 驱动
- FM6126A - FM6126A / ICN2038S 驱动（非常常见）
- ICN2038S - FM6126A 的别名
- MBI5124 - MBI5124 驱动（需要 clock_phase: true）
- DP3246 - DP3246 驱动

显示配置（可选）

brightness (可选, int)：初始亮度级别（0-255）。默认为 128。
bit_depth (可选, int)：颜色位深（4-12）。值越高颜色精度越好但刷新越慢。默认为 8。
gamma_correct (可选, 枚举)：伽马校正模式。可选：
- LINEAR - 无伽马校正（原始值）
- CIE1931 - CIE 1931 感知曲线（推荐用于大多数显示屏）
- GAMMA_2_2 - 标准 2.2 伽马曲线
double_buffer (可选, 布尔值)：启用双缓冲以防止撕裂。默认为 false。使用 LVGL 时设置为 false。
update_interval (可选, 时间)：显示更新频率。默认为 16ms（约 60 FPS）。使用 LVGL 时设置为 never。
min_refresh_rate (可选, int)：最小面板刷新率（Hz）（40-200）。面板可能刷新得更快，但不会更慢。从 update_interval 自动计算（update_interval: never 时默认为 60 Hz）。很少需要手动设置。

引脚配置

当未指定 board 时必填：

r1_pin (引脚模式)：上半部分红色数据引脚。
g1_pin (引脚模式)：上半部分绿色数据引脚。
b1_pin (引脚模式)：上半部分蓝色数据引脚。
r2_pin (引脚模式)：下半部分红色数据引脚。
g2_pin (引脚模式)：下半部分绿色数据引脚。
b2_pin (引脚模式)：下半部分蓝色数据引脚。
a_pin (引脚模式)：行地址位 0。
b_pin (引脚模式)：行地址位 1。
c_pin (引脚模式)：行地址位 2。
d_pin (引脚模式)：行地址位 3。
e_pin (可选, 引脚模式)：行地址位 4。1/32 扫描面板（32+ 行）必填，1/16 扫描面板省略。
lat_pin (引脚模式)：锁存/选通引脚。
oe_pin (引脚模式)：输出使能引脚。
clk_pin (引脚模式)：时钟引脚。

高级时序（可选）

clock_speed (可选, 枚举)：输出时钟速度。默认为 20MHZ。可选：
- 8MHZ - 8 MHz
- 10MHZ - 10 MHz
- 16MHZ - 16 MHz
- 20MHZ - 20 MHz（默认）
latch_blanking (可选, int)：LAT 脉冲期间 OE 空白的时钟周期数。默认为 1。
clock_phase (可选, 布尔值)：反转时钟相位。默认为 false。MBI5124 驱动需要设置为 true。

标准显示选项

所有标准的图形显示配置选项也可用，包括 lambda、pages、rotation 和 auto_clear_enabled。

多面板布局

您可以将多个面板级联在一起以创建更大的显示屏。该组件支持简单的水平级联和复杂的 2D 网格排列。

水平级联

对于简单的从左到右水平级联，使用 layout_cols：

# 三个 64x32 面板水平级联 = 总共 192x32
display:
  - platform: hub75
    id: matrix_display
    board: adafruit-matrix-portal-s3
    panel_width: 64
    panel_height: 32
    layout_cols: 3
    layout: HORIZONTAL

2D 网格布局

对于按行和列排列的面板，同时指定 layout_rows 和 layout_cols，以及适当的 layout 模式：

# 四个 64x32 面板排列成 2x2 网格 = 总共 128x64
display:
  - platform: hub75
    id: matrix_display
    board: adafruit-matrix-portal-s3
    panel_width: 64
    panel_height: 32
    layout_rows: 2
    layout_cols: 2
    layout: TOP_LEFT_DOWN_ZIGZAG

TIP

蛇形布局（如 TOP_LEFT_DOWN）物理上将交替行倒置以最小化电缆长度。锯齿形布局（如 TOP_LEFT_DOWN_ZIGZAG）保持所有面板直立，但行之间需要更长的电缆。

与 LVGL 配合使用

当此显示屏与 LVGL 配合使用时，您必须按以下方式配置显示屏：

display:
  - platform: hub75
    id: matrix_display
    board: adafruit-matrix-portal-s3
    panel_width: 64
    panel_height: 32
    update_interval: never
    auto_clear_enabled: false
    double_buffer: false
    # LVGL 配置单独放置

LVGL 的三个关键设置是：

update_interval: never - LVGL 控制何时更新（最小刷新率自动默认为 60 Hz）
auto_clear_enabled: false - LVGL 处理清除
double_buffer: false - LVGL 管理自己的缓冲

动作

`hub75.set_brightness` 动作

此动作允许您在运行时动态更改显示屏的亮度。

on_...:
  - hub75.set_brightness:
      id: matrix_display
      brightness: 128

配置变量：

id (可选, ID)：HUB75 显示组件的 ID。仅当配置了多个 hub75 平台显示屏时才需要。
brightness (必填, int, 可模板化)：要设置的亮度级别（0-255）。值为 0 实际上关闭显示屏，而 255 是最大亮度。

配置示例

基本单面板（使用开发板预设）

display:
  - platform: hub75
    id: matrix_display
    board: adafruit-matrix-portal-s3
    panel_width: 64
    panel_height: 32
    lambda: |-
      it.print(0, 0, id(font), "Hello!");

水平级联面板

# 三个 64x32 面板水平级联 = 总共 192x32
display:
  - platform: hub75
    id: matrix_display
    board: apollo-automation-m1-rev4
    panel_width: 64
    panel_height: 32
    layout_cols: 3
    layout: HORIZONTAL
    lambda: |-
      it.printf(0, 0, id(font), "Width: %d", it.get_width());

手动引脚配置

# 使用自定义引脚而不用开发板预设
display:
  - platform: hub75
    id: matrix_display
    panel_width: 64
    panel_height: 32
    r1_pin: GPIO25
    g1_pin: GPIO26
    b1_pin: GPIO27
    r2_pin: GPIO21
    g2_pin: GPIO22
    b2_pin: GPIO32
    a_pin: GPIO23
    b_pin: GPIO19
    c_pin: GPIO5
    d_pin: GPIO17
    e_pin: GPIO18  # 1/32 扫描面板必填
    lat_pin: GPIO4
    oe_pin: GPIO15
    clk_pin: GPIO16

带移位驱动器的高级配置

display:
  - platform: hub75
    id: matrix_display
    board: adafruit-matrix-portal-s3
    panel_width: 64
    panel_height: 32
    shift_driver: FM6126A
    clock_speed: 20MHZ
    brightness: 200
    bit_depth: 10
    latch_blanking: 2
    lambda: |-
      it.fill(Color(255, 0, 0));  # 红色背景

2×2 网格布局

# 四个 64x32 面板排列成 2x2 网格 = 总共 128x64
display:
  - platform: hub75
    id: matrix_display
    board: adafruit-matrix-portal-s3
    panel_width: 64
    panel_height: 32
    layout_rows: 2
    layout_cols: 2
    layout: TOP_LEFT_DOWN_ZIGZAG
    lambda: |-
      it.printf(32, 28, id(font), "128x64");

重要说明

ESP32 支持：此组件适用于 ESP32、ESP32-S2、ESP32-S3 和 ESP32-P4。它不适用于 ESP32-C3、ESP32-C2、ESP32-C6 或 ESP32-H2。
内存限制：DMA 缓冲区可能消耗大量 RAM。较大的显示屏或较长的面板级联可能无法放入可用内存。建议为大型安装使用带有 PSRAM 的 ESP32-S3。
开发板预设：使用开发板预设是最简单的入门方式。它会自动为流行的硬件正确配置所有引脚。
引脚配置：如果不使用开发板预设，所有引脚（除 e_pin 外）必须手动指定。没有默认引脚值。
驱动器兼容性：不同的面板使用不同的移位寄存器芯片。如果颜色显示错误或显示屏不工作，请尝试不同的 shift_driver 设置。FM6126A/ICN2038S 在现代面板中非常常见。
电源供应：始终为面板使用专用电源。LED 点阵可能消耗大量电流（较大的显示屏需要数安培）。
E 引脚要求：E 引脚用于 1/32 扫描面板（32 或 64 行）。对于 1/16 扫描面板（16 行）可以省略。
时钟相位：MBI5124 驱动器需要 clock_phase: true 才能正常工作。

HUB75 RGB LED 点阵显示屏

硬件要求

引脚连接

用法

开发板预设

使用开发板预设

覆盖特定引脚

手动引脚配置

配置变量

开发板配置（推荐）

面板尺寸（必填）

多面板布局（可选）

面板硬件（可选）

显示配置（可选）

引脚配置

高级时序（可选）

标准显示选项

多面板布局

水平级联

2D 网格布局

与 LVGL 配合使用

动作

hub75.set_brightness 动作

配置示例

基本单面板（使用开发板预设）

水平级联面板

手动引脚配置

带移位驱动器的高级配置

2×2 网格布局

重要说明

另见

`hub75.set_brightness` 动作