cycle_engine.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373
  1. #pragma once
  2. #include <cstdint>
  3. #include <cstdio>
  4. #include "esphome/core/gpio.h"
  5. #include "esphome/core/hal.h"
  6. #include "esphome/core/log.h"
  7. #include "esphome/components/spi/spi.h"
  8. #include "epd_command.h"
  9. namespace esphome::gxepd2 {
  10. // GxEPD2's vendor source specifies 20MHz for this panel, but the
  11. // known-working epaper_spi driver for this exact physical unit/wiring
  12. // (waveshare-2.13in-bv4) deliberately runs at 10MHz. Busy consistently
  13. // engaging and clearing at a normal duration while content still comes out
  14. // wrong (solid black, then solid red, now solid black again) is consistent
  15. // with signal integrity problems at too aggressive a clock corrupting what
  16. // actually lands in RAM, even though the controller still completes some
  17. // waveform. Matching the proven-working clock instead of GxEPD2's generic
  18. // spec value.
  19. using EpdSPIDevice = spi::SPIDevice<spi::BIT_ORDER_MSB_FIRST, spi::CLOCK_POLARITY_LOW, spi::CLOCK_PHASE_LEADING,
  20. spi::DATA_RATE_10MHZ>;
  21. // Mechanically replicates one GxEPD2 driver's refresh cycle - reset pulse,
  22. // init command table, RAM-window set, per-plane byte burst, refresh
  23. // trigger, busy-pin wait - as a state machine stepped from loop(), instead
  24. // of GxEPD2's own synchronous top-to-bottom call stack. See the plan this
  25. // was built from (and gxepd2_task_watchdog_status in project memory) for
  26. // why: that call stack has no yield points, so making it non-blocking used
  27. // to require running the whole thing on a separate FreeRTOS task, which
  28. // intermittently tripped the ESP-IDF watchdog anyway. step() never blocks -
  29. // every state does a small bounded unit of work and returns - so there is
  30. // nothing here that can starve another task or need a watchdog subscription
  31. // at all.
  32. class CycleEngine {
  33. public:
  34. void begin(const EpdPanelDescriptor *desc, GPIOPin *cs, GPIOPin *dc, GPIOPin *rst, GPIOPin *busy,
  35. EpdSPIDevice *spi) {
  36. this->desc_ = desc;
  37. this->cs_ = cs;
  38. this->dc_ = dc;
  39. this->rst_ = rst;
  40. this->busy_ = busy;
  41. this->spi_ = spi;
  42. this->cs_->setup();
  43. this->dc_->setup();
  44. if (this->rst_ != nullptr)
  45. this->rst_->setup();
  46. if (this->busy_ != nullptr)
  47. this->busy_->setup();
  48. this->cs_->digital_write(true);
  49. this->dc_->digital_write(true);
  50. }
  51. // Arms the state machine; returns immediately. planes[1] is ignored when
  52. // desc->plane_count == 1. Undefined to call while !idle().
  53. void request_full_update(const uint8_t *plane0, const uint8_t *plane1) {
  54. this->planes_[0] = plane0;
  55. this->planes_[1] = plane1;
  56. this->plane_bytes_ = (static_cast<uint32_t>(this->desc_->width) * this->desc_->height) / 8;
  57. this->cursor_ = 0;
  58. this->cmd_phase_ = CmdPhase::BEFORE_DELAY;
  59. this->set_state_(this->rst_ != nullptr ? State::RESET_LOW : State::INIT_CMD);
  60. }
  61. bool idle() const { return this->state_ == State::IDLE; }
  62. // Called once per loop() tick. Does one bounded unit of work.
  63. void step() {
  64. switch (this->state_) {
  65. case State::IDLE:
  66. return;
  67. case State::RESET_LOW:
  68. this->rst_->digital_write(true); // preset high, then pulse low - see GxEPD2_EPD::_reset()
  69. this->deadline_ = millis() + 10;
  70. this->set_state_(State::RESET_LOW_WAIT);
  71. return;
  72. case State::RESET_LOW_WAIT:
  73. if (millis() < this->deadline_)
  74. return;
  75. this->rst_->digital_write(false);
  76. this->deadline_ = millis() + 10;
  77. this->set_state_(State::RESET_HIGH_WAIT);
  78. return;
  79. case State::RESET_HIGH_WAIT:
  80. if (millis() < this->deadline_)
  81. return;
  82. this->rst_->digital_write(true);
  83. this->deadline_ = millis() + 10;
  84. this->set_state_(State::RESET_SETTLE);
  85. return;
  86. case State::RESET_SETTLE:
  87. if (millis() < this->deadline_)
  88. return;
  89. this->cursor_ = 0;
  90. this->cmd_phase_ = CmdPhase::BEFORE_DELAY;
  91. this->set_state_(State::INIT_CMD);
  92. return;
  93. case State::INIT_CMD:
  94. this->step_sequence_(this->desc_->init_sequence, this->desc_->init_sequence_len, State::INIT_CMD,
  95. State::SET_WINDOW);
  96. return;
  97. case State::SET_WINDOW:
  98. this->set_full_window_();
  99. this->cursor_ = 0;
  100. this->plane_ = 0;
  101. this->set_state_(State::WRITE_PLANE);
  102. return;
  103. case State::WRITE_PLANE:
  104. this->step_write_plane_();
  105. return;
  106. case State::REFRESH_CMD:
  107. this->step_sequence_(this->desc_->refresh_sequence, this->desc_->refresh_sequence_len, State::REFRESH_CMD,
  108. State::DONE);
  109. return;
  110. case State::POST_DELAY:
  111. if (millis() < this->deadline_)
  112. return;
  113. this->set_state_(this->delay_return_state_);
  114. return;
  115. case State::WAIT_BUSY:
  116. this->step_wait_busy_();
  117. return;
  118. case State::DONE:
  119. ESP_LOGD("gxepd2", "Display update finished");
  120. this->set_state_(State::IDLE);
  121. return;
  122. }
  123. }
  124. private:
  125. enum class State {
  126. IDLE,
  127. RESET_LOW,
  128. RESET_LOW_WAIT,
  129. RESET_HIGH_WAIT,
  130. RESET_SETTLE,
  131. INIT_CMD,
  132. SET_WINDOW,
  133. WRITE_PLANE,
  134. REFRESH_CMD,
  135. POST_DELAY,
  136. WAIT_BUSY,
  137. DONE,
  138. };
  139. enum class CmdPhase { BEFORE_DELAY, ISSUE };
  140. // Every command byte and every data byte is its own SPI transaction, CS
  141. // toggled around each one - this looks wasteful, but it's mechanically
  142. // what GxEPD2_EPD::_writeCommand()/_writeData(uint8_t) do (see
  143. // vendor/src/GxEPD2_EPD.cpp), and matching the vendor cycle byte-for-byte
  144. // is the point of this engine.
  145. void write_byte_(uint8_t b, bool dc_high) {
  146. this->dc_->digital_write(dc_high);
  147. this->spi_->enable();
  148. this->cs_->digital_write(false);
  149. this->spi_->write_byte(b);
  150. this->cs_->digital_write(true);
  151. this->spi_->disable();
  152. }
  153. void write_command_(uint8_t cmd, const uint8_t *data, uint8_t data_len) {
  154. #if ESPHOME_LOG_LEVEL >= ESPHOME_LOG_LEVEL_DEBUG
  155. // Command-level skeleton trace - deliberately left in (not gated to
  156. // VERY_VERBOSE) while diagnosing a real-hardware content bug: this is
  157. // the exact byte-for-byte counterpart to compare against a captured
  158. // epaper_spi trace on the same panel. Bulk plane data isn't logged
  159. // here (see step_write_plane_) - only the command skeleton matters for
  160. // that comparison.
  161. char buf[32] = {0};
  162. int n = 0;
  163. for (uint8_t i = 0; i < data_len && n < (int) sizeof(buf) - 3; i++)
  164. n += snprintf(buf + n, sizeof(buf) - n, "%02X ", data[i]);
  165. ESP_LOGD("gxepd2", "cmd 0x%02X data[%u]: %s", cmd, data_len, buf);
  166. #endif
  167. this->write_byte_(cmd, false);
  168. for (uint8_t i = 0; i < data_len; i++)
  169. this->write_byte_(data[i], true);
  170. }
  171. // Steps through one EpdCommand table one entry (and one delay/busy-wait,
  172. // if that entry has one) at a time, resuming in self_state after any
  173. // wait so the same call re-enters here for the next entry. Shared by
  174. // INIT_CMD and REFRESH_CMD - which table is being stepped is entirely
  175. // determined by which state called this.
  176. void step_sequence_(const EpdCommand *seq, uint8_t len, State self_state, State done_state) {
  177. if (this->cursor_ >= len) {
  178. this->cursor_ = 0;
  179. this->cmd_phase_ = CmdPhase::BEFORE_DELAY;
  180. this->set_state_(done_state);
  181. return;
  182. }
  183. const EpdCommand &c = seq[this->cursor_];
  184. if (this->cmd_phase_ == CmdPhase::BEFORE_DELAY) {
  185. this->cmd_phase_ = CmdPhase::ISSUE;
  186. if (c.delay_before_ms > 0) {
  187. this->start_delay_(c.delay_before_ms, self_state);
  188. return;
  189. }
  190. }
  191. this->write_command_(c.cmd, c.data, c.data_len);
  192. this->cursor_++;
  193. this->cmd_phase_ = CmdPhase::BEFORE_DELAY;
  194. if (c.wait_busy_after) {
  195. this->start_busy_wait_(self_state);
  196. } else if (c.delay_after_ms > 0) {
  197. this->start_delay_(c.delay_after_ms, self_state);
  198. }
  199. // else: stays in self_state; the next step() call processes the next entry.
  200. }
  201. // GxEPD2_EPD::_setPartialRamArea(0, 0, width, height) - full frame only,
  202. // this slice doesn't do partial windows yet.
  203. void set_full_window_() {
  204. uint16_t w = this->desc_->width, h = this->desc_->height;
  205. uint16_t xe = w - 1, ye = h - 1;
  206. const uint8_t x44[] = {0, static_cast<uint8_t>(xe / 8)};
  207. this->write_command_(0x44, x44, 2);
  208. const uint8_t x45[] = {0, 0, static_cast<uint8_t>(ye % 256), static_cast<uint8_t>(ye / 256)};
  209. this->write_command_(0x45, x45, 4);
  210. const uint8_t x4e[] = {0};
  211. this->write_command_(0x4E, x4e, 1);
  212. const uint8_t x4f[] = {0, 0};
  213. this->write_command_(0x4F, x4f, 2);
  214. }
  215. // Writes up to BYTE_BUDGET bytes of the current plane per call, then
  216. // returns - this bound is what keeps a full-frame write (thousands of
  217. // bytes) from ever making one loop() tick run long, replacing the old
  218. // per-256-byte esp_task_wdt_reset()+delay(1) throttle with simply not
  219. // doing enough work in one call to need it.
  220. static constexpr uint32_t BYTE_BUDGET = 64;
  221. void step_write_plane_() {
  222. if (this->cursor_ == 0) {
  223. const uint8_t *buf = this->planes_[this->plane_];
  224. uint32_t histo[3] = {0, 0, 0}; // [0]=0x00, [1]=0xFF, [2]=other
  225. if (buf != nullptr) {
  226. for (uint32_t i = 0; i < this->plane_bytes_; i++) {
  227. if (buf[i] == 0x00)
  228. histo[0]++;
  229. else if (buf[i] == 0xFF)
  230. histo[1]++;
  231. else
  232. histo[2]++;
  233. }
  234. }
  235. ESP_LOGD("gxepd2", "plane %u: cmd 0x%02X, %u bytes, invert=%d, buf[0]=0x%02X buf[last]=0x%02X, histo(00/FF/other)=%u/%u/%u",
  236. this->plane_, this->desc_->plane_write_cmd[this->plane_], (unsigned) this->plane_bytes_,
  237. this->desc_->plane_invert[this->plane_], buf != nullptr ? buf[0] : 0,
  238. buf != nullptr ? buf[this->plane_bytes_ - 1] : 0, (unsigned) histo[0], (unsigned) histo[1],
  239. (unsigned) histo[2]);
  240. this->write_byte_(this->desc_->plane_write_cmd[this->plane_], false);
  241. }
  242. const uint8_t *buf = this->planes_[this->plane_];
  243. bool invert = this->desc_->plane_invert[this->plane_];
  244. uint32_t end = this->cursor_ + BYTE_BUDGET;
  245. if (end > this->plane_bytes_)
  246. end = this->plane_bytes_;
  247. for (; this->cursor_ < end; this->cursor_++) {
  248. uint8_t b = buf != nullptr ? buf[this->cursor_] : 0xFF;
  249. this->write_byte_(invert ? static_cast<uint8_t>(~b) : b, true);
  250. }
  251. if (this->cursor_ >= this->plane_bytes_) {
  252. this->cursor_ = 0;
  253. this->plane_++;
  254. if (this->plane_ >= this->desc_->plane_count) {
  255. this->plane_ = 0;
  256. this->cursor_ = 0;
  257. this->cmd_phase_ = CmdPhase::BEFORE_DELAY;
  258. this->set_state_(State::REFRESH_CMD);
  259. }
  260. }
  261. }
  262. void start_delay_(uint16_t delay_ms, State return_to) {
  263. this->deadline_ = millis() + delay_ms;
  264. this->delay_return_state_ = return_to;
  265. this->set_state_(State::POST_DELAY);
  266. }
  267. void start_busy_wait_(State next) {
  268. this->busy_wait_next_ = next;
  269. this->busy_wait_deadline_ = millis() + this->desc_->busy_timeout_ms;
  270. this->set_state_(State::WAIT_BUSY);
  271. }
  272. void step_wait_busy_() {
  273. if (this->busy_ == nullptr) {
  274. this->set_state_(this->busy_wait_next_);
  275. return;
  276. }
  277. bool busy = this->busy_->digital_read() == this->desc_->busy_active_level;
  278. if (!busy) {
  279. this->set_state_(this->busy_wait_next_);
  280. return;
  281. }
  282. if (millis() >= this->busy_wait_deadline_) {
  283. ESP_LOGW("gxepd2", "Busy timeout waiting for panel");
  284. this->set_state_(this->busy_wait_next_);
  285. }
  286. }
  287. // Logs every state transition (only when the state actually changes -
  288. // WAIT_BUSY and POST_DELAY re-enter their own case on every step() call
  289. // while polling, which would otherwise spam this at loop() rate) so a
  290. // first hardware run can be checked against the vendor cycle it's meant
  291. // to replicate before this gets dialed back to WARN-only.
  292. void set_state_(State s) {
  293. if (s != this->state_)
  294. ESP_LOGD("gxepd2", "state: %s -> %s", state_name_(this->state_), state_name_(s));
  295. this->state_ = s;
  296. }
  297. static const char *state_name_(State s) {
  298. switch (s) {
  299. case State::IDLE:
  300. return "IDLE";
  301. case State::RESET_LOW:
  302. return "RESET_LOW";
  303. case State::RESET_LOW_WAIT:
  304. return "RESET_LOW_WAIT";
  305. case State::RESET_HIGH_WAIT:
  306. return "RESET_HIGH_WAIT";
  307. case State::RESET_SETTLE:
  308. return "RESET_SETTLE";
  309. case State::INIT_CMD:
  310. return "INIT_CMD";
  311. case State::SET_WINDOW:
  312. return "SET_WINDOW";
  313. case State::WRITE_PLANE:
  314. return "WRITE_PLANE";
  315. case State::REFRESH_CMD:
  316. return "REFRESH_CMD";
  317. case State::POST_DELAY:
  318. return "POST_DELAY";
  319. case State::WAIT_BUSY:
  320. return "WAIT_BUSY";
  321. case State::DONE:
  322. return "DONE";
  323. }
  324. return "?";
  325. }
  326. const EpdPanelDescriptor *desc_{nullptr};
  327. GPIOPin *cs_{nullptr};
  328. GPIOPin *dc_{nullptr};
  329. GPIOPin *rst_{nullptr};
  330. GPIOPin *busy_{nullptr};
  331. EpdSPIDevice *spi_{nullptr};
  332. State state_{State::IDLE};
  333. uint32_t cursor_{0};
  334. CmdPhase cmd_phase_{CmdPhase::BEFORE_DELAY};
  335. uint8_t plane_{0};
  336. const uint8_t *planes_[2]{nullptr, nullptr};
  337. uint32_t plane_bytes_{0};
  338. uint32_t deadline_{0};
  339. State delay_return_state_{State::DONE};
  340. uint32_t busy_wait_deadline_{0};
  341. State busy_wait_next_{State::DONE};
  342. };
  343. } // namespace esphome::gxepd2