display.py 6.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134
  1. """ESPHome display platform driving a GxEPD2 panel via the native replay
  2. engine (see cycle_engine.h) instead of GxEPD2's own C++ classes.
  3. Panels are selected via `model:`, each backed by an EpdPanelDescriptor
  4. (panel_*.h) generated by the capture emitter - see claude/DESIGN.md.
  5. """
  6. import re
  7. import esphome.codegen as cg
  8. import esphome.config_validation as cv
  9. from esphome import pins
  10. from esphome.components import display, spi
  11. from esphome.const import (
  12. CONF_BUSY_PIN,
  13. CONF_CS_PIN,
  14. CONF_DC_PIN,
  15. CONF_ID,
  16. CONF_LAMBDA,
  17. CONF_MODEL,
  18. CONF_RESET_PIN,
  19. CONF_SPI_ID,
  20. Framework,
  21. )
  22. from esphome.types import ConfigType
  23. CODEOWNERS = ["@zib"]
  24. DEPENDENCIES = ["spi"]
  25. # When true, the 1bpp (mono / BW+accent) draw path treats a *bright* color as
  26. # ink and a *dark* color as background, instead of the literal RGB mapping
  27. # (bright = white = blank). This exists only to ease conversion from
  28. # ESPHome's LCD-rooted color model: its drawing primitives default to
  29. # COLOR_ON = white, so with the literal mapping a default-color it.print()
  30. # draws nothing. We can't tell a defaulted COLOR_ON from an explicit white
  31. # (the default is compiled into the user's lambda as a constant), so the only
  32. # lever is this wholesale mono inversion - the same thing waveshare_epaper
  33. # bakes in. Default false (native, literal RGB); a future waveshare model
  34. # alias will flip the *default* to true, but an explicit setting always wins.
  35. # No effect on 2bpp/4bpp packed panels - there the palette maps literal RGB.
  36. CONF_INVERT_MONO = "invert_mono"
  37. gxepd2_ns = cg.esphome_ns.namespace("gxepd2")
  38. GxEPD2Display = gxepd2_ns.class_("GxEPD2Display", display.DisplayBuffer)
  39. # model name -> (C++ descriptor global declared in the matching panel_*.h
  40. # header - gxepd2_display.h includes them all, so no extra include wiring here;
  41. # Good Display part number on the panel's silkscreen).
  42. #
  43. # The part number, not the GxEPD2 class name, is the source of truth for the
  44. # on-screen label (see _panel_label / test_pattern): GxEPD2's older naming
  45. # style drops the GDEx prefix and the 4-digit size - GxEPD2_213_Z98C is really
  46. # GDEY0213Z98 - so the class name alone can't reconstruct what's on the tag.
  47. MODELS = {
  48. "GxEPD2_154_Z90c": ("PANEL_154_Z90C", "GDEH0154Z90"),
  49. "GxEPD2_213_Z98C": ("PANEL_213_Z98C", "GDEY0213Z98"),
  50. "GxEPD2_213c_GDEY0213F51": ("PANEL_213C_GDEY0213F51", "GDEY0213F51"),
  51. "GxEPD2_213c_GDEY0213F52": ("PANEL_213C_GDEY0213F52", "GDEY0213F52"),
  52. "GxEPD2_426_GDEQ0426T82": ("PANEL_426_GDEQ0426T82", "GDEQ0426T82"),
  53. "GxEPD2_583_GDEQ0583T31": ("PANEL_583_GDEQ0583T31", "GDEQ0583T31"),
  54. "GxEPD2_290c_GDEY029F51": ("PANEL_290C_GDEY029F51", "GDEY029F51"),
  55. "GxEPD2_579c_GDEY0579F51": ("PANEL_579C_GDEY0579F51", "GDEY0579F51"),
  56. # Debug variant: master half only, as if it were a self-contained
  57. # 396x272 panel - see panel_579c_gdey0579f51_master_only.h. Kept
  58. # around as a diagnostic tool, not the panel's real mode. Same physical
  59. # part as the full panel, so same label.
  60. "GxEPD2_579c_GDEY0579F51_MASTER_ONLY": ("PANEL_579C_GDEY0579F51_MASTER_ONLY", "GDEY0579F51"),
  61. }
  62. # Good Display part number -> shelf label: drop the 4-char GDEx series prefix,
  63. # keeping just the size + type (GDEQ0583T31 -> 0583T31, GDEY0213Z98 ->
  64. # 0213Z98). The GDEx series/generation letter encodes nothing we act on and
  65. # costs scarce width on small panels; size stays encoded once, in the digits.
  66. # Anything not starting with GDE<letter> is returned untouched.
  67. def _panel_label(part: str) -> str:
  68. return re.sub(r"^GDE[A-Z]", "", part)
  69. CONFIG_SCHEMA = cv.All(
  70. display.FULL_DISPLAY_SCHEMA.extend(
  71. {
  72. cv.GenerateID(): cv.declare_id(GxEPD2Display),
  73. cv.GenerateID(CONF_SPI_ID): cv.use_id(spi.SPIComponent),
  74. cv.Required(CONF_MODEL): cv.one_of(*MODELS),
  75. cv.Required(CONF_CS_PIN): pins.gpio_output_pin_schema,
  76. cv.Required(CONF_DC_PIN): pins.gpio_output_pin_schema,
  77. cv.Optional(CONF_RESET_PIN): pins.gpio_output_pin_schema,
  78. cv.Optional(CONF_BUSY_PIN): pins.gpio_input_pin_schema,
  79. # No schema default: absence falls to the alias-derived default in
  80. # to_code() (just False today; true for a waveshare alias once that
  81. # lands), while an explicit value always wins.
  82. cv.Optional(CONF_INVERT_MONO): cv.boolean,
  83. }
  84. ),
  85. # The runtime C++ uses only framework-portable ESPHome abstractions, so
  86. # both IDF and ESP32-Arduino are supported. ESP8266-Arduino compiles too
  87. # but is resolution-restricted at 1bpp and lacks the PSRAM that >1bpp
  88. # (color) panels need, so those fail allocation at runtime.
  89. cv.only_with_framework([Framework.ESP_IDF, Framework.ARDUINO]),
  90. )
  91. async def to_code(config: ConfigType) -> None:
  92. var = cg.new_Pvariable(config[CONF_ID])
  93. descriptor, part_number = MODELS[config[CONF_MODEL]]
  94. cg.add(var.set_descriptor(cg.RawExpression(f"&esphome::gxepd2::{descriptor}")))
  95. cg.add(var.set_cs_pin(await cg.gpio_pin_expression(config[CONF_CS_PIN])))
  96. cg.add(var.set_dc_pin(await cg.gpio_pin_expression(config[CONF_DC_PIN])))
  97. if reset_pin := config.get(CONF_RESET_PIN):
  98. cg.add(var.set_reset_pin(await cg.gpio_pin_expression(reset_pin)))
  99. if busy_pin := config.get(CONF_BUSY_PIN):
  100. cg.add(var.set_busy_pin(await cg.gpio_pin_expression(busy_pin)))
  101. spi_parent = await cg.get_variable(config[CONF_SPI_ID])
  102. cg.add(var.set_spi_parent(spi_parent))
  103. # Alias-derived default is just False for now; the waveshare-compat layer
  104. # will compute it from the (aliased) model. An explicit invert_mono wins.
  105. cg.add(var.set_invert_mono(config.get(CONF_INVERT_MONO, False)))
  106. # Panel label for test_pattern(): the Good Display part number minus its
  107. # series prefix (GDEQ0583T31 -> 0583T31), so a tested panel shows what it
  108. # is on the shelf, not the GxEPD2 C++ class id.
  109. cg.add(var.set_model_name(_panel_label(part_number)))
  110. # A top-level `lambda:` must be processed and attached via set_writer()
  111. # here - register_display() only wires up `pages:` (same pattern as every
  112. # other display component's to_code(), e.g. epaper_spi).
  113. if CONF_LAMBDA in config:
  114. lambda_ = await cg.process_lambda(config[CONF_LAMBDA], [(display.DisplayRef, "it")], return_type=cg.void)
  115. cg.add(var.set_writer(lambda_))
  116. await display.register_display(var, config)