GxEPD2-esphome/components/gxepd2/display.py

"""ESPHome display platform driving a GxEPD2 panel via the native replay
engine (see cycle_engine.h) instead of GxEPD2's own C++ classes.

Panels are selected via `model:`, each backed by an EpdPanelDescriptor
(panel_*.h) generated by the capture emitter - see CONTRIBUTING.md.
"""

import re
from collections import namedtuple

import esphome.codegen as cg
import esphome.config_validation as cv
from esphome import pins
from esphome.components import display, spi
from esphome.const import (
    CONF_BUSY_PIN,
    CONF_CS_PIN,
    CONF_DC_PIN,
    CONF_ID,
    CONF_LAMBDA,
    CONF_MODEL,
    CONF_RESET_PIN,
    CONF_SPI_ID,
    Framework,
)
from esphome.types import ConfigType

CODEOWNERS = ["@zib"]
DEPENDENCIES = ["spi"]

# When true, the 1bpp (mono / BW+accent) draw path treats a *bright* color as
# ink and a *dark* color as background, instead of the literal RGB mapping
# (bright = white = blank). This exists only to ease conversion from
# ESPHome's LCD-rooted color model: its drawing primitives default to
# COLOR_ON = white, so with the literal mapping a default-color it.print()
# draws nothing. We can't tell a defaulted COLOR_ON from an explicit white
# (the default is compiled into the user's lambda as a constant), so the only
# lever is this wholesale mono inversion - the same thing waveshare_epaper
# bakes in. Default false (native, literal RGB); a future waveshare model
# alias will flip the *default* to true, but an explicit setting always wins.
# No effect on 2bpp/4bpp packed panels - there the palette maps literal RGB.
CONF_INVERT_MONO = "invert_mono"

# Compiles in GxEPD2Display's dev-time diagnostic methods (currently
# diag_update_no_reset() - see gxepd2_display.h), stashed behind this flag so
# a production build doesn't pay flash for bench-only tooling. Off by
# default; set true only on the device you're actively debugging.
CONF_DIAGNOSTICS = "diagnostics"

gxepd2_ns = cg.esphome_ns.namespace("gxepd2")
GxEPD2Display = gxepd2_ns.class_("GxEPD2Display", display.DisplayBuffer)

# The panel registry - the single source of truth for which panels ship, their
# metadata, and whether each is hardware-verified. tools/panel_table.py renders
# the supported-panels table from this, and set_verified() surfaces the status
# in the device's boot log.
#
# descriptor: the C++ EpdPanelDescriptor global declared in the matching
#   panel_*.h (all `#include`d by gxepd2_display.h, so no extra wiring here).
# part: the Good Display part number on the silkscreen - the source of truth for
#   the on-screen label (GxEPD2's class name drops the GDEx prefix and size, so
#   GxEPD2_213_Z98C alone can't reconstruct GDEY0213Z98).
# status: "verified" (rendered correctly on real hardware), "structural"
#   (descriptor captured and compiles, not yet bench-confirmed), or "diagnostic".
Panel = namedtuple("Panel", "descriptor part controller fmt status")

PANELS = {
    "GxEPD2_154_Z90c": Panel("PANEL_154_Z90C", "GDEH0154Z90", "SSD1681", "3-color", "verified"),
    "GxEPD2_213_B72": Panel("PANEL_213_B72", "GDEH0213B72", "SSD1675A", "mono", "structural"),
    "GxEPD2_213_Z98C": Panel("PANEL_213_Z98C", "GDEY0213Z98", "SSD1680", "3-color", "verified"),
    "GxEPD2_213c_GDEY0213F51": Panel("PANEL_213C_GDEY0213F51", "GDEY0213F51", "JD79661", "4-color", "structural"),
    "GxEPD2_213c_GDEY0213F52": Panel("PANEL_213C_GDEY0213F52", "GDEY0213F52", "JD79676", "4-color", "verified"),
    "GxEPD2_270": Panel("PANEL_270", "GDEW027W3", "EK79652", "mono", "structural"),
    "GxEPD2_290_T5D": Panel("PANEL_290_T5D", "GDEW029T5D", "UC8151D", "mono", "structural"),
    "GxEPD2_420": Panel("PANEL_420", "GDEW042T2", "UC8176", "mono", "structural"),
    "GxEPD2_426_GDEQ0426T82": Panel("PANEL_426_GDEQ0426T82", "GDEQ0426T82", "SSD1677", "mono", "verified"),
    "GxEPD2_583": Panel("PANEL_583", "GDEW0583T7", "UC8159c", "mono", "structural"),
    "GxEPD2_583_GDEQ0583T31": Panel("PANEL_583_GDEQ0583T31", "GDEQ0583T31", "UC8179", "mono", "verified"),
    "GxEPD2_730c_GDEP073E01": Panel("PANEL_730C_GDEP073E01", "GDEP073E01", "unknown", "7-color", "verified"),
    "GxEPD2_750_GDEY075T7": Panel("PANEL_750_GDEY075T7", "GDEY075T7", "UC8179", "mono", "verified"),
    "GxEPD2_290c_GDEY029F51": Panel("PANEL_290C_GDEY029F51", "GDEY029F51", "JD79667", "4-color", "structural"),
    "GxEPD2_579c_GDEY0579F51": Panel("PANEL_579C_GDEY0579F51", "GDEY0579F51", "HX8717", "4-color", "verified"),
    "GxEPD2_154": Panel("PANEL_154", "TODO", "TODO", "mono", "structural"),
    "GxEPD2_1020_GDEM102T91": Panel("PANEL_1020_GDEM102T91", "GDEM102T91", "TODO", "mono", "structural"),
    "GxEPD2_266_BN": Panel("PANEL_266_BN", "TODO", "TODO", "mono", "structural"),
    "GxEPD2_102": Panel("PANEL_102", "GDEW0102T4", "UC8175", "mono", "structural"),
    "GxEPD2_1160_T91": Panel("PANEL_1160_T91", "GDEH116T91", "TODO", "mono", "structural"),
    "GxEPD2_1330_GDEM133T91": Panel("PANEL_1330_GDEM133T91", "GDEM133T91", "TODO", "mono", "structural"),
    "GxEPD2_150_BN": Panel("PANEL_150_BN", "TODO", "TODO", "mono", "structural"),
    "GxEPD2_154_D67": Panel("PANEL_154_D67", "GDEH0154D67", "TODO", "mono", "structural"),
    "GxEPD2_154_GDEY0154D67": Panel("PANEL_154_GDEY0154D67", "GDEY0154D67", "TODO", "mono", "structural"),
    "GxEPD2_154_M09": Panel("PANEL_154_M09", "GDEW0154M09", "TODO", "mono", "structural"),
    "GxEPD2_154_M10": Panel("PANEL_154_M10", "GDEW0154M10", "TODO", "mono", "structural"),
    "GxEPD2_154_T8": Panel("PANEL_154_T8", "GDEW0154T8", "IL0373", "mono", "structural"),
    "GxEPD2_213": Panel("PANEL_213", "TODO", "IL3895", "mono", "structural"),
    "GxEPD2_213_B73": Panel("PANEL_213_B73", "GDEH0213B73", "SSD1675B", "mono", "structural"),
    "GxEPD2_213_B74": Panel("PANEL_213_B74", "GDEM0213B74", "TODO", "mono", "structural"),
    "GxEPD2_213_BN": Panel("PANEL_213_BN", "TODO", "TODO", "mono", "structural"),
    "GxEPD2_213_GDEY0213B74": Panel("PANEL_213_GDEY0213B74", "GDEY0213B74", "TODO", "mono", "structural"),
    "GxEPD2_213_M21": Panel("PANEL_213_M21", "TODO", "UC8151", "mono", "structural"),
    "GxEPD2_213_T5D": Panel("PANEL_213_T5D", "TODO", "UC8151D", "mono", "structural"),
    "GxEPD2_213_flex": Panel("PANEL_213_FLEX", "TODO", "IL0373", "mono", "structural"),
    "GxEPD2_260": Panel("PANEL_260", "GDEW026T0", "IL0373", "mono", "structural"),
    "GxEPD2_260_M01": Panel("PANEL_260_M01", "TODO", "UC8151", "mono", "structural"),
    "GxEPD2_270_GDEY027T91": Panel("PANEL_270_GDEY027T91", "GDEY027T91", "TODO", "mono", "structural"),
    "GxEPD2_290": Panel("PANEL_290", "TODO", "IL3820", "mono", "structural"),
    "GxEPD2_290_BS": Panel("PANEL_290_BS", "TODO", "TODO", "mono", "structural"),
    "GxEPD2_290_GDEY029T71H": Panel("PANEL_290_GDEY029T71H", "GDEY029T71H", "TODO", "mono", "structural"),
    "GxEPD2_290_GDEY029T94": Panel("PANEL_290_GDEY029T94", "GDEY029T94", "TODO", "mono", "structural"),
    "GxEPD2_290_I6FD": Panel("PANEL_290_I6FD", "GDEW029I6FD", "UC8151D", "mono", "structural"),
    "GxEPD2_290_M06": Panel("PANEL_290_M06", "TODO", "UC8151D", "mono", "structural"),
    "GxEPD2_290_T5": Panel("PANEL_290_T5", "TODO", "IL0373", "mono", "structural"),
    "GxEPD2_290_T94": Panel("PANEL_290_T94", "GDEM029T94", "TODO", "mono", "structural"),
    "GxEPD2_290_T94_V2": Panel("PANEL_290_T94_V2", "GDEM029T94", "TODO", "mono", "structural"),
    "GxEPD2_310_GDEQ031T10": Panel("PANEL_310_GDEQ031T10", "GDEQ031T10", "UC8253", "mono", "structural"),
    "GxEPD2_370_TC1": Panel("PANEL_370_TC1", "TODO", "TODO", "mono", "structural"),
    "GxEPD2_371": Panel("PANEL_371", "GDEW0371W7", "IL0324", "mono", "structural"),
    "GxEPD2_397_GDEM0397T81": Panel("PANEL_397_GDEM0397T81", "GDEM0397T81", "TODO", "mono", "structural"),
    "GxEPD2_420_GDEY042T81": Panel("PANEL_420_GDEY042T81", "GDEY042T81", "TODO", "mono", "structural"),
    "GxEPD2_420_GYE042A87": Panel("PANEL_420_GYE042A87", "TODO", "TODO", "mono", "structural"),
    "GxEPD2_420_M01": Panel("PANEL_420_M01", "TODO", "UC8176", "mono", "structural"),
    "GxEPD2_420_SE0420NQ04": Panel("PANEL_420_SE0420NQ04", "TODO", "UC8276C", "mono", "structural"),
    "GxEPD2_576_GDEH0576T81_BW": Panel("PANEL_576_GDEH0576T81_BW", "GDEH0576T81", "SSD2677", "mono", "structural"),
    "GxEPD2_576_GDEH0576T81_BW_SHM": Panel("PANEL_576_GDEH0576T81_BW_SHM", "GDEH0576T81", "SSD2677", "mono", "structural"),
    "GxEPD2_579_GDEY0579T93": Panel("PANEL_579_GDEY0579T93", "GDEY0579T93", "TODO", "mono", "structural"),
    "GxEPD2_583_T8": Panel("PANEL_583_T8", "GDEW0583T8", "GD7965", "mono", "structural"),
    "GxEPD2_750": Panel("PANEL_750", "TODO", "IL0371", "mono", "structural"),
    "GxEPD2_750_T7": Panel("PANEL_750_T7", "GDEW075T7", "GD7965", "mono", "structural"),
}


# Good Display part number -> shelf label: drop the 4-char GDEx series prefix,
# keeping just the size + type (GDEQ0583T31 -> 0583T31, GDEY0213Z98 ->
# 0213Z98). The GDEx series/generation letter encodes nothing we act on and
# costs scarce width on small panels; size stays encoded once, in the digits.
# Anything not starting with GDE<letter> is returned untouched.
def _panel_label(part: str) -> str:
    return re.sub(r"^GDE[A-Z]", "", part)

CONFIG_SCHEMA = cv.All(
    display.FULL_DISPLAY_SCHEMA.extend(
        {
            cv.GenerateID(): cv.declare_id(GxEPD2Display),
            cv.GenerateID(CONF_SPI_ID): cv.use_id(spi.SPIComponent),
            cv.Required(CONF_MODEL): cv.one_of(*PANELS),
            cv.Required(CONF_CS_PIN): pins.gpio_output_pin_schema,
            cv.Required(CONF_DC_PIN): pins.gpio_output_pin_schema,
            cv.Optional(CONF_RESET_PIN): pins.gpio_output_pin_schema,
            cv.Optional(CONF_BUSY_PIN): pins.gpio_input_pin_schema,
            # No schema default: absence falls to the alias-derived default in
            # to_code() (just False today; true for a waveshare alias once that
            # lands), while an explicit value always wins.
            cv.Optional(CONF_INVERT_MONO): cv.boolean,
            cv.Optional(CONF_DIAGNOSTICS, default=False): cv.boolean,
        }
    ),
    # The runtime C++ uses only framework-portable ESPHome abstractions, so
    # both IDF and ESP32-Arduino are supported. ESP8266-Arduino compiles too
    # but is resolution-restricted at 1bpp and lacks the PSRAM that >1bpp
    # (color) panels need, so those fail allocation at runtime.
    cv.only_with_framework([Framework.ESP_IDF, Framework.ARDUINO]),
)


async def to_code(config: ConfigType) -> None:
    var = cg.new_Pvariable(config[CONF_ID])

    panel = PANELS[config[CONF_MODEL]]
    cg.add(var.set_descriptor(cg.RawExpression(f"&esphome::gxepd2::{panel.descriptor}")))
    cg.add(var.set_cs_pin(await cg.gpio_pin_expression(config[CONF_CS_PIN])))
    cg.add(var.set_dc_pin(await cg.gpio_pin_expression(config[CONF_DC_PIN])))
    if reset_pin := config.get(CONF_RESET_PIN):
        cg.add(var.set_reset_pin(await cg.gpio_pin_expression(reset_pin)))
    if busy_pin := config.get(CONF_BUSY_PIN):
        cg.add(var.set_busy_pin(await cg.gpio_pin_expression(busy_pin)))

    spi_parent = await cg.get_variable(config[CONF_SPI_ID])
    cg.add(var.set_spi_parent(spi_parent))

    # Alias-derived default is just False for now; the waveshare-compat layer
    # will compute it from the (aliased) model. An explicit invert_mono wins.
    cg.add(var.set_invert_mono(config.get(CONF_INVERT_MONO, False)))

    # Panel label for test_pattern(): the Good Display part number minus its
    # series prefix (GDEQ0583T31 -> 0583T31), so a tested panel shows what it
    # is on the shelf, not the GxEPD2 C++ class id.
    cg.add(var.set_model_name(_panel_label(panel.part)))
    cg.add(var.set_verified(panel.status == "verified"))

    # Compiles in GxEPD2Display/CycleEngine's dev-time diagnostic methods -
    # see CONF_DIAGNOSTICS above. Not set at all (not just defined false) for
    # every other build, so a production build's flash never sees them.
    if config[CONF_DIAGNOSTICS]:
        cg.add_define("USE_GXEPD2_DIAGNOSTICS")

    # A top-level `lambda:` must be processed and attached via set_writer()
    # here - register_display() only wires up `pages:` (same pattern as every
    # other display component's to_code(), e.g. epaper_spi).
    if CONF_LAMBDA in config:
        lambda_ = await cg.process_lambda(config[CONF_LAMBDA], [(display.DisplayRef, "it")], return_type=cg.void)
        cg.add(var.set_writer(lambda_))

    await display.register_display(var, config)