a2nr
/
velxio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
velxio/test/test_epaper/autosearch/04_arduino_libraries.md

4.3 KiB
Raw Blame History

04 — Arduino libraries we must compile against

To "support" an ePaper panel in Velxio, the firmware libraries the user writes against must compile and their generated SPI traffic must hit our emulator's command/data state machine cleanly. There are four common families:

1. GxEPD2 by Jean-Marc Zingg — the de-facto standard

  • Repo: https://github.com/ZinggJM/GxEPD2
  • Library Manager name: GxEPD2 (latest 1.5.x as of 2026-04)
  • Architectures: AVR, SAMD, ESP8266, ESP32, RP2040, mbed, STM32
  • Depends on: Adafruit_GFX (graphics primitives)

Class hierarchy (relevant pieces only):

GxEPD2_BW<DRV, page_height>     — single-plane B/W
GxEPD2_3C<DRV, page_height>     — two-plane B/W/Red
GxEPD2_4G<DRV, page_height>     — 4-grey
GxEPD2_7C<DRV, page_height>     — 7-colour ACeP

Where DRV is one of ~80 driver classes named after the panel (e.g. GxEPD2_154_D67 for the 1.54" 200×200 SSD1681 panel). Each driver knows its controller's init sequence and command set; the user just instantiates the right one.

// Canonical "hello world"
#include <GxEPD2_BW.h>
GxEPD2_BW<GxEPD2_154_D67, GxEPD2_154_D67::HEIGHT> display(
    GxEPD2_154_D67(/*CS=*/ 5, /*DC=*/ 17, /*RST=*/ 16, /*BUSY=*/ 4));

void setup() {
  display.init();
  display.setFullWindow();
  display.firstPage();
  do { display.fillScreen(GxEPD_WHITE); display.setCursor(10, 30);
       display.print("Hello"); } while (display.nextPage());
}

The constructor's pin order is (CS, DC, RST, BUSY). Important for the emulator's pin_map — we must surface those four pin names verbatim.

2. Adafruit_EPD — Adafruit's official driver

  • Repo: https://github.com/adafruit/Adafruit_EPD
  • Library Manager name: Adafruit EPD
  • Architectures: SAMD, ESP32, ESP8266 (no AVR — too little RAM for full framebuffer)
  • Depends on: Adafruit_GFX, Adafruit_BusIO

Used heavily for the MagTag, 2.13" Featherwing etc. Driver classes are named per-controller rather than per-panel:

#include "Adafruit_SSD1681.h"
#define EPD_DC      6
#define EPD_CS      9
#define EPD_BUSY    -1
#define SRAM_CS     -1
#define EPD_RESET   -1
Adafruit_SSD1681 display(200, 200, EPD_DC, EPD_RESET, EPD_CS, SRAM_CS, EPD_BUSY);

Pin order here is (DC, RST, CS, SRAM_CS, BUSY) — totally different from GxEPD2. Both must be supported by the Velxio component's pin labels.

3. ESPHome waveshare_epaper

Used by users coming from Home Assistant. YAML configures the panel; the generated C++ uses the same SSD168x command flow. We don't need a dedicated path — if Adafruit_EPD compiles, ESPHome compiles.

4. Pervasive Displays (PDLS) library family

Library/board compatibility matrix

Library AVR (Uno) RP2040 (Pico) ESP32 ESP32-S3 ESP32-C3
GxEPD2 ✓ (only ≤2.13" — RAM) ✓ ✓ ✓ ✓
Adafruit_EPD ✗ (RAM) ✓ ✓ ✓ ✓
ESPHome waveshare ✗ ✗ ✓ ✓ ✓
Pervasive PDLS ✓ ✓ ✓ ✓ ✓

The "AVR ≤2.13"" caveat is because GxEPD2 needs panel_W * page_height / 8 bytes of SRAM. For 4.2" 400×300 with the default 8-row page_height that's 1.5 KB which fits Uno, but with 80-row pages (typical) it's 12 KB which doesn't.

Notes for the test harness

  • The cross-board compile test (test_compile_*) should bundle GxEPD2 and Adafruit_GFX as required libraries. Both ship to ~/Arduino/libraries/ via arduino-cli lib install GxEPD2 Adafruit_GFX.
  • The Velxio Library Manager UI already supports auto-installing libraries from a sketch's #include lines (see frontend/src/components/simulator/InstallLibrariesModal.tsx); the GxEPD2 #include should auto-trigger the install path on first compile.

Sources