GxEPD2-esphome/components/gxepd2/cycle_engine.h

#pragma once

#include <cstdint>
#include <cstdio>

#include "esphome/core/gpio.h"
#include "esphome/core/hal.h"
#include "esphome/core/log.h"
#include "esphome/components/spi/spi.h"
#include "epd_command.h"

namespace esphome::gxepd2 {

// GxEPD2's vendor source specifies 20MHz for this panel, but the
// known-working epaper_spi driver for this exact physical unit/wiring
// (waveshare-2.13in-bv4) deliberately runs at 10MHz. Busy consistently
// engaging and clearing at a normal duration while content still comes out
// wrong (solid black, then solid red, now solid black again) is consistent
// with signal integrity problems at too aggressive a clock corrupting what
// actually lands in RAM, even though the controller still completes some
// waveform. Matching the proven-working clock instead of GxEPD2's generic
// spec value.
using EpdSPIDevice = spi::SPIDevice<spi::BIT_ORDER_MSB_FIRST, spi::CLOCK_POLARITY_LOW, spi::CLOCK_PHASE_LEADING,
                                     spi::DATA_RATE_10MHZ>;

// Mechanically replicates one GxEPD2 driver's refresh cycle - reset pulse,
// init command table, RAM-window set, per-plane byte burst, refresh
// trigger, busy-pin wait - as a state machine stepped from loop(), instead
// of GxEPD2's own synchronous top-to-bottom call stack. See the plan this
// was built from (and gxepd2_task_watchdog_status in project memory) for
// why: that call stack has no yield points, so making it non-blocking used
// to require running the whole thing on a separate FreeRTOS task, which
// intermittently tripped the ESP-IDF watchdog anyway. step() never blocks -
// every state does a small bounded unit of work and returns - so there is
// nothing here that can starve another task or need a watchdog subscription
// at all.
class CycleEngine {
 public:
  void begin(const EpdPanelDescriptor *desc, GPIOPin *cs, GPIOPin *dc, GPIOPin *rst, GPIOPin *busy,
             EpdSPIDevice *spi) {
    this->desc_ = desc;
    this->cs_ = cs;
    this->dc_ = dc;
    this->rst_ = rst;
    this->busy_ = busy;
    this->spi_ = spi;
    this->cs_->setup();
    this->dc_->setup();
    if (this->rst_ != nullptr)
      this->rst_->setup();
    if (this->busy_ != nullptr)
      this->busy_->setup();
    this->cs_->digital_write(true);
    this->dc_->digital_write(true);
  }

  // Arms the state machine; returns immediately. planes[1] is ignored when
  // desc->plane_count == 1. Undefined to call while !idle().
  void request_full_update(const uint8_t *plane0, const uint8_t *plane1) {
    this->planes_[0] = plane0;
    this->planes_[1] = plane1;
    this->plane_bytes_ = (static_cast<uint32_t>(this->desc_->width) * this->desc_->height) / 8;
    this->cursor_ = 0;
    this->cmd_phase_ = CmdPhase::BEFORE_DELAY;
    this->set_state_(this->rst_ != nullptr ? State::RESET_LOW : State::INIT_CMD);
  }

  bool idle() const { return this->state_ == State::IDLE; }

  // Called once per loop() tick. Does one bounded unit of work.
  void step() {
    switch (this->state_) {
      case State::IDLE:
        return;
      case State::RESET_LOW:
        this->rst_->digital_write(true);  // preset high, then pulse low - see GxEPD2_EPD::_reset()
        this->deadline_ = millis() + 10;
        this->set_state_(State::RESET_LOW_WAIT);
        return;
      case State::RESET_LOW_WAIT:
        if (millis() < this->deadline_)
          return;
        this->rst_->digital_write(false);
        this->deadline_ = millis() + 10;
        this->set_state_(State::RESET_HIGH_WAIT);
        return;
      case State::RESET_HIGH_WAIT:
        if (millis() < this->deadline_)
          return;
        this->rst_->digital_write(true);
        this->deadline_ = millis() + 10;
        this->set_state_(State::RESET_SETTLE);
        return;
      case State::RESET_SETTLE:
        if (millis() < this->deadline_)
          return;
        this->cursor_ = 0;
        this->cmd_phase_ = CmdPhase::BEFORE_DELAY;
        this->set_state_(State::INIT_CMD);
        return;

      case State::INIT_CMD:
        this->step_sequence_(this->desc_->init_sequence, this->desc_->init_sequence_len, State::INIT_CMD,
                              State::SET_WINDOW);
        return;

      case State::SET_WINDOW:
        this->set_full_window_();
        this->cursor_ = 0;
        this->plane_ = 0;
        this->set_state_(State::WRITE_PLANE);
        return;

      case State::WRITE_PLANE:
        this->step_write_plane_();
        return;

      case State::REFRESH_CMD:
        this->step_sequence_(this->desc_->refresh_sequence, this->desc_->refresh_sequence_len, State::REFRESH_CMD,
                              State::DONE);
        return;

      case State::POST_DELAY:
        if (millis() < this->deadline_)
          return;
        this->set_state_(this->delay_return_state_);
        return;

      case State::WAIT_BUSY:
        this->step_wait_busy_();
        return;

      case State::DONE:
        ESP_LOGD("gxepd2", "Display update finished");
        this->set_state_(State::IDLE);
        return;
    }
  }

 private:
  enum class State {
    IDLE,
    RESET_LOW,
    RESET_LOW_WAIT,
    RESET_HIGH_WAIT,
    RESET_SETTLE,
    INIT_CMD,
    SET_WINDOW,
    WRITE_PLANE,
    REFRESH_CMD,
    POST_DELAY,
    WAIT_BUSY,
    DONE,
  };
  enum class CmdPhase { BEFORE_DELAY, ISSUE };

  // Every command byte and every data byte is its own SPI transaction, CS
  // toggled around each one - this looks wasteful, but it's mechanically
  // what GxEPD2_EPD::_writeCommand()/_writeData(uint8_t) do (see
  // vendor/src/GxEPD2_EPD.cpp), and matching the vendor cycle byte-for-byte
  // is the point of this engine.
  void write_byte_(uint8_t b, bool dc_high) {
    this->dc_->digital_write(dc_high);
    this->spi_->enable();
    this->cs_->digital_write(false);
    this->spi_->write_byte(b);
    this->cs_->digital_write(true);
    this->spi_->disable();
  }

  void write_command_(uint8_t cmd, const uint8_t *data, uint8_t data_len) {
#if ESPHOME_LOG_LEVEL >= ESPHOME_LOG_LEVEL_DEBUG
    // Command-level skeleton trace - deliberately left in (not gated to
    // VERY_VERBOSE) while diagnosing a real-hardware content bug: this is
    // the exact byte-for-byte counterpart to compare against a captured
    // epaper_spi trace on the same panel. Bulk plane data isn't logged
    // here (see step_write_plane_) - only the command skeleton matters for
    // that comparison.
    char buf[32];
    int n = 0;
    for (uint8_t i = 0; i < data_len && n < (int) sizeof(buf) - 3; i++)
      n += snprintf(buf + n, sizeof(buf) - n, "%02X ", data[i]);
    ESP_LOGD("gxepd2", "cmd 0x%02X data[%u]: %s", cmd, data_len, buf);
#endif
    this->write_byte_(cmd, false);
    for (uint8_t i = 0; i < data_len; i++)
      this->write_byte_(data[i], true);
  }

  // Steps through one EpdCommand table one entry (and one delay/busy-wait,
  // if that entry has one) at a time, resuming in self_state after any
  // wait so the same call re-enters here for the next entry. Shared by
  // INIT_CMD and REFRESH_CMD - which table is being stepped is entirely
  // determined by which state called this.
  void step_sequence_(const EpdCommand *seq, uint8_t len, State self_state, State done_state) {
    if (this->cursor_ >= len) {
      this->cursor_ = 0;
      this->cmd_phase_ = CmdPhase::BEFORE_DELAY;
      this->set_state_(done_state);
      return;
    }
    const EpdCommand &c = seq[this->cursor_];
    if (this->cmd_phase_ == CmdPhase::BEFORE_DELAY) {
      this->cmd_phase_ = CmdPhase::ISSUE;
      if (c.delay_before_ms > 0) {
        this->start_delay_(c.delay_before_ms, self_state);
        return;
      }
    }
    this->write_command_(c.cmd, c.data, c.data_len);
    this->cursor_++;
    this->cmd_phase_ = CmdPhase::BEFORE_DELAY;
    if (c.wait_busy_after) {
      this->start_busy_wait_(self_state);
    } else if (c.delay_after_ms > 0) {
      this->start_delay_(c.delay_after_ms, self_state);
    }
    // else: stays in self_state; the next step() call processes the next entry.
  }

  // GxEPD2_EPD::_setPartialRamArea(0, 0, width, height) - full frame only,
  // this slice doesn't do partial windows yet.
  void set_full_window_() {
    uint16_t w = this->desc_->width, h = this->desc_->height;
    uint16_t xe = w - 1, ye = h - 1;
    const uint8_t x44[] = {0, static_cast<uint8_t>(xe / 8)};
    this->write_command_(0x44, x44, 2);
    const uint8_t x45[] = {0, 0, static_cast<uint8_t>(ye % 256), static_cast<uint8_t>(ye / 256)};
    this->write_command_(0x45, x45, 4);
    const uint8_t x4e[] = {0};
    this->write_command_(0x4E, x4e, 1);
    const uint8_t x4f[] = {0, 0};
    this->write_command_(0x4F, x4f, 2);
  }

  // Writes up to BYTE_BUDGET bytes of the current plane per call, then
  // returns - this bound is what keeps a full-frame write (thousands of
  // bytes) from ever making one loop() tick run long, replacing the old
  // per-256-byte esp_task_wdt_reset()+delay(1) throttle with simply not
  // doing enough work in one call to need it.
  static constexpr uint32_t BYTE_BUDGET = 64;

  void step_write_plane_() {
    if (this->cursor_ == 0) {
      ESP_LOGD("gxepd2", "plane %u: cmd 0x%02X, %u bytes, invert=%d", this->plane_,
               this->desc_->plane_write_cmd[this->plane_], (unsigned) this->plane_bytes_,
               this->desc_->plane_invert[this->plane_]);
      this->write_byte_(this->desc_->plane_write_cmd[this->plane_], false);
    }
    const uint8_t *buf = this->planes_[this->plane_];
    bool invert = this->desc_->plane_invert[this->plane_];
    uint32_t end = this->cursor_ + BYTE_BUDGET;
    if (end > this->plane_bytes_)
      end = this->plane_bytes_;
    for (; this->cursor_ < end; this->cursor_++) {
      uint8_t b = buf != nullptr ? buf[this->cursor_] : 0xFF;
      this->write_byte_(invert ? static_cast<uint8_t>(~b) : b, true);
    }
    if (this->cursor_ >= this->plane_bytes_) {
      this->cursor_ = 0;
      this->plane_++;
      if (this->plane_ >= this->desc_->plane_count) {
        this->plane_ = 0;
        this->cursor_ = 0;
        this->cmd_phase_ = CmdPhase::BEFORE_DELAY;
        this->set_state_(State::REFRESH_CMD);
      }
    }
  }

  void start_delay_(uint16_t delay_ms, State return_to) {
    this->deadline_ = millis() + delay_ms;
    this->delay_return_state_ = return_to;
    this->set_state_(State::POST_DELAY);
  }

  void start_busy_wait_(State next) {
    this->busy_wait_next_ = next;
    this->busy_wait_deadline_ = millis() + this->desc_->busy_timeout_ms;
    this->set_state_(State::WAIT_BUSY);
  }

  void step_wait_busy_() {
    if (this->busy_ == nullptr) {
      this->set_state_(this->busy_wait_next_);
      return;
    }
    bool busy = this->busy_->digital_read() == this->desc_->busy_active_level;
    if (!busy) {
      this->set_state_(this->busy_wait_next_);
      return;
    }
    if (millis() >= this->busy_wait_deadline_) {
      ESP_LOGW("gxepd2", "Busy timeout waiting for panel");
      this->set_state_(this->busy_wait_next_);
    }
  }

  // Logs every state transition (only when the state actually changes -
  // WAIT_BUSY and POST_DELAY re-enter their own case on every step() call
  // while polling, which would otherwise spam this at loop() rate) so a
  // first hardware run can be checked against the vendor cycle it's meant
  // to replicate before this gets dialed back to WARN-only.
  void set_state_(State s) {
    if (s != this->state_)
      ESP_LOGD("gxepd2", "state: %s -> %s", state_name_(this->state_), state_name_(s));
    this->state_ = s;
  }

  static const char *state_name_(State s) {
    switch (s) {
      case State::IDLE:
        return "IDLE";
      case State::RESET_LOW:
        return "RESET_LOW";
      case State::RESET_LOW_WAIT:
        return "RESET_LOW_WAIT";
      case State::RESET_HIGH_WAIT:
        return "RESET_HIGH_WAIT";
      case State::RESET_SETTLE:
        return "RESET_SETTLE";
      case State::INIT_CMD:
        return "INIT_CMD";
      case State::SET_WINDOW:
        return "SET_WINDOW";
      case State::WRITE_PLANE:
        return "WRITE_PLANE";
      case State::REFRESH_CMD:
        return "REFRESH_CMD";
      case State::POST_DELAY:
        return "POST_DELAY";
      case State::WAIT_BUSY:
        return "WAIT_BUSY";
      case State::DONE:
        return "DONE";
    }
    return "?";
  }

  const EpdPanelDescriptor *desc_{nullptr};
  GPIOPin *cs_{nullptr};
  GPIOPin *dc_{nullptr};
  GPIOPin *rst_{nullptr};
  GPIOPin *busy_{nullptr};
  EpdSPIDevice *spi_{nullptr};

  State state_{State::IDLE};
  uint32_t cursor_{0};
  CmdPhase cmd_phase_{CmdPhase::BEFORE_DELAY};
  uint8_t plane_{0};
  const uint8_t *planes_[2]{nullptr, nullptr};
  uint32_t plane_bytes_{0};
  uint32_t deadline_{0};
  State delay_return_state_{State::DONE};
  uint32_t busy_wait_deadline_{0};
  State busy_wait_next_{State::DONE};
};

}  // namespace esphome::gxepd2