"""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 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)