EPD Driver

The M5PAPER is equipped with a 540*960 @4.7" e-ink display, supporting 16-level grayscale display. In the M5.begin() initialization, an instance M5EPD_Driver EPD = M5EPD_Driver() is already created and initialized. Through the screen driver below, you can push the drawn content data to the screen.

begin()

Function:

Initialize the I2C bus

Function prototype:

m5epd_err_t begin(int8_t sck, int8_t mosi, int8_t miso, int8_t cs, int8_t busy, int8_t rst = -1)

Usage example:

#include <M5EPD.h>

void setup() {
    M5.EPD.begin(M5EPD_SCK_PIN, M5EPD_MOSI_PIN, M5EPD_MISO_PIN, M5EPD_CS_PIN,
                 M5EPD_BUSY_PIN);
}

void loop() {}

Clear()

Function:

Clear the screen content

Parameter	Description
true	Initialize the screen with UPDATE_MODE_INIT mode
false	Clear the 8951 cache

Function prototype:

m5epd_err_t Clear(bool init = false)

Usage example:

#include <M5EPD.h>

void setup() {
    M5.begin();
    M5.EPD.Clear(true);
}

void loop() {}

SetRotation()

Function:

Set screen rotation angle, usually set to 90°

Function prototype:

m5epd_err_t SetRotation(uint16_t rotate = IT8951_ROTATE_0)

Usage example:

#include <M5EPD.h>

void setup() {
    M5.begin();
    M5.EPD.Clear(true);
    M5.EPD.SetRotation(90);
}

void loop() {}

GetRotate()

Function:

Read the screen rotation angle

Function prototype:

uint8_t GetRotate(void)

GetDirection()

Function:

Read the screen direction

Function prototype:

uint8_t GetDirection(void)

UpdateFull()

Function:

Refresh the data in the cache area to the full screen with the specified mode

Function prototype:

m5epd_err_t UpdateFull(m5epd_update_mode_t mode)

UpdateArea()

Function:

Refresh the data in the cache area to the specified area of the screen with the specified mode

Function prototype:

m5epd_err_t UpdateArea(uint16_t x, uint16_t y, uint16_t w, uint16_t h, m5epd_update_mode_t mode)

UpdateCount()

Function:

Get the refresh count

Function prototype:

uint16_t UpdateCount(void)

ResetUpdateCount()

Function:

Reset the refresh count

Function prototype:

void CheckAFSR(void)

CheckAFSR()

Function:

Check if 8951 is busy

Function prototype:

m5epd_err_t CheckAFSR(void)

SetColorReverse()

Function:

Set color inversion

Function prototype:

void SetColorReverse(bool is_reverse)

WriteFullGram4bpp()

Function:

Write a full frame of data / 4 bits per pixel

Function prototype:

m5epd_err_t WriteFullGram4bpp(const uint8_t *gram)

WritePartGram4bpp()

Function:

Write partial data in the specified area / 4 bits per pixel

Function prototype:

m5epd_err_t WritePartGram4bpp(uint16_t x, uint16_t y, uint16_t w, uint16_t h, const uint8_t *gram)

FillPartGram4bpp()

Function:

Fill the specified area with specified data

Function prototype:

m5epd_err_t FillPartGram4bpp(uint16_t x, uint16_t y, uint16_t w, uint16_t h, uint16_t data)

Canvas

This library uses the Canvas class for pattern drawing, which provides various drawing APIs (including drawing strings, rectangles, triangles, circles, image data, etc.). Before using, you need to create a canvas instance and pass in the screen driver, as shown in the code below.

#include <M5EPD.h>

M5EPD_Canvas canvas(&M5.EPD);

Refresh Modes

When using pushCanvas, we need to pass in a refresh mode parameter. The m5epd_update_mode_t in this library has enumerated

several different refresh modes, here are their characteristics explained.


typedef enum
{                             //   Ghosting  Update Time  Usage
    UPDATE_MODE_INIT    = 0,  // * N/A       2000ms       Screen initialization,
    UPDATE_MODE_DU      = 1,  //   Low       260ms        Suitable for monochrome menus, text input, touch feedback 1bit black and white, ghosting present.
    UPDATE_MODE_GC16    = 2,  // * Very Low  450ms        Suitable for high quality image display Flash black then refresh
    UPDATE_MODE_GL16    = 3,  // * Medium    450ms        Suitable for text display with a white background No flash black
    UPDATE_MODE_GLR16   = 4,  //   Low       450ms        Suitable for text display with a white background No flash black
    UPDATE_MODE_GLD16   = 5,  //   Low       450ms        Suitable for text and graphic display with a white background No flash black
    UPDATE_MODE_DU4     = 6,  // * Medium    120ms        Reduces contrast, suitable for situations requiring quick page switching 1bit black and white Slightly faster than DU, larger ghosting compared to DU
    UPDATE_MODE_A2      = 7,  //   Medium    290ms        Suitable for menus, touch feedback, anti-aliasing text 2bit grayscale, ghosting present
    UPDATE_MODE_NONE    = 8   //                          Upload to 8951 cache Do not refresh, can accumulate multiple uploads, then refresh all content at once.
} m5epd_update_mode_t;        // The ones marked with `*` are more commonly used refresh modes

The refresh modes with relatively good quality include UPDATE_MODE_GC16, UPDATE_MODE_GL16, UPDATE_MODE_GLR16, UPDATE_MODE_GLD16
The M5Paper's e-ink screen supports 16-level grayscale display, the valid range for the color parameter in the API below is 0~15

image2gray tool

createCanvas()

Function:

Create Canvas (Before starting to draw, we need to use the Canvas instance to create a drawing area)

Function prototype:

void *createCanvas(int16_t width, int16_t height, uint8_t frames = 1)

Usage example:

#include <M5EPD.h>

M5EPD_Canvas canvas(&M5.EPD);

void setup() {
    M5.begin();
    M5.EPD.SetRotation(90);
    M5.EPD.Clear(true);
    M5.RTC.begin();
    canvas.createCanvas(500, 300);  // Create a 500*300 drawing area. Create a 500*300 drawing area
}

void loop() {}

deleteCanvas()

Function:

Delete Canvas and release memory

Function prototype:

void deleteCanvas(void)

Usage example:

#include <M5EPD.h>

M5EPD_Canvas canvas(&M5.EPD);

void setup() {
    M5.begin();
    M5.EPD.SetRotation(90);
    M5.EPD.Clear(true);
    M5.RTC.begin();
    canvas.createCanvas(500, 300);  // Create a 500*300 drawing area. Create a 500*300 drawing area
    canvas.deleteCanvas();  // Delete the drawing area. Delete the drawing area
}

void loop() {}

Pushing Canvas

After completing content drawing using the drawing API, we need to use the push API to push the drawing area to the screen. After pushing, the screen driver needs some time to refresh the drawing. Please avoid turning off the device before the drawing is completed.

// Re-implement functions

frameBuffer()

Function:

Get the Canvas cache area pointer

Function prototype:

void *frameBuffer(int8_t f = 1)

pushCanvas()

Function:

Push Canvas to the screen at position 0,0, specifying the refresh mode

Push Canvas to the specified area of the screen, specifying the refresh mode

Function prototype:

void pushCanvas(m5epd_update_mode_t mode)

void pushCanvas(int32_t x, int32_t y, m5epd_update_mode_t mode)

Usage example:

#include <M5EPD.h>

M5EPD_Canvas canvas(&M5.EPD);

void setup() {
    M5.begin();
    M5.EPD.Clear(true);
    M5.RTC.begin();
    canvas.createCanvas(500, 300);  // Create a 500*300 drawing area. Create a 500*300 drawing

 area
    canvas.setTextSize(3);
    canvas.drawString("Hello World!", 0, 0);
    canvas.drawString("Hello M5Stack!", 0, 20);
    canvas.pushCanvas(100, 100, UPDATE_MODE_DU4);  // Push the canvas to display. Push the canvas to the screen
}

void loop() {}

pushToCanvas()

Function:

Draw to the specified Canvas

Function prototype:

void pushToCanvas(int32_t x, int32_t y, M5EPD_Canvas* canvas)

Common APIs

fillCanvas()

Function:

Fill the drawing area with a certain color

Function prototype:

void fillCanvas(uint32_t color)

Usage example:

#include <M5EPD.h>

M5EPD_Canvas canvas(&M5.EPD);

void setup() {
    M5.begin();
    M5.EPD.Clear(true);
    M5.RTC.begin();
    canvas.createCanvas(500, 300);  // Create a 500*300 drawing area. Create a 500*300 drawing area
    canvas.setTextSize(3);
    canvas.fillCanvas(0xFFFF);  // Fill the drawn area with black. Fill the drawn area with black
    canvas.pushCanvas(100, 100, UPDATE_MODE_DU4);  // Push the canvas to display. Push the canvas to the screen
}

void loop() {}

pushImage()

Function:

Push Buffer data

Function prototype:

void pushImage(int32_t x, int32_t y, int32_t w, int32_t h, the uint8_t *data) void pushImage(int32_t x, int32_t y, int32_t w, int32_t h, uint8_t transp, the uint8_t *data)

readPixel()

Function:

Read pixel color

Function prototype:

uint16_t readPixel(int32_t x, int32_t y)

Usage example:

#include <M5EPD.h>

M5EPD_Canvas canvas(&M5.EPD);

void setup() {
    M5.begin();
    M5.EPD.Clear(true);
    M5.RTC.begin();
    canvas.createCanvas(500, 300);  // Create a 500*300 drawing area. Create a 500*300 drawing area
    canvas.setTextSize(3);
    canvas.fillCanvas(0xFFFF);  // Fill the drawn area with black. Fill the drawn area with black
    canvas.pushCanvas(100, 100, UPDATE_MODE_DU4);  // Push the canvas to display. Push the canvas to the screen
    Serial.print(canvas.readPixel(100, 100));
}

void loop() {}

drawPixel()

Function:

Draw a pixel

Function prototype:

void drawPixel(int32_t x, int32_t y, uint32_t color)

fillCenterSquare()

Function:

Draw a square from the center point

Function prototype:

void fillCenterSquare(int32_t cx, int32_t cy, uint16_t w, uint8_t color)

qrcode()

Function:

Draw a QR code

Function prototype:

void qrcode(const char *string, uint16_t x = 50, uint16_t y = 10, uint16_t width = 220, uint8_t version = 6)

void qrcode(const String &string, uint16_t x = 50, uint16_t y = 10, uint16_t width = 220, uint8_t version = 6)

getBufferSize()

Function:

Read the buffer size of the current Canvas image

Function prototype:

uint32_t getBufferSize(void)

ReverseColor()

Function:

Set inversion

Function prototype:

void ReverseColor(void)

ReversePartColor()

Function:

Set local inversion

Function prototype:

void ReversePartColor(int32_t x, int32_t y, int32_t w, int32_t h)

operator()

Function:

Canvas copy

Function prototype:

void operator=(const M5EPD_Canvas &src)

setDriver()

Function:

Set screen driver

Function prototype:

void setDriver(M5EPD_Driver *driver)

JPG/BMP/PNG

Function: Use Bmp file data to draw images

bool drawBmpFile(fs::FS &fs, const char *path, uint16_t x, uint16_t y);
bool drawBmpFile(fs::FS &fs, String path, uint16_t x, uint16_t y);

Function: Use Jpg file data to draw images

bool draw

JpgFile(fs::FS &fs, the char *path, uint16_t x = 0,
                uint16_t y = 0, uint16_t maxWidth = 0, uint16_t maxHeight = 0,
                uint16_t offX = 0, uint16_t offY = 0,
                jpeg_div_t scale = JPEG_DIV_NONE);

bool drawJpgFile(fs::FS &fs, String path, uint16_t x = 0,
                uint16_t y = 0, uint16_t maxWidth = 0, uint16_t maxHeight = 0,
                uint16_t offX = 0, uint16_t offY = 0,
                jpeg_div_t scale = JPEG_DIV_NONE);

Function: Use Png file data to draw images

bool drawPngFile(fs::FS &fs, the char *path, uint16_t x = 0, uint16_t y = 0,
                uint16_t maxWidth = 0, uint16_t maxHeight = 0,
                uint16_t offX = 0, uint16_t offY = 0,
                double scale = 1.0, uint8_t alphaThreshold = 127);

bool drawPngFile(fs::FS &fs, String path, uint16_t x = 0, uint16_t y = 0,
                uint16_t maxWidth = 0, uint16_t maxHeight = 0,
                uint16_t offX = 0, uint16_t offY = 0,
                double scale = 1.0, uint8_t alphaThreshold = 127);

Function: Use memory Jpg data to draw images

bool drawJpg(const uint8_t *jpg_data, size_t jpg_len, uint16_t x = 0,
                uint16_t y = 0, uint16_t maxWidth = 0, uint16_t maxHeight = 0,
                uint16_t offX = 0, uint16_t offY = 0,
                jpeg_div_t scale = JPEG_DIV_NONE);

Function: Use Jpg Url/network resource data to draw images

bool drawJpgUrl(String url, uint16_t x = 0,
                        uint16_t y = 0, uint16_t maxWidth = 0, uint16_t maxHeight = 0,
                        uint16_t offX = 0, uint16_t offY = 0, jpeg_div_t scale = JPEG_DIV_NONE);

Function: Use Png Url/network resource data to draw images

bool drawPngUrl(const char *url, uint16_t x = 0, uint16_t y = 0,
            uint16_t maxWidth = 0, uint16_t maxHeight = 0,
            uint16_t offX = 0, uint16_t offY = 0,
            double scale = 1.0, uint8_t alphaThreshold = 127);

Usage example:

#include <M5EPD.h>
#include <WiFi.h>


void setup()
{
    M5.begin();
    M5.EPD.SetRotation(90);
    M5.EPD.Clear(true);
    WiFi.begin("WIFI-SSID", "WIFI-PASSWORD");

    while (WiFi.status() != WL_CONNECTED) {
        delay(500);
        Serial.print(".");
    }

    canvas.createCanvas(540, 960);
    canvas.setTextSize(3);
    canvas.drawJpgUrl("https://m5stack.oss-cn-shenzhen.aliyuncs.com/image/example_pic/flower.jpg");
    canvas.pushCanvas(0,0,UPDATE_MODE_GC16);
}

void loop()
{
}

Text

Below are some commonly used text drawing APIs.

setTextColor()

Function:

Set font color

Function prototype:

void setTextColor(uint16_t color)

void setTextColor(uint16_t fgcolor, uint16_t bgcolor)

setTextSize()

Function:

Set font size

Function prototype:

void setTextSize(uint8_t size)

setTextWrap()

Function:

Set text wrapping

Function prototype:

void setTextWrap(boolean wrapX, boolean wrapY = false)

setTextDatum()

Function:

Set text datum

Function prototype:

void setTextDatum(uint8_t datum)

setTextPadding()

Function:

Set text padding

Function prototype:

void setTextPadding(uint16_t x_width)

setTextArea()

Function:

Set the font output area, you can use printf to output text in this area, and the text will automatically wrap

Function prototype:

void setTextArea(uint16_t x, uint16_t y, uint16_t w, uint16_t h)

setTextFillMargin()

Function:

Set the fill margin of the background

color for the string

Function prototype:

void setTextFillMargin(uint16_t left, uint16_t right, int16_t top, int16_t bottom)

setTextLineSpace()

Function:

Set the line spacing when outputting strings automatically wrapping with printf

Function prototype:

void setTextLineSpace(uint8_t space)

loadFont()

Function:

Load TTF font file from filesystem, supports SPIFFS and SD

Function prototype:

esp_err_t loadFont(String path, fs::FS &ffs)

loadFont()

Function:

Load TTF file from a binary array pointed to by a pointer, does not support larger TTF files

Function prototype:

esp_err_t loadFont(const uint8_t *memory_ptr, uint32_t length)

unloadFont()

Function:

Unload font file

Function prototype:

esp_err_t unloadFont()

createRender()

Function:

Create a TTF renderer of specified font size, optional cache size. Larger cache can cache more rendered fonts, significantly improving performance when rendering a large amount of text. The cache will arrange glyph storage automatically based on glyph usage frequency as priority.

Function prototype:

esp_err_t createRender(uint16_t size, uint16_t cache_size = 1)

destoryRender()

Function:

Destroy the TTF renderer of specified font size

Function prototype:

esp_err_t destoryRender(uint16_t size)

preRender()

Function:

Pre-render specified characters and store them in the cache area

Function prototype:

esp_err_t preRender(uint16_t code)

isRenderExist()

Function:

Determine if the renderer of the specified size exists

Function prototype:

bool isRenderExist(uint16_t size)

getNumOfRender()

Function:

Get the number of existing renderers

Function prototype:

uint32_t getNumOfRender(void)

useFreetypeFont()

Function:

Set whether to use TTF renderer

Function prototype:

void useFreetypeFont(bool isuse = true)

drawNumber()

Function:

Draw an integer

Function prototype:

int16_t drawNumber(long long_num, int32_t poX, int32_t poY, uint8_t font)

int16_t drawNumber(long long_num, int32_t poX, int32_t poY)

drawFloat()

Function:

Draw a floating-point number

Function prototype:

int16_t drawFloat(float floatNumber, uint8_t decimal, int32_t poX, int32_t poY, uint8_t font)

int16_t drawFloat(float floatNumber, uint8_t decimal, int32_t poX, int32_t poY)

drawString()

Function:

Draw a string

Function prototype:

int16_t drawString(const char *string, int32_t poX, int32_t poY, uint8_t font)

int16_t drawString(const char *string, int32_t poX, int32_t poY)

int16_t drawString(const String &string, int32_t poX, int32_t poY, uint8_t font)

int16_t drawString(const String &string, int32_t poX, int32_t poY)

decodeUTF8()

Function:

Decode UTF8 string/return Unicode value

Function prototype:

uint16_t decodeUTF8(uint8_t *buf, uint16_t *index, uint16_t remaining)

uint16_t decodeUTF8(uint8_t *buf, uint16_t *index, uint16_t remaining, uint8_t *length)

drawChar()

Function:

Draw a character

Function prototype:

int16_t drawChar(uint16_t uniCode, int32_t x, int32_t y)

int16_t drawChar(uint16_t uniCode, int32_t x, int32_t y, uint8_t font)

void drawChar(int32_t x, int32_t y, uint16_t c, uint32_t color, uint32_t bg, uint8_t size)

textWidth()

Function:

Get text width

Function prototype:

int16_t textWidth(const char *string, uint8_t font)

int16_t textWidth(const char *string)

int16_t textWidth(const String& string, uint8_t font)

int16_t textWidth(const String& string)

Drawing

Below are some commonly used drawing APIs.

// Parent functions drawing

drawCircle()

Function:

Draw a circle

**Function prototype:

void drawCircle(int32_t x0, int32_t y0, int32_t r, uint32_t color)

drawCircleHelper()

Function:

Draw circle helper

Function prototype:

void drawCircleHelper(int32_t x0, int32_t y0, int32_t r, uint8_t cornername, uint32_t color)

fillCircle()

Function:

Draw a filled circle

Function prototype:

void fillCircle(int32_t x0, int32_t y0, int32_t r, uint32_t color)

fillCircleHelper()

Function:

Draw filled circle helper

Function prototype:

void fillCircleHelper(int32_t x0, int32_t y0, int32_t r, uint8_t cornername, int32_t delta, uint32_t color)

drawLine()

Function:

Draw a line

Function prototype:

void drawLine(int32_t x0, int32_t y0, int32_t x1, int32_t y1, uint32_t color)

void drawLine(int32_t x0, int32_t y0, int32_t x1, int32_t y1, uint8_t thickness, uint8_t color)

drawFastVLine()

Function:

Draw a fast vertical line

Function prototype:

void drawFastVLine(int32_t x, int32_t y, int32_t h, uint32_t color)

void drawFastVLine(int32_t x, int32_t y, int32_t h, uint8_t thickness, uint8_t color)

drawEllipse()

Function:

Draw an ellipse

Function prototype:

void drawEllipse(int16_t x0, int16_t y0, int32_t rx, int32_t ry, uint16_t color)

fillEllipse()

Function:

Draw a filled ellipse

Function prototype:

void fillEllipse(int16_t x0, int16_t y0, int32_t rx, int32_t ry, uint16_t color)

drawRect()

Function:

Draw a rectangle

Function prototype:

void drawRect(int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color)

fillRect()

Function:

Draw a filled rectangle

Function prototype:

void fillRect(int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color)

drawRoundRect()

Function:

Draw a rounded rectangle

Function prototype:

void drawRoundRect(int32_t x0, int32_t y0, int32_t w, int32_t h, int32_t radius, uint32_t color)

fillRoundRect()

Function:

Draw a filled rounded rectangle

Function prototype:

void fillRoundRect(int32_t x0, int32_t y0, int32_t w, int32_t h, int32_t radius, uint32_t color)

drawTriangle()

Function:

Draw a triangle

Function prototype:

void drawTriangle(int32_t x0, int32_t y0, int32_t x1, int32_t y1, int32_t x2, int32_t y2, uint32_t color)

fillTriangle()

Function:

Draw a filled triangle

Function prototype:

void fillTriangle(int32_t x0, int32_t y0, int32_t x1, int32_t y1, int32_t x2, int32_t y2, uint32_t color)

print

Here are some function overloads for print formatting output.

// Parent functions Print size_t printf(const char * format, ...) __attribute__ ((format (printf, 2, 3)))

size_t print(const __FlashStringHelper *x)

size_t print(const String &x)

size_t print(const char x[])

size_t print(char x)

size_t print(unsigned char x, int y = DEC)

size_t print(int x, int y = DEC)

size_t print(unsigned int x, int y = DEC)

size_t print(long x, int y = DEC)

size_t print(unsigned long x, int y = DEC)

size_t print(double x, int y = 2)

size_t print(const Printable& x)

size_t print(struct tm * timeinfo, const char * format = NULL)

size_t println(const __FlashStringHelper *x)

size_t println(const String &x)

size_t println(const char x[])

size_t println(char x)

size_t println(unsigned char x, int y = DEC)

size_t println(int x, int y = DEC)

size_t println(unsigned int x, int y = DEC)

size_t println(long x, int y = DEC)

size_t println(unsigned long x, int y = DEC)

size_t println(double x, int y = 2)

size_t println(const Printable& x)

size_t println(struct tm * timeinfo, const char * format = NULL)

size_t println(void)

1. Arduino Setup

4. Program & Upload

2. API & Examples

M5Core

M5Core2

M5CoreS3

M5Tough

M5Atom

M5AtomS3

M5Capsule

M5Cardputer

M5Paper

M5CoreInk

M5StickC

M5StickCPlus2

M5TimerCAM

M5NanoC6

3. M5Unified & M5GFX

M5Unified

M5GFX

EPD Driver

begin()

Clear()

SetRotation()

GetRotate()

GetDirection()

UpdateFull()

UpdateArea()

UpdateCount()

ResetUpdateCount()

CheckAFSR()

SetColorReverse()

WriteFullGram4bpp()

WritePartGram4bpp()

FillPartGram4bpp()

Canvas

Refresh Modes

createCanvas()

deleteCanvas()

Pushing Canvas

frameBuffer()

pushCanvas()

pushToCanvas()

Common APIs

fillCanvas()

pushImage()

readPixel()

drawPixel()

fillCenterSquare()

qrcode()

getBufferSize()

ReverseColor()

ReversePartColor()

operator()

setDriver()

JPG/BMP/PNG

Text

setTextColor()

setTextSize()

setTextWrap()

setTextDatum()

setTextPadding()

setTextArea()

setTextFillMargin()

setTextLineSpace()

loadFont()

loadFont()

unloadFont()

createRender()

destoryRender()

preRender()

isRenderExist()

getNumOfRender()

useFreetypeFont()

drawNumber()

drawFloat()

drawString()

decodeUTF8()

drawChar()

textWidth()