GxEPD2 for Arduino SPI E-Paper Displays

GxEPD2 targets SPI panels with model-specific drivers

GxEPD2 addresses a specific hardware problem: Arduino projects need a practical way to draw graphics and text on SPI e-paper panels without treating every display as a generic framebuffer. The library targets panels from Dalian Good Display and Waveshare boards that use the same panels. Its support list includes black and white displays, black and white with red, black and white with yellow, flexible panels, DES variants, and four-color models.

The library is not a single generic e-paper driver. The README lists panel names, resolutions, and controller identifiers, including GDEW0102T4, GDEH0154D67, GDEY029F51H, and GDEW042T2. That distinction matters because panel resolution, controller behavior, refresh sequence, and electrical requirements are not interchangeable. A panel with similar size may still require a different class or initialization sequence.

The intended users are Arduino developers working with supported Good Display hardware, Waveshare e-paper boards, and compatible panels. The repository's primary language is C, with examples organized around displays, page rendering, callbacks, serial flash, storage filesystems, Wi-Fi certificates, and multi-display configurations. The library uses Adafruit_GFX for graphics and text, so existing drawing code based on that API is the intended starting point.

Paged drawing keeps memory use within Arduino limits

The central design choice in GxEPD2 is paged drawing. The README says the library uses a picture loop to limit RAM use and cope with panels that lack single-pixel update support. The application selects the page height through a template parameter named `page_height`, with `GxEPD2_Example` serving as the documented reference.

Instead of requiring a complete screen buffer, the application draws a section of the image and sends that section to the panel. The README describes two related interfaces. One uses a picture loop with Adafruit_GFX methods. The other uses `drawPaged()` and `drawCallback()`, where the callback is invoked as many times as needed. The documented signature is:

void drawPaged(void (*drawCallback)(const void*), const void* pv)

This approach fits microcontrollers whose available RAM is smaller than the panel's complete bitmap. The trade-off is that the application must tolerate repeated drawing callbacks and panel refreshes instead of treating each display operation as one immediate full-screen operation. Paged drawing also adds a structural requirement to the drawing code: the callback must be written so it can render the requested page.

For projects with sufficient memory, GxEPD2 offers a different path. Setting `page_height` to the display height selects a full-screen buffer. The application can then draw with Adafruit_GFX methods and call `display()`, or it can continue using the page loop and callback. This makes the library useful for both small Arduino-class boards and more capable systems, although the README does not quantify the memory required for each panel size.

GxEPD2 installation begins with the Arduino library workflow

The README identifies GxEPD2 as an Arduino display library, but it does not document a command such as `arduino-cli`, `platformio`, or a package installation procedure. It therefore does not provide a reproducible installation command that can be copied here. The repository contains `library.properties`, a `src/` directory, and an `examples/` directory, which are consistent with an Arduino library layout.

For a first use, obtain the library from the repository and install it through the Arduino library workflow used by the target Arduino environment. The repository does not specify a release archive command, branch checkout command, or package-manager command, so none is invented here. After installation, open the example corresponding to the selected panel rather than adapting an unrelated example blindly. The `examples/GxEPD2_HelloWorld/` directory is the narrow starting point for a first display operation, while `examples/GxEPD2_Example/` demonstrates broader library options.

The next required decision is the panel class. The README lists supported panel models and controllers, but the excerpt ends while listing larger Good Display panels. Confirm the exact model in the complete supported list or in the relevant header files before selecting a class. Also inspect `ConnectingHardware.md` and the example wiring because the electrical instructions are more consequential than a minor API choice.

Wiring and reset behavior create hardware-specific failure modes

GxEPD2's documentation gives unusually specific electrical warnings. The display panels use a 3.3V supply and 3.3V data lines. The README says not to connect data lines directly to 5V Arduino pins and recommends a 4k7/10k resistor divider as one possible solution. It explicitly says that a series resistor alone is not sufficient for reliable operation because of back-feed through protection diodes. A ground connection is also required.

The wiring solution depends on the board and connection method. The README warns that a 4k7/10k divider may not work with flat cable extensions or the Waveshare 4.2 board, where a level converter may be needed. It distinguishes newer Waveshare display boards that include level converters and a series regulator, described as safe for 5V, from boards that do not. ESP8266 users may need a 3k3 pull-down on `SS` for boards with level converters.

Reset behavior is another likely source of failure. Some Waveshare boards with a "clever" reset circuit may require a shortened reset pulse. The documented initialization for those boards is `init(115200, true, 2, false)`. The same boards need a 1k pull-up on `RST` for ESP8266, or a different reset pin. Newer Waveshare boards may also have a `PWR` control pin that must be pulled high. For the Universal e-Paper Raw Panel Driver HAT Rev 2.3, the README specifically says that `PWR` must be connected to VCC or driven high.

These constraints mean that a display that fails to wake, update, or initialize may have a hardware cause even when the sketch contains the expected GxEPD2 calls. The project does not present a universal wiring diagram that eliminates these board-specific differences.

Bitmap and callback APIs broaden the rendering workflow

Beyond ordinary graphics and text, GxEPD2 exposes low-level bitmap drawing support. The README says bitmap operations can target the controller memory and the screen. Applications can call the relevant methods through a template class instance, which forwards them to the base display class, or instantiate a base display class and call its methods directly.

The examples also show that GxEPD2 is intended to sit inside larger Arduino applications. `GxEPD2_SD_Example`, `GxEPD2_SerialFlash_Example`, `GxEPD2_Spiffs_Example`, and the loader examples indicate workflows involving stored images or assets. `GxEPD2_RotaryUsingBusyCallback` addresses a device using the display's busy callback, while `GxEPD2_WiFi_Example` and certificate-store examples extend the project beyond local rendering. These directory names establish the scope of the examples, but the README excerpt does not provide their exact board definitions, pin assignments, or complete sketches.

The API therefore supports two distinct styles. Callers who want Adafruit_GFX primitives can draw through a paged loop or full-screen buffer. Callers who need direct controller or bitmap access can use the lower-level methods. That breadth is useful for projects that load prepared images, but it also makes panel selection and electrical configuration part of the application design rather than a detail that the library can infer.

GxEPD2 has a focused scope and a restrictive collaboration policy

Compared with a general-purpose Arduino graphics abstraction, GxEPD2 concentrates on SPI e-paper hardware, panel-specific initialization, refresh behavior, and memory-conscious rendering. The alternative approach would be to write a custom driver for one exact panel or use a generic display abstraction that treats the panel as a conventional screen. Such an approach can offer direct control, but the developer must implement the controller protocol, buffering, refresh sequence, and hardware warnings independently.

GxEPD2's practical advantage is the amount of panel-specific information it already associates with named displays. Its limitation is that the abstraction does not erase hardware differences. Resolution, controller, voltage, reset circuitry, and power control remain exposed in the selection and wiring process. A library user still needs to verify that the physical panel matches the class and that the chosen Arduino board supplies suitable signals.

Maintenance is supported by the repository history. The repository is not archived, and the last push was on 2026-04-19. Releases 1.6.9, 1.6.8, and 1.6.7 were published on 2026-04-19, 2026-03-16, and 2026-02-08 respectively. The README does not document a compatibility policy or migration guide, so upgrade cost must be assessed by checking the selected example and panel header after updating the library. The project is licensed under GPL-3.0. Any distribution or integration implications of that license need to be reviewed separately; the README does not provide legal guidance.

Editorial conclusion

Adopt GxEPD2 when your Arduino project uses a supported SPI e-paper panel and needs graphics with either paged or full-screen rendering. Do not choose it solely because a panel has similar dimensions. Verify the exact panel model, controller, voltage requirements, reset behavior, and whether the board includes suitable level conversion before writing hardware code.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. ZinggJM/GxEPD2 on GitHub