EPD Driver

The M5PAPER is equipped with an e-ink screen with a resolution of 540*960 @ 4.7" and supports 16 levels of grayscale display. In the M5.begin() initialization, the instance M5EPD_Driver EPD = M5EPD_Driver() has been created and initialized. With the following screen driver, you can push the content-drawn data to the screen.

begin()

Function:

初始化I2C总线

Syntax:

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

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 screen content/true initializes screen with UPDATE_MODE_INIT mode/false Clear 8951 buffer

Parameters Description
true Initialize the screen using UPDATE_MODE_INIT mode
false Clear the 8951 buffer

Syntax:

m5epd_err_t Clear(bool init = false)

Example:

#include <M5EPD.h>

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

void loop() {}

SetRotation()

Function:

Set screen rotation angle/usually set to 90°

Syntax:

m5epd_err_t SetRotation(uint16_t rotate = IT8951_ROTATE_0)

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

Syntax:

uint8_t GetRotate(void)

GetDirection()

Function:

Read screen orientation

Syntax:

uint8_t GetDirection(void)

UpdateFull()

Function:

flushes the data in the buffer to full screen in the specified mode

Syntax:

m5epd_err_t UpdateFull(m5epd_update_mode_t mode)

UpdateArea()

Function:

flushes the data in the buffer to the specified area of the screen in the specified mode

Syntax:

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

UpdateCount()

Function:

get refresh times

Syntax:

uint16_t UpdateCount(void)

ResetUpdateCount()

Function:

reset refresh times

Syntax:

void CheckAFSR(void)

CheckAFSR()

Function:

detects if 8951 is busy

Syntax:

m5epd_err_t CheckAFSR(void)

SetColorReverse()

Function:

set color inverse color

Syntax:

void SetColorReverse(bool is_reverse)

WriteFullGram4bpp()

Function:

Write full frame data / 4 bit per pixel

Syntax:

m5epd_err_t WriteFullGram4bpp(const uint8_t *gram)

WritePartGram4bpp()

Function:

Write local data in specified area / 4 bit per pixel

Syntax:

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

FillPartGram4bpp()

Function:

Fill specified data in specified area

Syntax:

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

Canvas

The library uses the Canvas class for drawing patterns, which provides a variety of drawing APIs (including drawing strings, rectangles, triangles, circles, image data, etc.). To use it, you need to create a canvas instance and pass it to the screen driver, as shown in the following code.

#include <M5EPD.h>

M5EPD_Canvas canvas(&M5.EPD);

Update Mode

To use pushCanvas, we need to pass a refresh mode parameter. The library m5epd_update_mode_t already enumerates several different update modes.

typedef enum
{                             //   Ghosting  Update Time  Usage
    UPDATE_MODE_INIT    = 0,  // * N/A       2000ms       Display initialization,
    UPDATE_MODE_DU      = 1,  //   Low       260ms        Monochrome menu, text input, and touch screen input 1bit Gray level
    UPDATE_MODE_GC16    = 2,  // * Very Low  450ms        High quality images
    UPDATE_MODE_GL16    = 3,  // * Medium    450ms        Text with white background
    UPDATE_MODE_GLR16   = 4,  //   Low       450ms        Text with white background
    UPDATE_MODE_GLD16   = 5,  //   Low       450ms        Text and graphics with white background
    UPDATE_MODE_DU4     = 6,  // * Medium    120ms        Fast page flipping at reduced contrast 1bit Gray level Slightly faster than DU, larger afterimage relative to DU
    UPDATE_MODE_A2      = 7,  //   Medium    290ms        Anti-aliased text in menus / touch and screen input 2bit Gray level
    UPDATE_MODE_NONE    = 8                               Uploading to the 8951 cache without refreshing allows you to accumulate multiple uploads and then refresh all content at once.
} m5epd_update_mode_t;        // The ones marked with * are more commonly used

The refresh quality is relatively good for UPDATE_MODE_GC16, UPDATE_MODE_GL16 , UPDATE_MODE_GLR16 , UPDATE_MODE_GLD16.

The ink screen adopted by M5Paper supports 16-level grayscale display. The effective input range of the color parameter in the API below is 0~15

createCanvas()

Function:

Create a Canvas (before we start drawing, we need to create a drawing area using a Canvas instance)

Syntax:

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

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. 创建500*300的绘制区域
}

void loop() {}

deleteCanvas()

Function:

Delete the Canvas and free memory

Syntax:

void deleteCanvas(void)

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. 创建500*300的绘制区域
    canvas.deleteCanvas();  // Delete the drawing area. 删除绘制区域
}

void loop() {}

推送Canvas

After the content is drawn using the drawing API, we need to push the drawn area to the screen using the push API. After pushing, it takes some time for the screen driver to refresh the drawing. Please avoid shutting down your computer until you finish drawing.

frameBuffer()

Function:

Get a pointer to the Canvas buffer

Syntax:

void *frameBuffer(int8_t f = 1)

pushCanvas()

Function:

Get Canvas cache pointer to push Canvas to screen 0,0 position and specify refresh mode

Push the Canvas to the specified area of the screen, and specify the refresh mode.

Syntax:

void pushCanvas(m5epd_update_mode_t mode)

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

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. 创建500*300的绘制区域
    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. 推送画布到屏幕
}

void loop() {}

pushToCanvas()

Function:

Draw to the specified Canvas

Syntax:

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

常用API

fillCanvas()

Function:

Fill the drawing area with a certain color

Syntax:

void fillCanvas(uint32_t color)

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. 创建500*300的绘制区域
    canvas.setTextSize(3);
    canvas.fillCanvas(0xFFFF);  // Fill the drawn area with black. 以黑色填充绘制区域
    canvas.pushCanvas(100, 100, UPDATE_MODE_DU4);  // Push the canvas to display. 推送画布到屏幕
}

void loop() {}

pushImage()

Function:

Push Buffer Data

Syntax:

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

readPixel()

Function:

Read pixel color

Syntax:

uint16_t readPixel(int32_t x, int32_t y)

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. 创建500*300的绘制区域
    canvas.setTextSize(3);
    canvas.fillCanvas(0xFFFF);  // Fill the drawn area with black. 以黑色填充绘制区域
    canvas.pushCanvas(100, 100, UPDATE_MODE_DU4);  // Push the canvas to display. 推送画布到屏幕
    Serial.print(canvas.readPixel(100, 100));
}

void loop() {}

drawPixel()

Function:

Drawing pixel points

Syntax:

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

fillCenterSquare()

Function:

Draws a square with a center point

Syntax:

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

qrcode()

Function:

Draw QR code

Syntax:

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:

Retrieve the Buffer size of the current Canvas image

Syntax:

uint32_t getBufferSize(void)

ReverseColor()

Function:

Set inverse color

Syntax:

void ReverseColor(void)

ReversePartColor()

Function:

Set partial inverse color

Syntax:

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

operator()

Function:

Canvas复制

Syntax:

void operator=(const M5EPD_Canvas &src)

setDriver()

Function:

Setting up the screen driver

Syntax:

void setDriver(M5EPD_Driver *driver)

JPG/BMP/PNG

Function:Drawing images using Bmp file data

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:Drawing images using Jpg file data

bool drawJpgFile(fs::FS &fs, const 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:Drawing images with Png file data

bool drawPngFile(fs::FS &fs, const 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:Drawing images using in-memory Jpg data

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:Drawing images with Jpg Url/web resource data

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:Drawing images using Png's Url/web resource data

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);

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

Drawing images using Png's Url/web resource data Here are some common text drawing APIs.

setTextColor()

Function:

Set font color

Syntax:

void setTextColor(uint16_t color)

void setTextColor(uint16_t fgcolor, uint16_t bgcolor)

setTextSize()

Function:

Set font size

Syntax:

void setTextSize(uint8_t size)

setTextWrap()

Function:

Set text line feed

Syntax:

void setTextWrap(boolean wrapX, boolean wrapY = false)

setTextDatum()

Function:

Set the text base

Syntax:

void setTextDatum(uint8_t datum)

setTextPadding()

Function:

Set the text margin

Syntax:

void setTextPadding(uint16_t x_width)

setTextArea()

Function:

Set the font output area, you can use printf to output the text in the area, the text will be automatically line feed

Syntax:

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

setTextFillMargin()

Function:

Set the fill margin for the string background color

Syntax:

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

setTextLineSpace()

Function:

Set the line spacing for automatic line feeds when using printf to output strings

Syntax:

void setTextLineSpace(uint8_t space)

loadFont()

Function:

Load TTF font files from file system, support SPIFFS and SD

Syntax:

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

loadFont()

Function:

Load TTF files from the binary array pointed by the pointer, larger TTF files are not supported.

Syntax:

esp_err_t loadFont(const uint8_t *memory_ptr, uint32_t length)

unloadFont()

Function:

卸载字体文件

Syntax:

esp_err_t unloadFont()

createRender()

Function:

Create TTF renderers with specified font sizes and optional cache sizes. A larger cache can cache more rendered fonts, significantly improving performance when rendering large amounts of text. cache will automatically prioritize glyph storage by the frequency of glyph use.

Syntax:

esp_err_t createRender(uint16_t size, uint16_t cache_size = 1)

destoryRender()

Function:

Destroy TTF renderer for specified font size

Syntax:

esp_err_t destoryRender(uint16_t size)

preRender()

Function:

Render the specified characters in advance and store them in the cache

Syntax:

esp_err_t preRender(uint16_t code)

isRenderExist()

Function:

Determine if a renderer of the specified size exists

Syntax:

bool isRenderExist(uint16_t size)

getNumOfRender()

Function:

Get the number of existing renderers

Syntax:

uint32_t getNumOfRender(void)

useFreetypeFont()

Function:

Set whether to use TTF renderers

Syntax:

void useFreetypeFont(bool isuse = true)

drawNumber()

Function:

Draw integers

Syntax:

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 floating point numbers

Syntax:

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 strings

Syntax:

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 strings/return Unicode values

Syntax:

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 characters

Syntax:

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

Syntax:

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

Here are some common drawing APIs

// Parent functions drawing

drawCircle()

Function:

Draw circle

Syntax:

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

drawCircleHelper()

Function:

Draw circle helper

Syntax:

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

fillCircle()

Function:

Draw filled circles

Syntax:

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

fillCircleHelper()

Function:

Draw filled circle helper

Syntax:

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

drawLine()

Function:

Drawing straight lines

Syntax:

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:

Quickly draw vertical lines

Syntax:

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:

Drawing ellipses

Syntax:

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

fillEllipse()

Function:

Drawing filled ellipses

Syntax:

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

drawRect()

Function:

Draw Rectangle

Syntax:

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

fillRect()

Function:

Drawing a filled rectangle

Syntax:

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

drawRoundRect()

Function:

Drawing rounded rectangles

Syntax:

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

fillRoundRect()

Function:

Draws a filled rounded rectangle

Syntax:

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

drawTriangle()

Function:

Draw triangle

Syntax:

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:

Draws filled triangles

Syntax:

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 formatted 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)

On This Page