GxEPD2 (community library)

Summary

Arduino Display Library for SPI E-Paper displays from Dalian Good Display and Waveshare. Requires HW SPI and Adafruit_GFX. Caution: these e-papers require 3.3V supply AND data lines!

Library Read Me

This content is provided by the library maintainer and has not been validated or approved.

GxEPD2

Arduino Display Library for SPI E-Paper Displays

• With full Graphics and Text support using Adafruit_GFX

• For SPI e-paper displays from Dalian Good Display

• and SPI e-paper boards from Waveshare

important note :

• the display panels are for 3.3V supply and 3.3V data lines
• never connect data lines directly to 5V Arduino data pins, use e.g. 4k7/10k resistor divider
• series resistor only is not enough for reliable operation (back-feed effect through protection diodes)
• 4k7/10k resistor divider may not work with flat cable extensions or Waveshare 4.2 board, use level converter then
• do not forget to connect GND
• the actual Waveshare display boards now have level converters and series regulator, safe for 5V
• use 4k7 pull-down on SS for ESP8266 for boards with level converters

Paged Drawing, Picture Loop

• This library uses paged drawing to limit RAM use and cope with missing single pixel update support
• buffer size can be selected in the application by template parameter page_height, see GxEPD2_Example
• Paged drawing is implemented as picture loop, like in U8G2 (Oliver Kraus)
• see https://github.com/olikraus/u8glib/wiki/tpictureloop
• Paged drawing is also available using drawPaged() and drawCallback(), like in GxEPD
• // GxEPD style paged drawing; drawCallback() is called as many times as needed
• void drawPaged(void (*drawCallback)(const void*), const void* pv)
• paged drawing is done using Adafruit_GFX methods inside picture loop or drawCallback

Full Screen Buffer Support

• full screen buffer is selected by setting template parameter page_height to display height
• drawing to full screen buffer is done using Adafruit_GFX methods without picture loop or drawCallback
• and then calling method display()

Low Level Bitmap Drawing Support

• bitmap drawing support to the controller memory and screen is available:
• either through the template class instance methods that forward calls to the base display class
• or directly using an instance of a base display class and calling its methods directly

Supporting Arduino Forum Topics:

• Waveshare e-paper displays with SPI: http://forum.arduino.cc/index.php?topic=487007.0
• Good Dispay ePaper for Arduino : https://forum.arduino.cc/index.php?topic=436411.0

Note on documentation

• GxEPD2 uses Adafruit_GFX for Graphics and Text support, which is well documented there
• GxEPD2 uses meaningful method names, and has some comments in the header files
• consult the header files GxEPD2_BW.h, GxEPD2_3C.h and GxEPD2_GFX.h
• for the concept of paged drawing and picture loop see:
• https://github.com/olikraus/u8glib/wiki/tpictureloop

Supported SPI e-paper panels from Good Display:

• GDEP015OC1 1.54" b/w
• GDEW0154Z04 1.54" b/w/r 200x200
• GDE0213B1 2.13" b/w
• GDEH0213B72 2.13" b/w, replacement for GDE0213B1
• GDEH0213B73 2.13" b/w, new replacement for GDE0213B1, GDEH0213B72
• GDEW0213I5F 2.13" b/w flexible
• GDEW0213Z16 2.13" b/w/r
• GDEH029A1 2.9" b/w
• GDEW029T5 2.9" b/w
• GDEW029Z10 2.9" b/w/r
• GDEW026T0 2.6" b/w
• GDEW027C44 2.7" b/w/r
• GDEW027W3 2.7" b/w
• GDEW0371W7 3.7" b/w
• GDEW042T2 4.2" b/w
• GDEW042Z15 4.2" b/w/r
• GDEW0583T7 5.83" b/w
• GDEW075T8 7.5" b/w
• GDEW075Z09 7.5" b/w/r
• GDEW075Z08 7.5" b/w/r 800x480

  Supported SPI e-paper panels & boards from Waveshare: compare with Good Display, same panel

  other supported panels

• ED060SCT 6" grey levels, on Waveshare e-Paper IT8951 Driver HAT

Version 1.2.0

• added "fast partial update" (differential update) for GDEW0371W7 3.7" b/w 240x416
• improved differential update waveform for GDEW026T0 2.6" b/w 152x256
• fixed init code & improved differential update for GDEW042T2 4.2" b/w 300x400
• note that all differential refresh waveforms are a compromise (ghosting, big font use)
• parameters for differential waveform for these display can easily be changed for experimenting
• GDEW042T2 would have greyed background without sustain phase
• GDEW042T2 needs multiple full refreshes after extended use of partial updates

  Version 1.1.10

• added support for GDEH0213B73 2.13" b/w, replacement for GDE0213B1, GDEH0213B72
• added support for GDEW026T0 2.6" b/w 152x256
• added support for GDEW0371W7 3.7" b/w 240x416
• added support for GDEW075Z08 7.5" b/w/r 800x480
• GDEW075Z08 does allow (slow) partial update, set usePartialUpdate = false to disable for better image
• changed 4.2" b/w waveform table, for better result with actual panels

  Version 1.1.9

• note for ESP8266 when using SS for CS: (wiring suggestion)
• connect 4.7k pull-down from GPIO15 to GND if your board or shield has level converters
• fixes for large displays (use uint16_t for buffer index)

  Version 1.1.8

• fix for incomplete download in GxEPD2_WiFi_Example
• added missing method displayWindow() to GxEPD2_GFX base class
• fix and clean up of initial refresh for panels with differential update
• initial refresh needs to be full update, not "fast partial update", for these panels,
• as the screen content may differ from the "previous buffer" content.
• add clean of controller buffer(s) on initial write to controller, for partial update.

  Version 1.1.7

• enhanced support for full buffered, non-paged use, for processors with enough RAM
• use void display(bool partial_update_mode = false); corresponds to update() in GxEPD
• use added void displayWindow(uint16_t x, uint16_t y, uint16_t w, uint16_t h);
• use added writeImagePart(...), drawImagePart(...), used by displayWindow()
• added example GxEPD2_NotPagedExample.ino
• several fixes, e.g. parameter range check in setPartialWindow()

  Version 1.1.6

• added support for GDEH0213B72 2.13" b/w, replacement for GDE0213B1
• changed SPI speed for IT8951 Driver HAT to 24MHz for write, 10MHz for read
• minor fixes, e.g. centering of text bounding box in GxEPD2_Example

  Version 1.1.5

• added support for 6" ED060SCT on Waveshare e-Paper IT8951 Driver HAT
• uses 3.3V data lines, but 5V supply (~80mA active, ~20mA stand-by, sleep doesn't work)
• note: 5V supply needs to be exact and strong; 5V over diode from USB (e.g. Wemos D1 mini) doesn't work!
• note that the IT8951 Driver HAT is panel specific, with flash parameterized by supplier
• this is an initial version

  Version 1.1.4+

• added GxEPD2_WS_ESP32_Driver example for Waveshare ESP32 Driver Board

  Version 1.1.4

• eliminated double refresh for "fast partial update"
• moved wavetables to the driver classes
• added one explicit drawImage(...) and writeImage(...) method (for removed default paramter values for 1.1.3)
• added init method with added parameter initial, for re-init after processor deep sleep wakeup
• added init parameter pulldown_rst_mode, for special RST handling (not needed for waveshare shield)

  Version 1.1.3

• fixed wavetables for GDEW029T5 and GDEW0213I5F
• fixed drawImage(...) overloaded methods signature matching ambiguity

  Version 1.1.2

• added support for GDEW029T5
• fixed (added) clipping for partial window
• fixed (added) powerOff() after full update (partial update keeps power on)
• added hibernate() for minimum power use by displays that support it

  Version 1.1.1

• 2.7" b/w GDEW027W3 with fast partial update support, based on new demo code wavetable
• mapping suggestion added for Arduino MEGA
• NOTE: use voltage divider resistors for 5V Arduinos, series resistor is not reliable enough
• ConnectingHardware.md updated

  Version 1.1.0

• added support for GDEW0213I5F for 2.13" b/w 104x212 flexible display
• updated GxEPD2_WiFi_Example and GxEPD2_Spiffs_Loader to use BearSSL on ESP8266, for large bitmap downloads

  Version 1.0.9

• add GxEPD2_U8G2_Fonts_Example, e.g. for use of Umlauts ÄÖÜäéöü
• NOTE: you need to SAVE the modified example to a saveable location for UTF-8 characters to work

  Version 1.0.8

• add GxEPD2_SD_AVR_boards_added.h to GxEPD2_SD_AVR_Example
• with example definitions for non-AVR boards (low level display class use example)

  Version 1.0.7

• add GxEPD2_boards_added.h to GxEPD2_Example
• with example definitions for Arduino DUE and MKR1000

  Version 1.0.6

• add buffered drawing option to GxEPD2_WiFi_Example
• allows use with 1.54" 3-color 200x200 display, may also be useful for small bitmaps

  Version 1.0.5

• add buffered drawing option to GxEPD2_SD_Example and GxEPD2_Spiffs_Example
• allows use with 1.54" 3-color 200x200 display, may also be useful for small bitmaps

  Version 1.0.4

• add GxEPD2_GFX base class support (optional, selectable, uses slightly more code)
• base class GxEPD2_GFX can be used to pass references or pointers to the display instance as parameter
• add GxEPD2_GFX_MultiDisplayExample, uses GxEPD2_GFX reference parameter
• modify GxEPD2_MultiDisplayExample for ESP8266 (template issue: class expected instead of typename)

  Version 1.0.3

• fix GxEPD2_SD_Example & GxEPD2_SD_AVR_Example
• add GxEPD2_MultiDisplayExample (preliminary version)

  Version 1.0.2

• initial release version 1.0.2
• tested with ESP8266, ESP32, STM32F103C8T6, AVR Arduino (Pro Mini 3.3V)
• 1.54" 3-color GxEPD2_154c can be used with paging for AVR
• wave tables in program space, 4.2" b/w can be used with GxEPD2_SD_AVR_Example
• issues enabled and welcome, please use Forum Topic for enhancement suggestions

  Version 1.0.1

• pre-release test version
• GxEPD2_SD_AVR_Example added, has no graphics buffer to reduce RAM usage (base display class use)
• issues disabled so far, use Arduino Forum Topics instead
• in this version 1.54" 3-color GxEPD2_154c can only be used with full size buffer (or with no buffer base display class)

  Version 1.0.0

• preliminary version, under construction

Browse Library Files