gxepd2_display.h 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446
  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_bn.h"
  8. #include "panel_213_b74.h"
  9. #include "panel_213_b73.h"
  10. #include "panel_213.h"
  11. #include "panel_154_t8.h"
  12. #include "panel_154_m10.h"
  13. #include "panel_154_m09.h"
  14. #include "panel_154_gdey0154d67.h"
  15. #include "panel_154_d67.h"
  16. #include "panel_150_bn.h"
  17. #include "panel_1330_gdem133t91.h"
  18. #include "panel_1160_t91.h"
  19. #include "panel_102.h"
  20. #include "panel_266_bn.h"
  21. #include "panel_1020_gdem102t91.h"
  22. #include "panel_154.h"
  23. #include "panel_154_z90c.h"
  24. #include "panel_213_b72.h"
  25. #include "panel_213_z98c.h"
  26. #include "panel_213c_gdey0213f51.h"
  27. #include "panel_213c_gdey0213f52.h"
  28. #include "panel_270.h"
  29. #include "panel_290_t5d.h"
  30. #include "panel_290c_gdey029f51.h"
  31. #include "panel_420.h"
  32. #include "panel_426_gdeq0426t82.h"
  33. #include "panel_579c_gdey0579f51.h"
  34. #include "panel_579c_gdey0579f51_master_only.h"
  35. #include "panel_583.h"
  36. #include "panel_583_gdeq0583t31.h"
  37. #include "panel_730c_gdep073e01.h"
  38. #include "panel_750_gdey075t7.h"
  39. namespace esphome::gxepd2 {
  40. static const char *const TAG = "gxepd2";
  41. // ESPHome display component for a GxEPD2 panel. Panels arrive as
  42. // EpdPanelDescriptors selected at runtime via set_descriptor() and driven by
  43. // CycleEngine, not by templating this class over GxEPD2's own driver classes.
  44. class GxEPD2Display : public display::DisplayBuffer {
  45. public:
  46. void set_cs_pin(GPIOPin *pin) { this->cs_ = pin; }
  47. void set_dc_pin(GPIOPin *pin) { this->dc_ = pin; }
  48. void set_reset_pin(GPIOPin *pin) { this->rst_ = pin; }
  49. void set_busy_pin(GPIOPin *pin) { this->busy_ = pin; }
  50. void set_spi_parent(spi::SPIComponent *parent) { this->spi_.set_spi_parent(parent); }
  51. void set_descriptor(const EpdPanelDescriptor *desc) { this->desc_ = desc; }
  52. void set_invert_mono(bool invert) { this->invert_mono_ = invert; }
  53. // The short panel label (e.g. "GDEQ0583T31") test_pattern() can print,
  54. // derived from model: in display.py.
  55. void set_model_name(const char *name) { this->model_name_ = name; }
  56. // Whether this panel's descriptor is confirmed on real hardware (vs captured
  57. // but not yet bench-verified) - surfaced in dump_config(). From display.py.
  58. void set_verified(bool v) { this->verified_ = v; }
  59. // Bench visual-check pattern, bit-depth aware. Everything scales to what
  60. // THIS panel can actually show (see test_colors_): the color-bar count,
  61. // the ladder color cycle and the corner markers all follow the panel's
  62. // real color set instead of a hardcoded 4, so the drawn pattern doubles as
  63. // a statement of what the driver expects of the panel. Adds a dithered grey
  64. // ramp so a 1bpp panel shows a graded sweep, not just two flat blocks.
  65. //
  66. // Pass a font to label the panel with its model (and the panel can spare the
  67. // room); pass nothing to skip the label - handy when you just want a quick
  68. // pattern without defining a font. From the display lambda:
  69. // id(<display_id>).test_pattern(); // no label
  70. // id(<display_id>).test_pattern(id(<font_id>)); // labelled
  71. void test_pattern(display::BaseFont *font = nullptr) {
  72. const int w = this->get_width();
  73. const int h = this->get_height();
  74. Color colors[8];
  75. const int n = this->test_colors_(colors, 8);
  76. this->fill(Color(0xFF, 0xFF, 0xFF));
  77. const int smin = w < h ? w : h;
  78. const int border = smin / 100 > 1 ? smin / 100 : 1;
  79. const int x0 = border;
  80. int y0 = border;
  81. const int iw = w - 2 * border;
  82. int ih = h - 2 * border;
  83. // Name band, above every test zone. Drawn only when a font was passed and
  84. // the panel is tall enough to give it a fifth of the interior without
  85. // crowding the zones below.
  86. if (font != nullptr && this->model_name_ != nullptr && this->model_name_[0] != '\0') {
  87. int tw, xoff, baseline, th;
  88. font->measure(this->model_name_, &tw, &xoff, &baseline, &th);
  89. const int band = th + 4;
  90. if (band <= ih / 5) {
  91. this->print(w / 2, y0 + band / 2, font, Color(0x00, 0x00, 0x00), display::TextAlign::CENTER, this->model_name_);
  92. y0 += band;
  93. ih -= band;
  94. }
  95. }
  96. // Vertical budget for the four zones below any name band.
  97. const int bars_h = ih * 34 / 100;
  98. int dither_h = ih * 12 / 100;
  99. if (dither_h < 8) dither_h = 8;
  100. const int row_h = ih * 18 / 100 > 2 ? ih * 18 / 100 : 2;
  101. const int dy = y0 + bars_h;
  102. const int ry = dy + dither_h;
  103. const int col_y = ry + row_h;
  104. const int col_h = (y0 + ih) - col_y;
  105. // Color bars: one solid block per available color, in palette/wire-code
  106. // order (black, white, then the accents). A wrong or missing block
  107. // points straight at the color - or the wire code - it stands for.
  108. const int bar_w = iw / n;
  109. for (int i = 0; i < n; i++) {
  110. const int bx = x0 + i * bar_w;
  111. const int bw = (i == n - 1) ? (x0 + iw - bx) : bar_w;
  112. this->filled_rectangle(bx, y0, bw, bars_h, colors[i]);
  113. }
  114. // Dithered grey ramp: brightness 255 (left) -> 0 (right) via an ordered
  115. // 4x4 Bayer threshold. On a 1bpp panel this is the only zone that shows
  116. // a graded sweep; on deeper panels it's a quick mono/uniformity check.
  117. static const uint8_t BAYER4[4][4] = {
  118. {0, 8, 2, 10}, {12, 4, 14, 6}, {3, 11, 1, 9}, {15, 7, 13, 5}};
  119. for (int yy = 0; yy < dither_h; yy++) {
  120. for (int xx = 0; xx < iw; xx++) {
  121. const int bright = (iw <= 1) ? 255 : 255 - xx * 255 / (iw - 1);
  122. const int thr = (BAYER4[yy & 3][xx & 3] * 2 + 1) * 255 / 32;
  123. if (bright <= thr)
  124. this->draw_pixel_at(x0 + xx, dy + yy, Color(0x00, 0x00, 0x00));
  125. }
  126. }
  127. // Row ladder: 1px rows cycling the full color set - a dropped, doubled
  128. // or reordered row breaks the N-row cadence.
  129. for (int yy = 0; yy < row_h; yy++)
  130. this->horizontal_line(x0, ry + yy, iw, colors[yy % n]);
  131. // Column ladder: the same rotated 90 degrees, catching nibble/column
  132. // order bugs the row ladder can't (packed formats put several pixels per
  133. // byte, so a column-order fault can leave every row looking fine).
  134. for (int xx = 0; xx < iw; xx++)
  135. this->vertical_line(x0 + xx, col_y, col_h, colors[xx % n]);
  136. // Corner markers for orientation, using the panel's ink colors (every
  137. // color but white). BL is always black; TL/TR take the next inks when
  138. // the panel has them; BR is left blank as the distinct "no marker"
  139. // state. A 90/180 rotation or mirror can't survive this even though the
  140. // bars and ladders are otherwise symmetric.
  141. Color ink[8];
  142. int ni = 0;
  143. for (int i = 0; i < n; i++) {
  144. if (colors[i].red == 0xFF && colors[i].green == 0xFF && colors[i].blue == 0xFF)
  145. continue; // skip white - a white marker is invisible
  146. ink[ni++] = colors[i];
  147. }
  148. const int mk = smin / 12 > 3 ? smin / 12 : 3;
  149. if (ni > 0) this->filled_rectangle(x0, y0 + ih - mk, mk, mk, ink[0]); // BL
  150. if (ni > 1) this->filled_rectangle(x0, y0, mk, mk, ink[1]); // TL
  151. if (ni > 2) this->filled_rectangle(x0 + iw - mk, y0, mk, mk, ink[2]); // TR
  152. // Corner-to-corner diagonals over everything: the cheapest coordinate-
  153. // transform check - a clean line means no row/column reordering.
  154. this->line(0, 0, w - 1, h - 1, Color(0x00, 0x00, 0x00));
  155. this->line(w - 1, 0, 0, h - 1, Color(0x00, 0x00, 0x00));
  156. // Border frame last, so it stays an unbroken rectangle on all four edges
  157. // even where a zone fills to the edge - catches a clipped/offset origin.
  158. this->rectangle(0, 0, w, h, Color(0x00, 0x00, 0x00));
  159. }
  160. void setup() override {
  161. const auto *desc = this->desc_;
  162. // window_per_plane panels (GDEY0579F51's master+slave) size each
  163. // plane's own buffer from plane_width (each region's own local
  164. // width), not the descriptor's overall width (the full logical canvas
  165. // ESPHome draws into) - both regions are the same size here, so one
  166. // plane_bytes_ value covers both buffers.
  167. uint32_t w = desc->window_per_plane ? desc->plane_width : desc->width;
  168. // width*height*bpp/8: /8 at 1bpp, /4 at 2bpp (4-color), /2 at 4bpp (7-color).
  169. this->plane_bytes_ = (uint32_t) w * desc->height * desc->bits_per_pixel / 8;
  170. RAMAllocator<uint8_t> allocator;
  171. this->plane0_ = allocator.allocate(this->plane_bytes_);
  172. bool need_plane1 = desc->plane_count > 1;
  173. this->plane1_ = need_plane1 ? allocator.allocate(this->plane_bytes_) : nullptr;
  174. if (this->plane0_ == nullptr || (need_plane1 && this->plane1_ == nullptr)) {
  175. ESP_LOGE(TAG, "Failed to allocate %u-byte plane buffer(s)", (unsigned) this->plane_bytes_);
  176. this->mark_failed();
  177. return;
  178. }
  179. if (desc->bits_per_pixel > 1) {
  180. // Packed modes: clear every pixel to the panel's white/blank code,
  181. // replicated across the byte - e.g. 4-color white=0x01 -> 0x55, 7-color
  182. // white=0x01 -> 0x11, matching GxEPD2's own writeScreenBuffer() fill
  183. // (color4()*0x55 / color7()|<<4). Both regions of a window_per_plane
  184. // panel (master/slave) get the same blank fill.
  185. uint8_t fill = replicate_code_(desc->blank_code, desc->bits_per_pixel);
  186. memset(this->plane0_, fill, this->plane_bytes_);
  187. if (this->plane1_ != nullptr)
  188. memset(this->plane1_, fill, this->plane_bytes_);
  189. } else {
  190. // 1bpp plane model: plane0 white = all bits set (0xFF); plane1 (the
  191. // accent/red plane, when present) = 0 = not-red.
  192. memset(this->plane0_, 0xFF, this->plane_bytes_);
  193. if (this->plane1_ != nullptr)
  194. memset(this->plane1_, 0x00, this->plane_bytes_);
  195. }
  196. this->spi_.spi_setup();
  197. this->engine_.begin(desc, this->cs_, this->dc_, this->rst_, this->busy_, &this->spi_);
  198. }
  199. // Arms the state machine and returns immediately - the real several-
  200. // seconds-long write/refresh/busy-wait cycle happens across many
  201. // subsequent loop() ticks, not before this call returns.
  202. void update() override {
  203. if (!this->engine_.idle()) {
  204. ESP_LOGW(TAG, "Skipping update: previous display refresh is still running");
  205. return;
  206. }
  207. this->do_update_();
  208. this->engine_.request_full_update(this->plane0_, this->plane1_);
  209. }
  210. void loop() override { this->engine_.step(); }
  211. // Turns off the panel's driving-voltage generation (reduces fading over
  212. // time between refreshes). Call from a lambda, e.g.
  213. // id(<display_id>).power_off(); - not called automatically by update(),
  214. // since this engine does a full hardware reset every cycle regardless of
  215. // prior power state, so correctness never depends on it. A no-op (with a
  216. // warning) while a refresh is still in progress.
  217. void power_off() {
  218. if (!this->engine_.idle()) {
  219. ESP_LOGW(TAG, "Skipping power_off: display refresh still in progress");
  220. return;
  221. }
  222. this->engine_.request_power_off();
  223. }
  224. // power_off() + deep sleep, wakeable only by a hardware reset pulse - which
  225. // the next update() always issues (request_full_update()'s RESET_LOW), so
  226. // no paired "wake" call is needed; just call update() as usual. A no-op
  227. // (with a warning) while a refresh is still in progress.
  228. void hibernate() {
  229. if (!this->engine_.idle()) {
  230. ESP_LOGW(TAG, "Skipping hibernate: display refresh still in progress");
  231. return;
  232. }
  233. this->engine_.request_hibernate();
  234. }
  235. #ifdef USE_GXEPD2_DIAGNOSTICS
  236. // Dev-time diagnostics - compiled out entirely unless this display's YAML
  237. // sets `diagnostics: true` (display.py then adds -DUSE_GXEPD2_DIAGNOSTICS),
  238. // so a production build pays nothing for them. A stash for throwaway bench
  239. // tests, not a stable API - add more here as needed, don't feel obliged to
  240. // keep any of it around once a test has done its job.
  241. //
  242. // Draws the current lambda/pages content and pushes it WITHOUT the reset
  243. // pulse update() normally does first - see
  244. // CycleEngine::diag_request_update_no_reset(). Call from a lambda, e.g. to
  245. // check whether power_off()/hibernate() actually took: call one of those,
  246. // then this with a pattern distinct from what's already on screen - no
  247. // change (or odd BUSY behavior) means the panel really is off-line; follow
  248. // with a normal update() to confirm the next real reset wakes it and to
  249. // leave the panel in a known state either way.
  250. void diag_update_no_reset() {
  251. if (!this->engine_.idle()) {
  252. ESP_LOGW(TAG, "Skipping diag_update_no_reset: display refresh still in progress");
  253. return;
  254. }
  255. this->do_update_();
  256. this->engine_.diag_request_update_no_reset(this->plane0_, this->plane1_);
  257. }
  258. #endif
  259. void dump_config() override {
  260. ESP_LOGCONFIG(TAG, "GxEPD2 Display:");
  261. ESP_LOGCONFIG(TAG, " Dimensions: %ux%u", (unsigned) this->desc_->width, (unsigned) this->desc_->height);
  262. ESP_LOGCONFIG(TAG, " Bits/pixel: %u (%s)", (unsigned) this->desc_->bits_per_pixel,
  263. this->desc_->bits_per_pixel == 1 ? "mono/plane" : "packed palette");
  264. ESP_LOGCONFIG(TAG, " Planes/regions: %u", (unsigned) this->desc_->plane_count);
  265. ESP_LOGCONFIG(TAG, " Busy active level: %s", this->desc_->busy_active_level ? "HIGH" : "LOW");
  266. if (this->desc_->bits_per_pixel == 1)
  267. ESP_LOGCONFIG(TAG, " invert_mono: %s", YESNO(this->invert_mono_));
  268. ESP_LOGCONFIG(TAG, " Hardware-verified: %s", YESNO(this->verified_));
  269. if (!this->verified_)
  270. ESP_LOGW(TAG, "Panel %s is not yet hardware-verified - the captured descriptor may be wrong; "
  271. "if it renders correctly, please report it so it can be marked verified",
  272. this->model_name_ != nullptr ? this->model_name_ : "(unknown)");
  273. LOG_UPDATE_INTERVAL(this);
  274. }
  275. display::DisplayType get_display_type() override { return display::DisplayType::DISPLAY_TYPE_COLOR; }
  276. protected:
  277. // Replicates a packed wire code across a whole byte (one code per pixel
  278. // slot), e.g. 2bpp code 0x01 -> 0x55, 4bpp code 0x01 -> 0x11.
  279. static uint8_t replicate_code_(uint8_t code, uint8_t bpp) {
  280. uint8_t mask = static_cast<uint8_t>((1u << bpp) - 1);
  281. uint8_t out = 0;
  282. for (uint8_t i = 0; i < 8 / bpp; i++)
  283. out = static_cast<uint8_t>((out << bpp) | (code & mask));
  284. return out;
  285. }
  286. // Maps a drawn RGB color to its panel wire code via the descriptor's
  287. // palette: exact matches win (so named colors are deterministic, like
  288. // GxEPD2's color4()/color7() switch), otherwise nearest in RGB space.
  289. static uint8_t classify_(Color c, const EpdPaletteEntry *pal, uint8_t len) {
  290. if (pal == nullptr || len == 0)
  291. return 0;
  292. uint8_t best = 0;
  293. long best_d = -1;
  294. for (uint8_t i = 0; i < len; i++) {
  295. long dr = static_cast<long>(c.red) - pal[i].r;
  296. long dg = static_cast<long>(c.green) - pal[i].g;
  297. long db = static_cast<long>(c.blue) - pal[i].b;
  298. long d = dr * dr + dg * dg + db * db;
  299. if (d == 0)
  300. return pal[i].code;
  301. if (best_d < 0 || d < best_d) {
  302. best_d = d;
  303. best = i;
  304. }
  305. }
  306. return pal[best].code;
  307. }
  308. // Packed code-per-pixel model (bits_per_pixel > 1): N bits/pixel, MSB
  309. // first, matching GxEPD2's own out_data packing in writeImage (4-color
  310. // 4px/byte, 7-color 2px/byte). Routes to the correct region for a
  311. // window_per_plane (master/slave) panel the same way the mono path does.
  312. void draw_packed_(int x, int y, Color color) {
  313. const uint8_t bpp = this->desc_->bits_per_pixel;
  314. uint8_t code = classify_(color, this->desc_->palette, this->desc_->palette_len);
  315. uint16_t stride = this->desc_->width;
  316. uint8_t *buf = this->plane0_;
  317. int local_x = x;
  318. if (this->desc_->window_per_plane && this->desc_->plane_count > 1) {
  319. stride = this->desc_->plane_width;
  320. if (x >= stride) {
  321. buf = this->plane1_;
  322. local_x = x - stride;
  323. }
  324. }
  325. uint32_t px = static_cast<uint32_t>(y) * stride + local_x;
  326. const uint8_t ppb = 8 / bpp;
  327. uint32_t idx = px / ppb;
  328. uint8_t shift = static_cast<uint8_t>((ppb - 1 - (px % ppb)) * bpp);
  329. uint8_t mask = static_cast<uint8_t>((1u << bpp) - 1);
  330. buf[idx] = static_cast<uint8_t>((buf[idx] & ~(mask << shift)) | ((code & mask) << shift));
  331. }
  332. void draw_absolute_pixel_internal(int x, int y, Color color) override {
  333. if (x < 0 || y < 0 || x >= this->desc_->width || y >= this->desc_->height)
  334. return;
  335. if (this->desc_->bits_per_pixel > 1) {
  336. this->draw_packed_(x, y, color);
  337. return;
  338. }
  339. bool red = color.red > color.green && color.red > color.blue && color.red > 0x7f;
  340. bool bright = color.red > 0x7f || color.green > 0x7f || color.blue > 0x7f;
  341. uint32_t idx = (static_cast<uint32_t>(y) * this->desc_->width + x) / 8;
  342. uint8_t mask = 0x80 >> (x % 8);
  343. // Red/accent pixels go to the color plane (when the panel has one),
  344. // everything else is black/white on the black plane. get_display_type()
  345. // reports
  346. // DISPLAY_TYPE_COLOR, so callers draw literal RGB colors, not the
  347. // on/off is_on() convention, even on a plane_count==1 (BW-only) panel -
  348. // there just is no color plane for a "red" classification to land on.
  349. //
  350. // Buffer convention here is 1=red/0=not-red (matching the reference
  351. // epaper_spi driver's EPaperWeAct3C internal convention), transformed
  352. // to the wire value by plane_invert[1] - see PANEL_213_Z98C's comment
  353. // for why that inversion flag and this buffer convention are coupled,
  354. // not independent facts.
  355. if (red && this->plane1_ != nullptr) {
  356. this->plane1_[idx] |= mask;
  357. } else {
  358. if (this->plane1_ != nullptr)
  359. this->plane1_[idx] &= ~mask;
  360. // plane0 bit set = white/blank. invert_mono_ flips the mono sense so a
  361. // bright color (e.g. ESPHome's default COLOR_ON) becomes ink, not blank
  362. // - see display.py's CONF_INVERT_MONO. Red classification is unaffected.
  363. if (bright ^ this->invert_mono_) {
  364. this->plane0_[idx] |= mask;
  365. } else {
  366. this->plane0_[idx] &= ~mask;
  367. }
  368. }
  369. }
  370. int get_width_internal() override { return this->desc_->width; }
  371. int get_height_internal() override { return this->desc_->height; }
  372. // The colors this panel can actually show, each as a representative RGB, in
  373. // a stable order (black, white, then accents). Packed panels (>1bpp): one
  374. // entry per distinct palette wire code, first RGB seen for each. 1bpp:
  375. // black + white, plus red when a second plane exists for the accent (only
  376. // red-classified pixels reach it - see draw_absolute_pixel_internal). This
  377. // is what makes test_pattern() bit-depth aware. Returns the count.
  378. int test_colors_(Color *out, int max) {
  379. int n = 0;
  380. if (this->desc_->bits_per_pixel > 1 && this->desc_->palette != nullptr) {
  381. uint8_t seen[16];
  382. int seen_n = 0;
  383. for (int i = 0; i < this->desc_->palette_len && n < max; i++) {
  384. const uint8_t code = this->desc_->palette[i].code;
  385. bool dup = false;
  386. for (int j = 0; j < seen_n; j++)
  387. if (seen[j] == code) { dup = true; break; }
  388. if (dup) continue;
  389. if (seen_n < (int) sizeof(seen)) seen[seen_n++] = code;
  390. const auto &e = this->desc_->palette[i];
  391. out[n++] = Color(e.r, e.g, e.b);
  392. }
  393. } else {
  394. if (n < max) out[n++] = Color(0x00, 0x00, 0x00); // black
  395. if (n < max) out[n++] = Color(0xFF, 0xFF, 0xFF); // white
  396. if (this->desc_->plane_count >= 2 && n < max) out[n++] = Color(0xFF, 0x00, 0x00); // accent
  397. }
  398. return n;
  399. }
  400. const EpdPanelDescriptor *desc_{nullptr};
  401. const char *model_name_{nullptr};
  402. bool verified_{false};
  403. GPIOPin *cs_{nullptr};
  404. GPIOPin *dc_{nullptr};
  405. GPIOPin *rst_{nullptr};
  406. GPIOPin *busy_{nullptr};
  407. EpdSPIDevice spi_;
  408. CycleEngine engine_;
  409. uint8_t *plane0_{nullptr};
  410. uint8_t *plane1_{nullptr};
  411. uint32_t plane_bytes_{0};
  412. bool invert_mono_{false};
  413. };
  414. } // namespace esphome::gxepd2