IT8951 电子纸显示

it8951 显示平台为使用 ITE IT8951 控制器的电子纸显示提供了一个驱动。

IT8951 控制器支持 16 级灰度和多种刷新模式包括快速局部更新。它出现在较大的电子纸显示（4.7” 及以上）和集成板（如 M5Paper）中。

通信方法使用 SPI，因此你需要在配置中有一个 spi: 部分。MOSI 和 MISO 都是必需的（驱动从控制器读取设备信息和寄存器值）。

对于有预定义配置的集成板，只需指定模型名称即可。如有需要可以覆盖其他选项。

display:
  - platform: it8951
    model: m5stack-m5paper
    lambda: |-
      it.filled_circle(it.get_width() / 2, it.get_height() / 2, 50, Color::BLACK);

支持的型号

通用控制器

使用通用 IT8951 模型需要完整配置，并指定引脚和尺寸。

模型名称	描述
IT8951	通用 IT8951 控制器。数据手册

集成显示板

这些型号有预定义的引脚分配和尺寸。至少只需配置模型名称即可。

模型名称	制造商	尺寸	描述
m5stack-m5paper	M5Stack	960×540	M5Paper 4.7” 电子墨水，16 级灰度。文档
Seeed-reTerminal-E1003	Seeed Studio	1872×1404	产品页面
Seeed-EE03	Seeed Studio	1872×1404	带 10.3” 电子纸的 Seeed EE03 板。

IMPORTANT

m5stack-m5paper 型号适用于 SKU K049 型号及变体（K049-B、K049-C）

更新的（但已停产）M5PaperS3 不使用 IT8951 或任何驱动，而是直接连接到 ESP32S3，不受此组件支持。

配置变量

使用集成显示板型号时，大部分配置（引脚、尺寸、VCOM）已预设，但可以覆盖。

model (必需): IT8951 显示的模型。请参阅上面的表格了解选项（大小写不敏感）。可选值为 IT8951、m5stack-m5paper、 Seeed-reTerminal-E1003、Seeed-EE03。
cs_pin（通用必需，集成板可选， Pin Schema）：SPI 片选引脚。
busy_pin（通用必需，集成板可选， Pin Schema）：HRDY（主机就绪）引脚。 IT8951 使用高电平有效的就绪信号（HIGH = 就绪，LOW = 忙）。
reset_pin（通用必需，集成板可选， Pin Schema）：硬件复位引脚。如果未连接到 GPIO 引脚，请确保将该引脚拉高（通过电阻连接到 3.3V）。
enable_pin（可选，Pin Schema 或列表）：一个或多个 GPIO 在设置期间被驱动为高电平以给面板上电，在复位和初始化之前。对于具有一个或多个显示电源使能电源轨的板很有用。
dimensions（通用必需，集成板可选）：屏幕尺寸，可以 width x height （例如 960x540）或分别用配置键指定。尺寸以像素为单位表示原生面板方向（旋转前）。
- width (必需, int): 以像素指定显示的宽度。
- height (必需, int): 以像素指定显示的高度。
rotation（可选, int): 设置显示的旋转角度。你在 lambda: 中绘制的一切将被旋转。可选值为 0°（默认）、90°、180°、 270°。
transform（可选, dict): 在旋转之上应用的附加转换。
- mirror_x (必需, boolean): 如果为 true，则镜像 x 轴。
- mirror_y (必需, boolean): 如果为 true，则镜像 y 轴。
- swap_xy (必需, boolean): 如果为 true，则交换 x 和 y 轴。

update_mode（可选, enum): 显示更新的默认波形模式。如果不设置，默认为 GC16（完整灰度）。可以通过 it8951.update 操作每次更新覆盖。可选值有：

模式	描述
`INIT`	完全擦除为白色。上电后或显示状态未知时使用。
`DU`	直接更新。快速，无闪烁。仅黑白转换。也作为 `fast` 可用。
`GC16`	灰度清除。完整 16 级灰度，最高质量。也作为 `full` 可用。
`GL16`	灰度轻量。16 级，减少闪烁，适合白底上的抗锯齿文本。
`GLR16`	类似 GL16 但减少伪影（需要图像预处理）。
`GLD16`	类似 GL16 但进一步减少伪影（建议完整显示更新）。
`DU4`	4 级灰度，快速更新。适合菜单中的抗锯齿文本。
`A2`	最快模式。仅黑白，最小残影。适合动画/翻页。

NOTE

并非每个波形都存在每个面板的波形 LUT 中。在受支持的 Seeed 面板上，只有 GC16（灰度）和 DU（单色）已被验证可以正确渲染；降低灰度模式（GL16、 GLR16、GLD16、DU4）和 A2 可能会将白色背景渲染为灰色。驱动自动模式选择因此只使用 GC16 和 DU；仅在确认它对你的面板有效时才将 update_mode 设置为其他值。

full_update_every（可选, int): 强制完整 GC16 刷新之间的更新次数，以清除累积的残影。默认为 30；范围 1-255。启动后的第一次更新始终是完整刷新。在单色模式（grayscale: false）中，中间更新使用快速的 DU 波形；在灰度模式下，它们保持为 GC16（参见 update_mode 下的注释）。
auto_clear_enabled（可选, boolean): 当为 true（配置了 lambda 或 pages 时的默认值），帧缓冲在每次渲染前清除，因此每次更新重绘并刷新整个屏幕。设置为 false 以启用局部区域更新，仅传输并刷新更改的区域 —— 请参见区域更新。
vcom（可选, int): VCOM 电压（毫伏）。每个电子纸面板都有特定的 VCOM 值印在其柔性电缆上。m5stack-m5paper 默认为 2300（2.3V）。错误的 VCOM 可能导致图像质量问题。
invert_colors（可选, boolean): 反转颜色映射（交换黑色和白色）。默认为 false。
sleep_when_done（可选, boolean): 每次显示更新完成后将 IT8951 控制器置于深度睡眠。减少功耗但增加下次更新的唤醒延迟。m5stack-m5paper 默认为 true， Seeed 板为 false。
grayscale（可选, boolean): 选择帧缓冲像素格式。当为 true（默认），帧缓冲存储 16 级灰度（每像素 4 位），更新使用 GC16 波形。当为 false 时，帧缓冲为打包单色（每像素 1 位）：这减半了 RAM 使用，大约减半了传输时间，并在完整清除之间启用快速的 DU 局部刷新。对于纯黑白内容（文本、二维码、线条画），选择 false，其中速度和内存比灰度更重要。
dithering（可选, boolean): 仅单色（当 grayscale 为 true 时无效果）。当为 true（默认），颜色以有序（Bayer）抖动再现，因此淡色调 —— 按钮填充、加载弧、浅灰 —— 渲染为可见的黑白点阵而不是消失为白色。纯黑和纯白保持实心。设置为 false 以使用硬性 50% 黑白阈值（更清晰、无点阵的文本，代价是淡填充消失）。
reset_duration（可选, Time): 硬件复位脉冲的持续时间。默认为 10ms。最大 500ms。
lambda（可选, lambda): 用于在显示上渲染内容的 lambda。参见显示渲染引擎了解更多信息。
pages（可选, list): 显示页面而非单个 lambda。参见显示页面。
update_interval（可选, Time): 重新绘制屏幕的间隔。默认为 1min。使用 never 仅通过 component.update 手动更新屏幕。
spi_id（可选, ID): 如果配置定义了多个 SPI 总线，则必须指定 SPI 组件的 ID。
id（可选, ID): 手动指定用于代码生成的 ID。

操作

`it8951.update` 操作

触发显示更新，可选项波形模式覆盖：

on_...:
  then:
    - it8951.update:
        id: my_display
        mode: DU

id (必需, ID): 要更新的显示。
mode（可选, string): 本次更新的波形模式。如果省略，使用配置的 update_mode 或默认为 GC16。支持模板化。

完整配置示例

M5Paper（集成板）

最小配置 —— 引脚和尺寸已预设：

spi:
  clk_pin: GPIO18
  mosi_pin: GPIO23
  miso_pin: GPIO34

display:
  - platform: it8951
    model: m5stack-m5paper
    update_interval: 30s
    update_mode: DU
    full_update_every: 20
    rotation: 270
    lambda: |-
      it.print(10, 10, id(my_font), "Hello, M5Paper!");

通用 IT8951 控制器

完整配置，显式引脚和尺寸：

spi:
  clk_pin: GPIO18
  mosi_pin: GPIO23
  miso_pin: GPIO19

display:
  - platform: it8951
    model: IT8951
    dimensions:
      width: 1024
      height: 758
    cs_pin: GPIO15
    reset_pin: GPIO22
    busy_pin: GPIO27
    vcom: 2100
    update_interval: 1min
    full_update_every: 10
    rotation: 0
    lambda: |-
      it.fill(Color::WHITE);
      it.print(10, 10, id(my_font), Color::BLACK, "Hello!");

与 LVGL 一起使用

与 LVGL 一起使用时，设置 update_interval: never 并让 LVGL 管理更新：

display:
  - platform: it8951
    model: m5stack-m5paper
    id: my_display
    update_interval: never
    rotation: 270

使用不同模式的局部更新

对交互元素使用快速模式，对定期清理使用完整模式：

display:
  - platform: it8951
    model: m5stack-m5paper
    id: my_display
    update_mode: DU
    full_update_every: 30
    update_interval: 5s
    rotation: 270
    lambda: |-
      it.fill(Color::WHITE);
      it.strftime(10, 10, id(my_font), "%H:%M:%S", id(my_time).now());

区域更新（局部区域）

默认情况下，每次更新都重绘并刷新整个屏幕，因为 auto_clear_enabled 默认为 true，并在每次渲染前清除帧缓冲。设置 auto_clear_enabled: false 启用区域更新：帧缓冲在更新之间保持，只有你的 lambda 绘制的边界框传输到控制器并在面板上刷新。这要快得多，并且只闪烁更改的区域。

由于缓冲区持久化，你的 lambda 必须擦除它即将重绘的区域（覆盖旧像素），否则先前内容的残余会保留。擦除也算作绘制，因此它包含在更改区域中：

display:
  - platform: it8951
    model: m5stack-m5paper
    id: my_display
    auto_clear_enabled: false
    update_mode: DU
    full_update_every: 30
    update_interval: 1s
    rotation: 270
    lambda: |-
      // 仅擦除时钟区域，然后重绘它。只有这个矩形被
      // 传输和刷新；面板的其余部分保持不变。
      it.filled_rectangle(0, 0, 360, 90, Color::WHITE);
      it.strftime(0, 0, id(my_font), Color::BLACK, "%H:%M:%S", id(my_time).now());

注意：

更改区域的水平范围四舍五入为 32 像素的倍数（硬件对齐要求）；垂直范围是精确的。
仍然每隔 full_update_every 次更新强制执行一次完整 GC16 刷新，并且在启动后的第一次更新时，以清除累积的残影。
如果 lambda 什么都不绘制，则完全跳过更新。

技术说明

IT8951 控制器支持高达 16 级的灰度（每像素 4 位）。设置 grayscale: false 以将帧缓冲存储为打包的 1 位单色，使用的 RAM 只有四分之一，每次更新的传输数据大大减少。
驱动是完全非阻塞的。SPI 操作排队，并在主循环的每次迭代中执行一次，受 HRDY 引脚控制。行数据传输进行时间切片，以保持循环滴答预算。
帧缓冲存储在 ESP32 设备的 PSRAM 中。对于 960×540 显示在 4bpp 下，这需要大约 260 KB。
显示渲染 lambda 同步运行，由于 PSRAM 访问延迟，复杂 UI 可能需要 200-300ms。对于带有大型帧缓冲的电子纸显示来说这是正常的。