EPD Driver

M5PAPER搭载了一块分辨率为540*960 @4.7"的电子墨水屏,支持16级灰度显示. 在M5.begin()初始化中,已经创建了实例M5EPD_Driver EPD = M5EPD_Driver()并进行了初始化.通过下面的屏幕驱动,你能够将内容绘制的数据推送至屏幕.

begin()

功能:

初始化I2C总线

函数原型:

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

使用示例:

#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()

功能:

清除屏幕内容

参数	描述
true	使用UPDATE_MODE_INIT模式初始化屏幕
false	清除8951缓存区

函数原型:

m5epd_err_t Clear(bool init = false)

使用示例:

#include <M5EPD.h>

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

void loop() {}

SetRotation()

功能:

设置屏幕旋转角度/通常设置为90°

函数原型:

m5epd_err_t SetRotation(uint16_t rotate = IT8951_ROTATE_0)

使用示例:

#include <M5EPD.h>

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

void loop() {}

GetRotate()

功能:

读取屏幕旋转角度

函数原型:

uint8_t GetRotate(void)

GetDirection()

功能:

读取屏幕方向

函数原型:

uint8_t GetDirection(void)

UpdateFull()

功能:

以指定模式将缓存区中的数据刷新至全屏幕

函数原型:

m5epd_err_t UpdateFull(m5epd_update_mode_t mode)

UpdateArea()

功能:

以指定模式将缓存区中的数据刷新至屏幕指定区域

函数原型:

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

UpdateCount()

功能:

获取刷新次数

函数原型:

uint16_t UpdateCount(void)

ResetUpdateCount()

功能:

重置刷新次数

函数原型:

void CheckAFSR(void)

CheckAFSR()

功能:

检测8951是否忙碌

函数原型:

m5epd_err_t CheckAFSR(void)

SetColorReverse()

功能:

设置颜色反色

函数原型:

void SetColorReverse(bool is_reverse)

WriteFullGram4bpp()

功能:

写入完整一帧数据/ 每像素4bit

函数原型:

m5epd_err_t WriteFullGram4bpp(const uint8_t *gram)

WritePartGram4bpp()

功能:

在指定区域写入局部数据/ 每像素4bit

函数原型:

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

FillPartGram4bpp()

功能:

在指定区域填充指定数据

函数原型:

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

Canvas

该库使用Canvas类进行图案绘制,该类中提供了多种绘图API(其中包含绘制字符串,矩形,三角形,圆形,图片数据等). 使用前需要创建canvas实例并传入屏幕驱动,如下方代码所示。

#include <M5EPD.h>

M5EPD_Canvas canvas(&M5.EPD);

刷新模式

在使用pushCanvas时,我们需要传入一个刷新模式参数,在该库中的m5epd_update_mode_t已经枚举了几种不同的刷新模式,下面为你说明它们分别有什么样的特点。


typedef enum
{                             //   Ghosting  Update Time  Usage
    UPDATE_MODE_INIT    = 0,  // * N/A       2000ms       显示屏初始化,
    UPDATE_MODE_DU      = 1,  //   Low       260ms        适合单色菜单,文本输入, 触摸反馈 1bit黑白,存在残影。
    UPDATE_MODE_GC16    = 2,  // * Very Low  450ms        适合高质量图像显示 先黑闪后刷新
    UPDATE_MODE_GL16    = 3,  // * Medium    450ms        适合白色背景的文本显示 不黑闪
    UPDATE_MODE_GLR16   = 4,  //   Low       450ms        适合白色背景的文本显示 不黑闪
    UPDATE_MODE_GLD16   = 5,  //   Low       450ms        适合白色背景的文本和图形显示 不黑闪
    UPDATE_MODE_DU4     = 6,  // * Medium    120ms        降低对比度,适合需要快速翻页切换的情况 1bit黑白 稍微比DU快一点,残影相对DU较大
    UPDATE_MODE_A2      = 7,  //   Medium    290ms        适合菜单,触摸反馈,抗锯齿文字 2bit灰度,存在残影
    UPDATE_MODE_NONE    = 8   //                          上传至8951缓存区 不刷新,可以积累上传多次,然后一次刷新所有内容。
} m5epd_update_mode_t;        // 以上标注了`*`符号的为较为常用的刷新模式

刷新质量较为好的几种分别为UPDATE_MODE_GC16,UPDATE_MODE_GL16 , UPDATE_MODE_GLR16 , UPDATE_MODE_GLD16
M5Paper采用的墨水屏,支持16级灰度显示,在下方API中color参数的有效传入范围为0~15

image2gray tool

createCanvas()

功能:

创建Canvas(在开始绘图前,我们需要使用Canvas实例创建一个绘制区域)

函数原型:

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

使用示例:

#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()

功能:

删除Canvas并释放内存

函数原型:

void deleteCanvas(void)

使用示例:

#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

在使用绘图API完成内容绘制后,我们需要使用pushAPI将绘制区域推送到屏幕。推送后屏幕驱动需要一定的时间进行刷新绘制。在完成绘制前,请避免关机操作。

// Re-implement functions

frameBuffer()

功能:

获取Canvas缓存区指针

函数原型:

void *frameBuffer(int8_t f = 1)

pushCanvas()

功能:

推送Canvas到屏幕0,0位置,指定刷新模式

推送Canvas到屏幕指定区域,并指定刷新模式

函数原型:

void pushCanvas(m5epd_update_mode_t mode)

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

使用示例:

#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()

功能:

绘制到指定的Canvas

函数原型:

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

常用API

fillCanvas()

功能:

以某颜色填充绘制区域

函数原型:

void fillCanvas(uint32_t color)

使用示例:

#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()

功能:

推送Buffer数据

函数原型:

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

功能:

读取像素点颜色

函数原型:

uint16_t readPixel(int32_t x, int32_t y)

使用示例:

#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()

功能:

绘制像素点

函数原型:

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

fillCenterSquare()

功能:

以中心点绘制方块

函数原型:

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

qrcode()

功能:

绘制二维码

函数原型:

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

功能:

读取当前Canvas图像的Buffer大小

函数原型:

uint32_t getBufferSize(void)

ReverseColor()

功能:

设置反色

函数原型:

void ReverseColor(void)

ReversePartColor()

功能:

设置局部反色

函数原型:

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

operator()

功能:

Canvas复制

函数原型:

void operator=(const M5EPD_Canvas &src)

setDriver()

功能:

设置屏幕驱动

函数原型:

void setDriver(M5EPD_Driver *driver)

JPG/BMP/PNG

功能:使用Bmp文件数据绘制图像

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

功能:使用Jpg文件数据绘制图像

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

功能:使用Png文件数据绘制图像

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

功能:使用内存Jpg数据绘制图像

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

功能:使用Jpg的Url/网络资源数据绘制图像

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

功能:使用Png的Url/网络资源数据绘制图像

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

使用示例:

#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

下面是一些常用的文本绘制API。

setTextColor()

功能:

设置字体颜色

函数原型:

void setTextColor(uint16_t color)

void setTextColor(uint16_t fgcolor, uint16_t bgcolor)

setTextSize()

功能:

设置字体大小

函数原型:

void setTextSize(uint8_t size)

setTextWrap()

功能:

设置文本换行

函数原型:

void setTextWrap(boolean wrapX, boolean wrapY = false)

setTextDatum()

功能:

设置文本基准

函数原型:

void setTextDatum(uint8_t datum)

setTextPadding()

功能:

设置文本边距

函数原型:

void setTextPadding(uint16_t x_width)

setTextArea()

功能:

设定字体输出区域,可使用printf在该区域内输出文字,文字将自动换行

函数原型:

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

setTextFillMargin()

功能:

设置字符串背景色的填充边距

函数原型:

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

setTextLineSpace()

功能:

设置使用printf输出字符串时自动换行的行间距

函数原型:

void setTextLineSpace(uint8_t space)

loadFont()

功能:

从文件系统加载TTF字体文件,支持SPIFFS与SD

函数原型:

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

loadFont()

功能:

从指针指向的二进制数组加载TTF文件,不支持较大的TTF文件

函数原型:

esp_err_t loadFont(const uint8_t *memory_ptr, uint32_t length)

unloadFont()

功能:

卸载字体文件

函数原型:

esp_err_t unloadFont()

createRender()

功能:

创建指定字号的TTF渲染器,可选cache大小。较大的cache可以缓存更多渲染好的字体,显著提升渲染大量文字时的性能。cache将以字形使用的频率为优先级自动安排字形存储。

函数原型:

esp_err_t createRender(uint16_t size, uint16_t cache_size = 1)

destoryRender()

功能:

销毁指定字号的TTF渲染器

函数原型:

esp_err_t destoryRender(uint16_t size)

preRender()

功能:

提前渲染指定的字符并存入缓存区

函数原型:

esp_err_t preRender(uint16_t code)

isRenderExist()

功能:

判断指定大小的渲染器是否存在

函数原型:

bool isRenderExist(uint16_t size)

getNumOfRender()

功能:

获取已有的渲染器数量

函数原型:

uint32_t getNumOfRender(void)

useFreetypeFont()

功能:

设定是否使用TTF渲染器

函数原型:

void useFreetypeFont(bool isuse = true)

drawNumber()

功能:

绘制整数

函数原型:

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

功能:

绘制浮点数

函数原型:

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

功能:

绘制字符串

函数原型:

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

功能:

解码UTF8字符串/返回Unicode值

函数原型:

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

功能:

绘制字符

函数原型:

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

功能:

获取文本宽度

函数原型:

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

下面是一些常用的绘图API。

// Parent functions drawing

drawCircle()

功能:

绘制圆形

函数原型:

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

drawCircleHelper()

功能:

绘制圆形助手

函数原型:

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

fillCircle()

功能:

绘制填充圆形

函数原型:

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

fillCircleHelper()

功能:

绘制填充圆形助手

函数原型:

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

drawLine()

功能:

绘制直线

函数原型:

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

功能:

快速绘制垂直直线

函数原型:

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

功能:

绘制椭圆

函数原型:

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

fillEllipse()

功能:

绘制填充椭圆

函数原型:

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

drawRect()

功能:

绘制矩形

函数原型:

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

fillRect()

功能:

绘制填充矩形

函数原型:

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

drawRoundRect()

功能:

绘制圆角矩形

函数原型:

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

fillRoundRect()

功能:

绘制填充圆角矩形

函数原型:

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

drawTriangle()

功能:

绘制三角形

函数原型:

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

fillTriangle()

功能:

绘制填充三角形

函数原型:

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

print

下面是一些关于print格式化输出的一些函数重载。

// 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

刷新模式

createCanvas()

deleteCanvas()

推送Canvas

frameBuffer()

pushCanvas()

pushToCanvas()

常用API

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