Port real epd13in3e driver from vendor code; fix wire-raster stride bug
Build and push server image / test (push) Successful in 43s
Firmware build check / build-check (push) Successful in 2m47s
Build and push server image / build-and-push (push) Successful in 4m34s
Build and push server image / deploy (push) Failing after 1m27s

Vendored the panel's init/LUT/refresh register sequence from three
independent Waveshare reference drivers for this exact panel+controller
(RaspberryPi/c, ESP32, and the ESP32-S3-ePaper-13.3E6 ESP-IDF example),
which all agree byte-for-byte. The epd13in3e.c #error is gone; it
compiles clean and links (verified via /build-firmware ee02).

That vendor code also revealed the panel's SPI wire raster is a native
1200x1600 (portrait), not 1600x1200 as previously assumed -- rotated 90
degrees from the panel's landscape mount/marketing size. The old
assumption wasn't just a rotation bug: 1600x1200 and 1200x1600 don't
share a row stride, so packing at the wrong one would have shredded
images into a repeating diagonal garble on real hardware, not just
displayed them sideways. Fixed with a new PANEL_WIRE_TRANSPOSE in
image_pipeline.py, applied after the existing per-frame
ORIENTATION_TRANSPOSE, with a direction-agnostic regression test that
catches the stride bug specifically (a byte-count check alone can't,
since both orientations pack to the same total size).

A full ee02 build still fails, but no longer because of this driver --
main/{back,next,combo}_button.c call an ESP32-C6-only deep-sleep
GPIO-wakeup API with no ESP32-S3 fallback, a separate pre-existing gap
that was simply hidden behind the panel driver's old #error. See
docs/hardware.md for details; CI's continue-on-error on this board
stays in place until that's fixed too.
This commit is contained in:
2026-08-04 22:00:18 +00:00
parent fe5a2df074
commit 454c03586e
6 changed files with 464 additions and 160 deletions
@@ -5,31 +5,42 @@
#include "esp_err.h"
/* Waveshare 13.3" e-Paper (E) Spectra 6 panel, driven by Seeed's EE02
* board (XIAO ESP32-S3 Plus): 1600x1200, 4 bits/pixel packed
* 2-pixels-per-byte -- same packing convention and public function
* shapes as epd7in3e.h, just a different resolution, so main's own
* sources don't need to branch on which panel is active beyond
* main/epd_board.h's
* header selection. Confirmed from Waveshare's/Seeed's public product
* pages (270.40x202.80mm, 1600x1200px). NOT yet confirmed against the
* vendor's own reference driver code, which doesn't exist in this tree
* yet -- see epd13in3e.c's top comment and epd_init()'s stub. The panel
* is also driven as two halves over a shared bus with two independent
* chip-selects (see Kconfig's EPD_PIN_CS_MASTER/EPD_PIN_CS_SLAVE), unlike
* epd7in3e's single-CS interface -- that's an implementation detail of
* epd13in3e.c, not something callers of this header need to know about. */
#define EPD_WIDTH 1600
#define EPD_HEIGHT 1200
* board (XIAO ESP32-S3 Plus). The panel is marketed/mounted as a
* 1600x1200 landscape rectangle (270.40x202.80mm), but its SPI
* controller addresses a native raster of 1200 columns x 1600 rows --
* i.e. the wire format is portrait, rotated 90 degrees from how the
* panel physically hangs. Confirmed identically across three independent
* vendor sources: Waveshare's RaspberryPi/c and ESP32 reference drivers
* for this exact panel (E-paper_Separate_Program/13.3inch_e-Paper_E in
* waveshare/e-Paper), and Waveshare's own ESP-IDF example for their
* ESP32-S3-ePaper-13.3E6 driver board (a *different* carrier board than
* Seeed's EE02, but the same panel+controller, hence the same command
* bytes/geometry -- only the GPIO numbers differ, and those come from
* EE02-specific sources, see this component's Kconfig). All three define
* EPD_WIDTH=1200/EPD_HEIGHT=1600 and split each row into two 600-byte
* (300px) halves sent to independent chip-selects: EPD_PIN_CS_MASTER
* gets the left half, EPD_PIN_CS_SLAVE the right -- see epd13in3e.c.
*
* Getting this backwards (assuming the wire raster matches the
* 1600x1200 mount/marketing size) doesn't just rotate the image -- 1600
* and 1200 don't share a row stride with 1200 and 1600 the other way
* (800 bytes/row x 1200 rows vs 600 bytes/row x 1600 rows), so a mismatch
* here slices real image rows at the wrong byte offsets and shreds the
* picture into a repeating diagonal garble, not a clean rotation.
* server/app/image_pipeline.py's PANEL_WIRE_TRANSPOSE handles the
* corresponding rotation server-side before packing bytes for this
* panel_type -- this header and that dict must agree on which axis is
* native. */
#define EPD_WIDTH 1200
#define EPD_HEIGHT 1600
#define EPD_BYTES_PER_ROW ((EPD_WIDTH + 1) / 2)
#define EPD_FRAME_BYTES (EPD_BYTES_PER_ROW * EPD_HEIGHT)
/* Same 6-ink Spectra family as the 7.3" panel, so the same 6 named
* colors -- but whether this panel's controller uses the SAME nibble
* values as epd7in3e.h's epd_color_t is UNCONFIRMED (see this file's own
* top comment). Left identical to epd7in3e.h's values as the working
* assumption; correct these against the vendor demo code once it exists,
* alongside server/app/image_pipeline.py's PANEL_CODES if they turn out
* to differ (see that file's own comment on PANEL_CODES). */
/* Same 6-ink Spectra family as the 7.3" panel, and (now confirmed by the
* same three vendor sources as the geometry above) the same 4-bit nibble
* codes as epd7in3e.h's epd_color_t -- matches
* server/app/image_pipeline.py's PANEL_CODES unconditionally, no
* panel-specific table needed there. */
typedef enum {
EPD_COLOR_BLACK = 0x0,
EPD_COLOR_WHITE = 0x1,