跳转到内容
ESPHome - 让智能家居更简单2026.7.0

HUB75 RGB LED 矩阵显示

hub75 显示平台允许你在使用 ESPHome 时使用 HUB75 RGB LED 矩阵面板。此组件使用基于 DMA 的高性能驱动，提供高效、低 CPU 开销的 LED 矩阵面板驱动。

HUB75 显示器是使用并行行刷新的 RGB LED 矩阵面板，可创建动态、多彩的显示。它们常见的尺寸有 64×32、64×64，并且可以级联在一起创建更大的显示。

硬件要求

Section titled “硬件要求”

支持的 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 等）

引脚连接

Section titled “引脚连接”

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

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

NOTE

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

TIP

使用 板预设 自动为常见硬件配置引脚，或者如果使用自定义接线，则手动指定所有引脚。

用法

Section titled “用法”
# 使用板预设的示例（推荐）
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 进行高效的显示更新。

板预设

Section titled “板预设”

板预设会自动为流行的 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

使用板预设

Section titled “使用板预设”
display:
  - platform: hub75
    id: matrix_display
    board: adafruit-matrix-portal-s3
    panel_width: 64
    panel_height: 32

覆盖特定引脚

Section titled “覆盖特定引脚”

你可以覆盖单个引脚，同时仍然使用板预设：

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

手动引脚配置

Section titled “手动引脚配置”

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

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

配置变量

Section titled “配置变量”

板配置（推荐）

Section titled “板配置（推荐）”
  • board (可选, string): 板预设名称。可选值：adafruit-matrix-portal-s3、apollo-automation-m1-rev4、apollo-automation-m1-rev6、huidu-hd-wf2。指定后，自动配置所有引脚映射。

面板尺寸（必需）

Section titled “面板尺寸（必需）”
  • panel_width (必需, int): 单个面板的像素宽度（例如 64）。
  • panel_height (必需, int): 单个面板的像素高度（例如 32）。

多面板布局（可选）

Section titled “多面板布局（可选）”

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

  • layout_rows (可选, int): 垂直排列的面板数量。默认为 1。
  • layout_cols (可选, int): 水平排列的面板数量。默认为 1。
  • layout (可选, enum): 物理面板级联模式。默认为 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 像素。

面板硬件（可选）

Section titled “面板硬件（可选）”

  • scan_wiring (可选, enum): 面板扫描接线模式。默认为 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_32PX_FULL - 32px 高面板的 1/8 扫描，段宽度为面板全长
    • SCAN_1_8_40PX_HIGH - 40px 高面板的 1/8 扫描
    • SCAN_1_8_64PX_HIGH - 64px 高面板的 1/8 扫描

  • shift_driver (可选, enum): LED 移位寄存器驱动芯片类型。默认为 GENERIC。可选值：

    • GENERIC - 标准移位寄存器（默认）
    • FM6124 - FM6124 驱动
    • FM6126A - FM6126A / ICN2038S 驱动（非常常见）
    • ICN2038S - FM6126A 的别名
    • MBI5124 - MBI5124 驱动（需要 clock_phase: true）
    • DP3246 - DP3246 驱动

显示配置（可选）

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

引脚配置

Section titled “引脚配置”

当未指定 board 时必需：

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

高级计时（可选）

Section titled “高级计时（可选）”

  • clock_speed (可选, enum): 输出时钟速度。默认为 20MHZ。可选值：

    • 8MHZ - 8 MHz
    • 10MHZ - 10 MHz
    • 16MHZ - 16 MHz
    • 20MHZ - 20 MHz（默认）

  • latch_blanking (可选, int): LAT 脉冲期间 OE 被消隐的时钟周期数。默认为 1。

  • clock_phase (可选, boolean): 反转时钟相位。默认为 false。MBI5124 驱动需要为 true。

标准显示选项

Section titled “标准显示选项”

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

多面板布局

Section titled “多面板布局”

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

水平级联

Section titled “水平级联”

对于简单的从左到右水平级联，使用 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 网格布局

Section titled “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 一起使用

Section titled “与 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 管理自己的缓冲

操作

Section titled “操作”

hub75.set_brightness 操作

Section titled “hub75.set_brightness 操作”

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

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

配置变量：

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

配置示例

Section titled “配置示例”

基本单板（使用板预设）

Section titled “基本单板（使用板预设）”
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!");

水平级联面板

Section titled “水平级联面板”
# 三块 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());

手动引脚配置

Section titled “手动引脚配置”
# 使用自定义引脚，不使用板预设
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

带移位驱动的高级配置

Section titled “带移位驱动的高级配置”
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 网格布局

Section titled “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");

重要提示

Section titled “重要提示”
  • 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 引脚要求：1/32 扫描面板（32 或 64 行）需要 E 引脚。1/16 扫描面板（16 行）可以省略。
  • 时钟相位：MBI5124 驱动需要 clock_phase: true 才能正确工作。

参见

Section titled “参见”