#pragma once #include "esphome/core/component.h" #include "esphome/core/helpers.h" #include "esphome/components/display/display_buffer.h" #include "esphome/components/spi/spi.h" #include "cycle_engine.h" #include "panel_213_z98c.h" #include "panel_290c_gdey029f51.h" #include "panel_426_gdeq0426t82.h" #include "panel_579c_gdey0579f51.h" #include "panel_579c_gdey0579f51_master_only.h" #include "panel_583_gdeq0583t31.h" namespace esphome::gxepd2 { static const char *const TAG = "gxepd2"; // Native chunked-engine replacement for the old GxEPD2-template/FreeRTOS-task // component - see the plan this was built from (and project memory entry // gxepd2_task_watchdog_status) for why. Panels arrive as hand-written // (later, extracted) descriptors selected at runtime via set_descriptor(), // not by templating this class over GxEPD2's own driver classes. class GxEPD2Display : public display::DisplayBuffer { public: void set_cs_pin(GPIOPin *pin) { this->cs_ = pin; } void set_dc_pin(GPIOPin *pin) { this->dc_ = pin; } void set_reset_pin(GPIOPin *pin) { this->rst_ = pin; } void set_busy_pin(GPIOPin *pin) { this->busy_ = pin; } void set_spi_parent(spi::SPIComponent *parent) { this->spi_.set_spi_parent(parent); } void set_descriptor(const EpdPanelDescriptor *desc) { this->desc_ = desc; } void setup() override { const auto *desc = this->desc_; // window_per_plane panels (GDEY0579F51's master+slave) size each // plane's own buffer from plane_width (each region's own local // width), not the descriptor's overall width (the full logical canvas // ESPHome draws into) - both regions are the same size here, so one // plane_bytes_ value covers both buffers. uint32_t w = desc->window_per_plane ? desc->plane_width : desc->width; this->plane_bytes_ = desc->packed_2bpp_plane ? (w * desc->height) / 4 : (w * desc->height) / 8; RAMAllocator allocator; this->plane0_ = allocator.allocate(this->plane_bytes_); bool need_plane1 = desc->plane_count > 1; this->plane1_ = need_plane1 ? allocator.allocate(this->plane_bytes_) : nullptr; if (this->plane0_ == nullptr || (need_plane1 && this->plane1_ == nullptr)) { ESP_LOGE(TAG, "Failed to allocate %u-byte plane buffer(s)", (unsigned) this->plane_bytes_); this->mark_failed(); return; } // Packed 2bpp: code 0x01 (white) repeated 4x/byte = 0x55, matching // GxEPD2's own writeScreenBuffer()'s white fill value exactly - not // 0xFF (that's the 1bpp planes' white) or 0x00 (that's black here). memset(this->plane0_, desc->packed_2bpp_plane ? 0x55 : 0xFF, this->plane_bytes_); if (this->plane1_ != nullptr) { // plane1_ is a second packed region (master/slave) for a // window_per_plane panel - also defaults to white (0x55), not the // 1bpp "red" plane's 0=not-red convention. memset(this->plane1_, desc->packed_2bpp_plane ? 0x55 : 0x00, this->plane_bytes_); } this->spi_.spi_setup(); this->engine_.begin(desc, this->cs_, this->dc_, this->rst_, this->busy_, &this->spi_); } // Arms the state machine and returns immediately - the real several- // seconds-long write/refresh/busy-wait cycle happens across many // subsequent loop() ticks, not before this call returns. void update() override { if (!this->engine_.idle()) { ESP_LOGW(TAG, "Skipping update: previous display refresh is still running"); return; } this->do_update_(); this->engine_.request_full_update(this->plane0_, this->plane1_); } void loop() override { this->engine_.step(); } void dump_config() override { ESP_LOGCONFIG(TAG, "GxEPD2 Display"); LOG_UPDATE_INTERVAL(this); } display::DisplayType get_display_type() override { return display::DisplayType::DISPLAY_TYPE_COLOR; } protected: void draw_absolute_pixel_internal(int x, int y, Color color) override { if (x < 0 || y < 0 || x >= this->desc_->width || y >= this->desc_->height) return; bool red = color.red > color.green && color.red > color.blue && color.red > 0x7f; bool bright = color.red > 0x7f || color.green > 0x7f || color.blue > 0x7f; if (this->desc_->packed_2bpp_plane) { // JD79667/HX8717-family panels: 2 bits/pixel, 4 pixels/byte, MSB // first (matches GxEPD2's own out_data <<= 2 packing order in e.g. // GxEPD2_290c_GDEY029F51::writeImage). Codes match GxEPD2_4C.h's own // color4() table exactly: black=0x00, white=0x01, yellow=0x02, // red=0x03 - confirmed against that table after first getting // black/white backwards by misreading writeImage's own // black_data-bit ternary (2026-09-19). bool yellow = color.red > 0x7f && color.green > 0x7f && color.blue <= 0x7f; uint8_t code; if (red) code = 0x03; else if (yellow) code = 0x02; else if (bright) code = 0x01; else code = 0x00; // window_per_plane (GDEY0579F51's master+slave): each region is its // own local 396-wide buffer, not one 792-wide one - route by which // half of the global x range this pixel falls in. uint16_t stride = this->desc_->width; uint8_t *buf = this->plane0_; int local_x = x; if (this->desc_->window_per_plane && this->desc_->plane_count > 1) { stride = this->desc_->plane_width; if (x >= stride) { buf = this->plane1_; local_x = x - stride; } } uint32_t px = static_cast(y) * stride + local_x; uint32_t idx = px / 4; uint8_t shift = static_cast((3 - (px % 4)) * 2); buf[idx] = static_cast((buf[idx] & ~(0x03 << shift)) | (code << shift)); return; } uint32_t idx = (static_cast(y) * this->desc_->width + x) / 8; uint8_t mask = 0x80 >> (x % 8); // Same classification the old task-based component used: red/accent // pixels go to the color plane (when the panel has one), everything // else is black/white on the black plane. get_display_type() reports // DISPLAY_TYPE_COLOR, so callers draw literal RGB colors, not the // on/off is_on() convention, even on a plane_count==1 (BW-only) panel - // there just is no color plane for a "red" classification to land on. // // Buffer convention here is 1=red/0=not-red (matching the reference // epaper_spi driver's EPaperWeAct3C internal convention), transformed // to the wire value by plane_invert[1] - see PANEL_213_Z98C's comment // for why that inversion flag and this buffer convention are coupled, // not independent facts. if (red && this->plane1_ != nullptr) { this->plane1_[idx] |= mask; } else { if (this->plane1_ != nullptr) this->plane1_[idx] &= ~mask; if (bright) { this->plane0_[idx] |= mask; } else { this->plane0_[idx] &= ~mask; } } } int get_width_internal() override { return this->desc_->width; } int get_height_internal() override { return this->desc_->height; } const EpdPanelDescriptor *desc_{nullptr}; GPIOPin *cs_{nullptr}; GPIOPin *dc_{nullptr}; GPIOPin *rst_{nullptr}; GPIOPin *busy_{nullptr}; EpdSPIDevice spi_; CycleEngine engine_; uint8_t *plane0_{nullptr}; uint8_t *plane1_{nullptr}; uint32_t plane_bytes_{0}; }; } // namespace esphome::gxepd2