epd_compat

独立 ESPHome 组件：驱动微雪兼容 e-paper 屏。model: 选择型号名（微雪官方型号用 waveshare-*，拆机/裸屏用其真实料号）；兼容极性（颜色位映射 color_map 与 BUSY 忙闲电平）已内建在各型号，仅在特殊批次/接法与内建不符时才需覆盖。

派生自 ESPHome 的 waveshare_epaper 组件（GPL-3.0），见 LICENSE。

安装

方式一（git 仓库）：从仓库拉取组件，适合分发到其它项目。仓库根目录就是 components/ 所在处，无需额外 path：

external_components:
  - source:
      type: git
      url: https://git.o0kam1.dev/HumanlessCode/epd_compat
      ref: main
      refresh: 1d
    components: [epd_compat]

• ref 可写分支 / 标签 / 提交号；想锁定版本就改成具体 tag 或 commit。
• refresh 是拉取间隔（默认 1d）。
• 私有仓库可加 username: / password:。

方式二（本地路径）：把本仓库放到项目旁，external_components 指向 components/：

external_components:
  - source:
      type: local
      path: /path/to/epd_compat/components
    components: [epd_compat]

方式三：直接把 components/epd_compat/ 目录复制到你的配置目录下的 components/ 里。

用法

display:
  - platform: epd_compat
    model: se2417fs051-bwr    # 型号选择（本项目型号名）
    cs_pin: GPIO18
    dc_pin: GPIO15
    reset_pin: GPIO8
    busy_pin: GPIO14          # BUSY 极性已内建（本屏低电平=忙），一般无需 inverted
    update_interval: never    # 全刷约 16s，建议手动刷
    # color_map:              # 可选覆盖：仅当屏幕批次与内建极性不符时
    #   black: 1              # BW 平面：位 1 = 黑（位 0 = 白）
    #   red: 1                # 红平面：位 1 = 红（位 0 = 无红）

型号（model:）

model	实际面板 / 对应型号	颜色	分辨率	内建 color_map	内建 BUSY	备注
se2417fs051-bwr	SE2417FS051 拆机屏（兼容 4.2inch e-Paper B V2，两平面反相）	黑/白/红	400×300	{black: 1, red: 1}	低电平=忙
se2417fs051-bw	SE2417FS051 拆机屏（= 4.2 B V2 忽略红平面）	黑/白	400×300	{black: 1, red: 1}	低电平=忙	⚠️ 非官方二色 4.2 B
se2417fs051-bw-partial	SE2417FS051 拆机屏（IL0398 局部刷新序列）	黑/白	400×300	{black: 1, red: 0}	低电平=忙	局部刷新（仅黑白，无红层）
se2417fs051-4gray	SE2417FS051 拆机屏（IL0398 4Gray 序列）	4 灰阶	400×300	{black: 0, red: 0}（不生效）	低电平=忙
waveshare-2.13-v1	微雪 2.13inch e-Paper 一代 v1（IL3895，完全兼容 HINK-E0213A04-G01 裸屏）	黑/白	122×250	{black: 0, red: 0}	高电平=忙	✅ 已实测
waveshare-2.13-v1-partial	微雪 2.13inch e-Paper 一代 v1（IL3895，局部刷新，兼容 HINK-E0213A04-G01 裸屏）	黑/白	122×250	{black: 0, red: 0}	高电平=忙	局部刷新（仅换局刷 LUT）
waveshare-1.54-v1	微雪 1.54inch e-Paper 一代 v1（SSD1608，完全兼容 OED OPM016A1）	黑/白	200×200	{black: 0, red: 0}	高电平=忙	✅ 已实测
waveshare-1.54-v1-partial	微雪 1.54inch e-Paper 一代 v1（SSD1608，局部刷新，兼容 OED OPM016A1）	黑/白	200×200	{black: 0, red: 0}	高电平=忙	局部刷新（仅换局刷 LUT）
waveshare-4.2-b-v2	微雪 4.2inch e-Paper (B V2)（官方行为）	黑/白/红	400×300	{black: 0, red: 0}	高电平=忙
hink-e042a13-a0-bwr	HINK-E042A13-A0 裸屏（SSD1619A，等价 GDEH042Z96）	黑/白/红	400×300	{black: 0, red: 1}	高电平=忙	仅全刷，约 16s
hink-e042a13-a0-bw	HINK-E042A13-A0 裸屏（SSD1619A，等价 GDEH042Z96 无红层版本）	黑/白	400×300	{black: 0, red: 0}（red 不生效）	高电平=忙	仅全刷，约 16s

waveshare-2.13-v1 即微雪 2.13inch e-Paper 一代 v1（IL3895，不是 ESPHome 里 SSD1680 的 2.13inv2/inv3），完全兼容 HINK-E0213A04-G01（= HINK-E0213-G01）裸屏。命令序列已逐条对齐微雪官方 EPD_2in13 V3.0（esp8266-waveshare-epd 的 epd2in13-demo），✅ 已真机实测（全刷/局刷均可用，无需调整）。示例 logger 默认开 DEBUG，wait_until_idle_ 会打印 BUSY 拉高时长（正常全刷约 2s）便于验证。

waveshare-2.13-v1-partial 是同一块屏的局部刷新变体：只把 0x32 的 30 字节 LUT 换成微雪 EPD_2IN13_lut_partial_update，其余序列不变。IL3895 局刷仍是全窗口写入，只是波形更轻、刷新时闪烁更少；不是 IL0398（se2417fs051-bw-partial）那种 0x91/0x90 局部窗口 + diff 脏矩形。

⚠️ HINK-E0213A04-G01 裸屏 FPC 是 23 pin，比微雪 2.13 一代标准 24 pin 少的是端部 pin 1（NC）——pin 24 是 VCOM 不能省，而少中间 pin 6 会让 pin 7 起整体错位、怎么对齐都不行（与实测能点亮矛盾），故只能是 pin 1。插 24 pin 驱动板座时需让排线整体错开一位（排线 VCOM 对座 pin 24，座 pin 1 的 NC 悬空），才能让 pin 2~24 全部对位；但这样 FPC 端部少一个 pitch、无法抵住连接器定位，易滑动 → 连接不可靠。软件驱动不受影响（IL3895 协议一致），属硬件选型/接线问题——长期使用建议换 24 pin 标准屏或配 23 pin 座。

waveshare-1.54-v1 即微雪 1.54inch e-Paper 一代 v1（200×200，SSD1608，非 SSD1681），命令序列（含 30 字节全刷 LUT）逐条对齐微雪官方 EPD_1in54（esp8266-waveshare-epd 的 epd1in54-demo 例程），完全兼容 OED OPM016A1（1.6″/200×200，物理规格与微雪 1.54″ 屏等同）。✅ 已真机实测（全刷可用，无需调整）。示例 logger 默认开 DEBUG，wait_until_idle_ 会打印 BUSY 拉高时长便于验证。

waveshare-1.54-v1-partial 是同一块屏的局部刷新变体：只把 0x32 的 30 字节 LUT 换成微雪 EPD_1IN54_lut_partial_update，其余序列不变。SSD1608 局刷仍是全窗口写入，只是波形更轻、刷新时闪烁更少；不是 IL0398（se2417fs051-bw-partial）那种 0x91/0x90 局部窗口 + diff 脏矩形。

⚠️ 微雪官方二色 4.2inch e-Paper (B) 尚未实现。早期版本里的 waveshare-4.2-b 键实际驱动的是「4.2 B V2 忽略红平面」（现更名 se2417fs051-bw），并非正经官方二色 4.2 B 屏，已改名纠正。

se2417fs051-4gray 采用 IL0398（= 微雪 EPD_4in2）的 4 灰阶命令序列与 6 组 LUT，逐字节对齐官方 epd4in2-demo，真机确认可用。灰阶由 ESPHome 的 white 通道量化（color_to_grayscale4）；纯 RGB 灰（如 Color(128,128,128)）会回退到感知亮度，可直接作画。真机实测 4 灰阶刷新会残影，改为按三色（BWR）模式清屏消残影：初始化清一次，之后每 clear_every 次刷新前先清屏再画（默认 clear_every: 1，即每次刷新前都清；0 = 禁用周期性清屏）。

se2417fs051-bw-partial 用 IL0398 的局部刷新序列（微雪 EPD_4IN2_Init_Partial + EPD_4IN2_PartialDisplay），真机确认可用。驱动保留上一帧 buffer，display() 里 diff 出脏矩形，只对变化窗口下发 0x91/0x90/0x10/0x13/0x12。局部刷新仅黑白（红层不参与），适合钟表跳字、计数器、状态角标等小区域更新场景。

以后加新型号：在 display.py 的 MODELS 里加一行（型号名 → 类），并新增一对 epd_<型号>.h / epd_<型号>.cpp（类名 EpdCompat<CamelCase 型号>；声明与实现分离，按型号隔离 git 历史）。

兼容极性 color_map:（可选覆盖）

各型号的兼容极性已内建（见上表「内建 color_map」列），一般无需配置。只有特殊批次与内建不符时，才用 color_map: 显式覆盖：

键	含义
black	BW 平面中代表「黑」的位值（另一值 = 白）
red	红平面中代表「红」的位值（另一值 = 无红）

SE2417FS051 的三色/双色型号（se2417fs051-bwr / -bw）两个颜色平面都比微雪反相，故内建 black: 1、red: 1；局部刷新型号（-bw-partial）无红层、只涉及 BW 平面，4 灰阶型号（-4gray）不使用 color_map。

BUSY 极性（内建 + 可选覆盖）

各型号的 BUSY 忙闲电平已内建（见上表「内建 BUSY」列）：se2417fs051-* 是低电平=忙，其余型号是高电平=忙，一般无需配置。内建极性通过给 busy_pin 的 inverted 设默认值实现——GPIOPin 的反转对组件透明（digital_read() 已返回反转后的逻辑电平），组件代码本身不感知极性。

与 color_map 一样，显式写 busy_pin: {inverted: ...} 即可覆盖内建值，例如：

    busy_pin:
      number: GPIO14
      inverted: false     # 显式覆盖型号内建极性（本例：内建低电平=忙 → 改为高电平=忙）

已对齐微雪例程的时序（固化在驱动里，无需配置）

（以下为 4.2 B V2 三色/双色路径，即 waveshare-4.2-b-v2 与 se2417fs051-bwr / -bw；4 灰阶 se2417fs051-4gray 与局部刷新 se2417fs051-bw-partial 走 IL0398 4Gray / Partial 序列，见 docs/se2417fs051-ic.md）

• 复位 HIGH 200ms → LOW 2ms → HIGH 200ms（对齐 Epd::Reset()）
• 0x04 上电 → 等 BUSY → 0x00 = 0x0F（LUT from OTP）
• 0x12 刷新后 delay(100) 再等 BUSY
• 刷新后不掉电（对齐 Display_old()；掉电只发生在 deep_sleep）
• 全刷超时 30s（基类默认 1s 会误报 "Timeout while displaying image!"）

示例配置（examples/）

文件	用途
examples/se2417fs051-bwr.yaml	SE2417FS051 三色 BWR 冒烟测试（黑/白/红三条竖带）
examples/se2417fs051-bw.yaml	SE2417FS051 双色冒烟测试（左黑 / 右白）
examples/se2417fs051-bw-partial.yaml	SE2417FS051 局部刷新冒烟测试（静态底图 + 底部一条方块循环移动，只刷变化区域）
examples/se2417fs051-4gray.yaml	SE2417FS051 4 灰阶冒烟测试（黑/暗灰/亮灰/白四条竖带）
examples/se2417fs051-grid.yaml	网格测试：400×300 全幅白底 + 红色 1px 外框 + 每 50px 黑网格 + 四角角标 + 中心红十字，用于检查边缘是否被裁剪、画面是否偏移
examples/hink-e042a13-a0-bwr.yaml	HINK-E042A13-A0 三色 BWR 冒烟测试（黑/白/红三条竖带）
examples/hink-e042a13-a0-bw.yaml	HINK-E042A13-A0 双色冒烟测试（左黑 / 右白）
examples/waveshare-2.13-v1-bw.yaml	微雪 2.13inch v1（IL3895，兼容 HINK-E0213A04-G01）双色冒烟测试（左黑 / 右白）
examples/waveshare-2.13-v1-partial.yaml	微雪 2.13inch v1 局部刷新冒烟测试（静态底图 + 底部一条方块循环移动，走局刷 LUT 轻闪烁）
examples/waveshare-2.13-v1-grid.yaml	微雪 2.13inch v1 网格测试：122×250 全幅白底 + 黑色 1px 外框 + 每 50px 黑网格 + 四角角标 + 中心黑十字，用于检查边缘是否被裁剪、画面是否偏移
examples/waveshare-1.54-v1-bw.yaml	微雪 1.54inch v1（SSD1608，兼容 OED OPM016A1）双色冒烟测试（左黑 / 右白）
examples/waveshare-1.54-v1-partial.yaml	微雪 1.54inch v1 局部刷新冒烟测试（静态底图 + 底部一条方块循环移动，走局刷 LUT 轻闪烁）
examples/waveshare-1.54-v1-grid.yaml	微雪 1.54inch v1 网格测试：200×200 全幅白底 + 黑色 1px 外框 + 每 50px 黑网格 + 四角角标 + 中心黑十字

示例均显式声明 id: epaper（供 component.update: epaper 引用），并配手动刷新按钮。全刷时长因型号而异：400×300 的 SE2417FS051 系列约 16s，2.13/1.54 约 2s；*-partial 示例另用 update_interval: 3s 周期驱动方块移动。

许可

派生自 ESPHome 的 waveshare_epaper 组件。ESPHome 采用双许可（见 LICENSE）：

• C++ 源码（components/epd_compat/ 下的 *.h / *.cpp）→ GPLv3
• Python 源码（display.py / __init__.py）→ MIT