GxEPD2-esphome/components/gxepd2/epd_command.h

#pragma once

#include <cstdint>

namespace esphome::gxepd2 {

// One command byte plus its (fixed, compile-time) data bytes, as sent by
// GxEPD2_EPD::_writeCommand()/_writeData(). delay_before_ms/delay_after_ms
// and wait_busy_after mirror the fixed delay()s and _waitWhileBusy() calls
// bracketing specific commands in the vendor source (which command gets
// which varies per panel - e.g. GxEPD2_213_Z98c delays 10ms on both sides
// of its SWRESET, while GxEPD2_154_Z90c busy-waits after its SWRESET
// instead). At most one of delay_after_ms/wait_busy_after is expected to be
// set on any one command.
struct EpdCommand {
  uint8_t cmd;
  const uint8_t *data;  // nullptr if the command takes no data bytes
  uint8_t data_len;
  uint16_t delay_before_ms{0};
  uint16_t delay_after_ms{0};
  bool wait_busy_after{false};
};

// Everything CycleEngine needs to drive one panel, hand-derived from a
// GxEPD2 vendor driver's .cpp/.h (see panel_154_z90c.h). Only what this
// first slice's engine actually uses - the RAM-window-set command layout
// (0x44/0x45/0x4E/0x4F) is common to every panel inspected so far and is
// hardcoded in CycleEngine itself rather than made part of this struct;
// revisit if/when the extraction-tooling phase finds a controller family
// that lays it out differently.
struct EpdPanelDescriptor {
  uint16_t width;
  uint16_t height;
  bool busy_active_level;    // digitalRead() level meaning "still busy"
  uint32_t busy_timeout_ms;  // ceiling for every busy wait (init and refresh alike)

  const EpdCommand *init_sequence;  // run once, after the reset pulse
  uint8_t init_sequence_len;

  // Sets the (always full-frame, since this engine has no partial-window
  // support) RAM addressing window. window_sequence[0] runs once after
  // init_sequence and before the first plane's byte burst; index 1 is only
  // used when window_per_plane is true (see below). Was hardcoded into
  // CycleEngine assuming every controller shares SSD1680's
  // 0x44/0x45/0x4E/0x4F byte-column layout - GxEPD2_426_GDEQ0426T82
  // (SSD1677) turned out to address in raw pixels with reversed Y and
  // re-issues its entry-mode command here, and GxEPD2_583_GDEQ0583T31
  // (UC8179) uses one 0x90 command bracketed by 0x91/0x92 markers instead.
  // Made per-panel data, same as init/refresh, rather than special-cased
  // in the engine.
  const EpdCommand *window_sequence[2];
  uint8_t window_sequence_len[2];

  // true if each plane needs window_sequence[plane index] re-run before
  // its own byte burst, instead of one window_sequence[0] covering every
  // plane's burst (the default, e.g. a BW+red panel's shared full-frame
  // window). This is how GxEPD2_579c_GDEY0579F51's real master/slave
  // regions are handled: two genuinely separate physical RAM windows, not
  // just two color planes sharing one - "plane" here just means "one more
  // buffer with its own byte burst," which happens to fit a two-physical-
  // region panel as well as a two-color-plane one. See
  // panel_579c_gdey0579f51.h.
  bool window_per_plane{false};

  uint8_t plane_count;          // 1 (BW), 2 (BW + accent color), or 2 physical regions
  uint8_t plane_write_cmd[2];   // e.g. {0x24, 0x26}
  bool plane_invert[2];         // true if the byte must be bit-inverted on write

  // When window_per_plane is true, each plane's own buffer is sized for
  // this width, not the descriptor's overall `width` (which is the full
  // logical canvas ESPHome draws into and get_width_internal() reports) -
  // e.g. 396 for GDEY0579F51's master/slave halves, each 396x272 on its
  // own, not the full 792x272. Unused otherwise.
  uint16_t plane_width{0};

  // true if rows must be sent in interleaved top/bottom-pair order (row 0,
  // row H-1, row 1, row H-2, ...) instead of plain sequential top-to-
  // bottom - GDEY0579F51's HX8717 pair apparently scans each half from
  // both edges toward the middle, per Waveshare's own epd5in79g.cpp
  // reference driver (confirmed 2026-09-19: a bar/ladder/diagonal test
  // pattern came out vertically scrambled with a broken diagonal - the
  // documented signature of a row-reordering bug - sent in plain
  // sequential order). Not assumed for any other packed_2bpp_plane panel
  // (e.g. GDEY029F51, a single-chip panel with no master/slave split at
  // all) without the same kind of hardware confirmation.
  bool row_interleave{false};

  // true for the JD79667/HX8717-family 4-color panels (GDEY029F51,
  // GDEY0579F51): pixels are 2 bits each, 4 per byte, built from a
  // white/black/yellow/red classification at draw time - a fundamentally
  // different buffer shape than the 1-bit-per-pixel plane(s) above, not
  // just a different invert/command byte. When true, plane_invert is
  // unused and GxEPD2Display's buffer(s) are width*height/4 bytes instead
  // of /8 (per-plane width*height/4 when window_per_plane is also true).
  bool packed_2bpp_plane{false};

  const EpdCommand *refresh_sequence;  // e.g. 0x22/0xF7 then trigger 0x20
  uint8_t refresh_sequence_len;
};

}  // namespace esphome::gxepd2