pdf-icon

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)

On This Page