CALE IDF

E-paper component driver for the ESP-IDF framework and compatible with ESP32 / ESP32S2

CalEPD is a C++ component for ESP-IDF that can be used as a library for Epaper displays. My intention was to create a library similar to GxEPD but only to be used in IDF >= v.4.0 that it compiles without Arduino libraries and that it follows as much as possible modern Object-Oriented C++.

Compiling

The only requirement is to have the latest Espressif IDF Framework installed and an ESP32 ready to be flashed. At the moment of writing this, it is tested using IDF version 4.0. Please note that last updates are still not in master so after pulling this repository just checkout:

develop is the latest branch where we are optimizing the Class and OOP structure. (ex refactor/oop)

master is the stable branch where tested epaper model classes will be merged only after successful testing.

Make sure to check out the right branch before compiling and flashing your ESP32

If it's an ESP32:

idf.py -D IDF_TARGET=esp32 menuconfig

If it's an ESP32S2:

idf.py -D IDF_TARGET=esp32s2 menuconfig

Make sure to edit "Display configuration" in the Kconfig menuoptions and adjust it with your Epaper GPIOs.

Configuring the Epaper model

Check your model in this wiki index. It’s labeled ModelName.h so you can copy and paste in your include. To use it your display class just have to add this 2 lines in your main.cpp

    // This declares an SPI class
    EspSpi io;
    // Injects this io in the Display for model Gdew0213i5f (2.13" b/w)
    Gdew0213i5f display(io);

After this point, you can already call all the functions in the display component:

    display.init(true); // true to activate debug
    display.setRotation(1);
    display.fillScreen(EPD_WHITE);

This display class, takes care of initialization of your epaper display, since every model is different and needs different commands for bootstrapping.

DEBUG lowers also the SPI speed to 50000 Hertz (0.05 Mhz), since is what I use to sniff with an ESP32 slave SPI, to check if my commands are being sent correctly. Just use non-debug for full 4 Mhz speed or just override it in the EspSpi.cpp class

And also the Adafruit GFX functions like:

    //#include <Fonts/FreeMono9pt7b.h> // Don't forget to include Adafruit font header
    display.setFont(&FreeMono9pt7b);
    display.setTextColor(GxEPD_BLACK);
    display.setCursor(20,20);
    display.println("Hello world!");

Check our cale.cpp example to see more details.

How to add my custom epaper class

Basically you need to copy the header class in components/CalEPD (/include) and also a model class that is similar to your display model (Ex. gdew0213i5f.cpp copy to yourdisplay.cpp)

If your display is already implemented by Jean-Marc GxEPD classes you can just reverse engineer it and use the same SPI commands. Warning: It's not a task for the faint of the heart! And also is not the goal of CalEPD to be a GxEPD clon for Espressif IDF. The idea is that once you get it working, to test fully every possible thing your display can achieve, with an exclamation mark in "Partial refresh" that is not working as it should on many models. Basically, since no one has read in detail the documentation of the Eink controllers.

Why to use this over GxEPD

GxEPD is perfectly fine for Arduino projects and it's a solid library like the 490+ Stars indicate. The mission of this new component is to have a similar library for ESP-IDF that is easier to understand. If possible strictly meeting these requirements:

• Extendable
• Maintainable
• Object-Oriented Programming with human-readable code and function names
• Easy to add a new Epaper display drivers
• Easy to implement and send stuff to your Epaper displays
• Human-understandable
• Well documented
• ESP-IDF only (No Arduino classes)

The only exception of Arduino classes is that we are including in this first version Print and Printable since Adafruit uses them. But that will change in the future. The final idea is to have a bridge GFX class that will let you use also another GFX library. And all that configurable using great Kconfig menuoption in IDF. So no GPIOs constant in your code, this will be configurable with a human interface, and then will be declared in compilation time. The well documented is also an important point. To go deep in Hardware providers documentation and experiment with a component that is well documented so we can change parameters and experiment with different configurations.

Please follow/star this repository if you are interested in the development. And if you discover a bug or want to optimize any part of the code, pull requests are more than welcome.

Thanks for your interest in CalEPD,

Martin Fasani

Component creator - derived from CALE.es project