gxepd2_display.h 9.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216
  1. #pragma once
  2. #include "esphome/core/component.h"
  3. #include "esphome/core/helpers.h"
  4. #include "esphome/components/display/display_buffer.h"
  5. #include "esphome/components/spi/spi.h"
  6. #include "cycle_engine.h"
  7. #include "panel_213_z98c.h"
  8. #include "panel_290c_gdey029f51.h"
  9. #include "panel_426_gdeq0426t82.h"
  10. #include "panel_579c_gdey0579f51.h"
  11. #include "panel_579c_gdey0579f51_master_only.h"
  12. #include "panel_583_gdeq0583t31.h"
  13. namespace esphome::gxepd2 {
  14. static const char *const TAG = "gxepd2";
  15. // Native chunked-engine replacement for the old GxEPD2-template/FreeRTOS-task
  16. // component - see the plan this was built from (and project memory entry
  17. // gxepd2_task_watchdog_status) for why. Panels arrive as hand-written
  18. // (later, extracted) descriptors selected at runtime via set_descriptor(),
  19. // not by templating this class over GxEPD2's own driver classes.
  20. class GxEPD2Display : public display::DisplayBuffer {
  21. public:
  22. void set_cs_pin(GPIOPin *pin) { this->cs_ = pin; }
  23. void set_dc_pin(GPIOPin *pin) { this->dc_ = pin; }
  24. void set_reset_pin(GPIOPin *pin) { this->rst_ = pin; }
  25. void set_busy_pin(GPIOPin *pin) { this->busy_ = pin; }
  26. void set_spi_parent(spi::SPIComponent *parent) { this->spi_.set_spi_parent(parent); }
  27. void set_descriptor(const EpdPanelDescriptor *desc) { this->desc_ = desc; }
  28. void set_invert_mono(bool invert) { this->invert_mono_ = invert; }
  29. void setup() override {
  30. const auto *desc = this->desc_;
  31. // window_per_plane panels (GDEY0579F51's master+slave) size each
  32. // plane's own buffer from plane_width (each region's own local
  33. // width), not the descriptor's overall width (the full logical canvas
  34. // ESPHome draws into) - both regions are the same size here, so one
  35. // plane_bytes_ value covers both buffers.
  36. uint32_t w = desc->window_per_plane ? desc->plane_width : desc->width;
  37. // width*height*bpp/8: /8 at 1bpp, /4 at 2bpp (4-color), /2 at 4bpp (7-color).
  38. this->plane_bytes_ = (uint32_t) w * desc->height * desc->bits_per_pixel / 8;
  39. RAMAllocator<uint8_t> allocator;
  40. this->plane0_ = allocator.allocate(this->plane_bytes_);
  41. bool need_plane1 = desc->plane_count > 1;
  42. this->plane1_ = need_plane1 ? allocator.allocate(this->plane_bytes_) : nullptr;
  43. if (this->plane0_ == nullptr || (need_plane1 && this->plane1_ == nullptr)) {
  44. ESP_LOGE(TAG, "Failed to allocate %u-byte plane buffer(s)", (unsigned) this->plane_bytes_);
  45. this->mark_failed();
  46. return;
  47. }
  48. if (desc->bits_per_pixel > 1) {
  49. // Packed modes: clear every pixel to the panel's white/blank code,
  50. // replicated across the byte - e.g. 4-color white=0x01 -> 0x55, 7-color
  51. // white=0x01 -> 0x11, matching GxEPD2's own writeScreenBuffer() fill
  52. // (color4()*0x55 / color7()|<<4). Both regions of a window_per_plane
  53. // panel (master/slave) get the same blank fill.
  54. uint8_t fill = replicate_code_(desc->blank_code, desc->bits_per_pixel);
  55. memset(this->plane0_, fill, this->plane_bytes_);
  56. if (this->plane1_ != nullptr)
  57. memset(this->plane1_, fill, this->plane_bytes_);
  58. } else {
  59. // 1bpp plane model: plane0 white = all bits set (0xFF); plane1 (the
  60. // accent/red plane, when present) = 0 = not-red.
  61. memset(this->plane0_, 0xFF, this->plane_bytes_);
  62. if (this->plane1_ != nullptr)
  63. memset(this->plane1_, 0x00, this->plane_bytes_);
  64. }
  65. this->spi_.spi_setup();
  66. this->engine_.begin(desc, this->cs_, this->dc_, this->rst_, this->busy_, &this->spi_);
  67. }
  68. // Arms the state machine and returns immediately - the real several-
  69. // seconds-long write/refresh/busy-wait cycle happens across many
  70. // subsequent loop() ticks, not before this call returns.
  71. void update() override {
  72. if (!this->engine_.idle()) {
  73. ESP_LOGW(TAG, "Skipping update: previous display refresh is still running");
  74. return;
  75. }
  76. this->do_update_();
  77. this->engine_.request_full_update(this->plane0_, this->plane1_);
  78. }
  79. void loop() override { this->engine_.step(); }
  80. void dump_config() override {
  81. ESP_LOGCONFIG(TAG, "GxEPD2 Display:");
  82. ESP_LOGCONFIG(TAG, " Dimensions: %ux%u", (unsigned) this->desc_->width, (unsigned) this->desc_->height);
  83. ESP_LOGCONFIG(TAG, " Bits/pixel: %u (%s)", (unsigned) this->desc_->bits_per_pixel,
  84. this->desc_->bits_per_pixel == 1 ? "mono/plane" : "packed palette");
  85. ESP_LOGCONFIG(TAG, " Planes/regions: %u", (unsigned) this->desc_->plane_count);
  86. ESP_LOGCONFIG(TAG, " Busy active level: %s", this->desc_->busy_active_level ? "HIGH" : "LOW");
  87. if (this->desc_->bits_per_pixel == 1)
  88. ESP_LOGCONFIG(TAG, " invert_mono: %s", YESNO(this->invert_mono_));
  89. LOG_UPDATE_INTERVAL(this);
  90. }
  91. display::DisplayType get_display_type() override { return display::DisplayType::DISPLAY_TYPE_COLOR; }
  92. protected:
  93. // Replicates a packed wire code across a whole byte (one code per pixel
  94. // slot), e.g. 2bpp code 0x01 -> 0x55, 4bpp code 0x01 -> 0x11.
  95. static uint8_t replicate_code_(uint8_t code, uint8_t bpp) {
  96. uint8_t mask = static_cast<uint8_t>((1u << bpp) - 1);
  97. uint8_t out = 0;
  98. for (uint8_t i = 0; i < 8 / bpp; i++)
  99. out = static_cast<uint8_t>((out << bpp) | (code & mask));
  100. return out;
  101. }
  102. // Maps a drawn RGB color to its panel wire code via the descriptor's
  103. // palette: exact matches win (so named colors are deterministic, like
  104. // GxEPD2's color4()/color7() switch), otherwise nearest in RGB space.
  105. static uint8_t classify_(Color c, const EpdPaletteEntry *pal, uint8_t len) {
  106. if (pal == nullptr || len == 0)
  107. return 0;
  108. uint8_t best = 0;
  109. long best_d = -1;
  110. for (uint8_t i = 0; i < len; i++) {
  111. long dr = static_cast<long>(c.red) - pal[i].r;
  112. long dg = static_cast<long>(c.green) - pal[i].g;
  113. long db = static_cast<long>(c.blue) - pal[i].b;
  114. long d = dr * dr + dg * dg + db * db;
  115. if (d == 0)
  116. return pal[i].code;
  117. if (best_d < 0 || d < best_d) {
  118. best_d = d;
  119. best = i;
  120. }
  121. }
  122. return pal[best].code;
  123. }
  124. // Packed code-per-pixel model (bits_per_pixel > 1): N bits/pixel, MSB
  125. // first, matching GxEPD2's own out_data packing in writeImage (4-color
  126. // 4px/byte, 7-color 2px/byte). Routes to the correct region for a
  127. // window_per_plane (master/slave) panel the same way the mono path does.
  128. void draw_packed_(int x, int y, Color color) {
  129. const uint8_t bpp = this->desc_->bits_per_pixel;
  130. uint8_t code = classify_(color, this->desc_->palette, this->desc_->palette_len);
  131. uint16_t stride = this->desc_->width;
  132. uint8_t *buf = this->plane0_;
  133. int local_x = x;
  134. if (this->desc_->window_per_plane && this->desc_->plane_count > 1) {
  135. stride = this->desc_->plane_width;
  136. if (x >= stride) {
  137. buf = this->plane1_;
  138. local_x = x - stride;
  139. }
  140. }
  141. uint32_t px = static_cast<uint32_t>(y) * stride + local_x;
  142. const uint8_t ppb = 8 / bpp;
  143. uint32_t idx = px / ppb;
  144. uint8_t shift = static_cast<uint8_t>((ppb - 1 - (px % ppb)) * bpp);
  145. uint8_t mask = static_cast<uint8_t>((1u << bpp) - 1);
  146. buf[idx] = static_cast<uint8_t>((buf[idx] & ~(mask << shift)) | ((code & mask) << shift));
  147. }
  148. void draw_absolute_pixel_internal(int x, int y, Color color) override {
  149. if (x < 0 || y < 0 || x >= this->desc_->width || y >= this->desc_->height)
  150. return;
  151. if (this->desc_->bits_per_pixel > 1) {
  152. this->draw_packed_(x, y, color);
  153. return;
  154. }
  155. bool red = color.red > color.green && color.red > color.blue && color.red > 0x7f;
  156. bool bright = color.red > 0x7f || color.green > 0x7f || color.blue > 0x7f;
  157. uint32_t idx = (static_cast<uint32_t>(y) * this->desc_->width + x) / 8;
  158. uint8_t mask = 0x80 >> (x % 8);
  159. // Same classification the old task-based component used: red/accent
  160. // pixels go to the color plane (when the panel has one), everything
  161. // else is black/white on the black plane. get_display_type() reports
  162. // DISPLAY_TYPE_COLOR, so callers draw literal RGB colors, not the
  163. // on/off is_on() convention, even on a plane_count==1 (BW-only) panel -
  164. // there just is no color plane for a "red" classification to land on.
  165. //
  166. // Buffer convention here is 1=red/0=not-red (matching the reference
  167. // epaper_spi driver's EPaperWeAct3C internal convention), transformed
  168. // to the wire value by plane_invert[1] - see PANEL_213_Z98C's comment
  169. // for why that inversion flag and this buffer convention are coupled,
  170. // not independent facts.
  171. if (red && this->plane1_ != nullptr) {
  172. this->plane1_[idx] |= mask;
  173. } else {
  174. if (this->plane1_ != nullptr)
  175. this->plane1_[idx] &= ~mask;
  176. // plane0 bit set = white/blank. invert_mono_ flips the mono sense so a
  177. // bright color (e.g. ESPHome's default COLOR_ON) becomes ink, not blank
  178. // - see display.py's CONF_INVERT_MONO. Red classification is unaffected.
  179. if (bright ^ this->invert_mono_) {
  180. this->plane0_[idx] |= mask;
  181. } else {
  182. this->plane0_[idx] &= ~mask;
  183. }
  184. }
  185. }
  186. int get_width_internal() override { return this->desc_->width; }
  187. int get_height_internal() override { return this->desc_->height; }
  188. const EpdPanelDescriptor *desc_{nullptr};
  189. GPIOPin *cs_{nullptr};
  190. GPIOPin *dc_{nullptr};
  191. GPIOPin *rst_{nullptr};
  192. GPIOPin *busy_{nullptr};
  193. EpdSPIDevice spi_;
  194. CycleEngine engine_;
  195. uint8_t *plane0_{nullptr};
  196. uint8_t *plane1_{nullptr};
  197. uint32_t plane_bytes_{0};
  198. bool invert_mono_{false};
  199. };
  200. } // namespace esphome::gxepd2