Quick Start M5GFX Library

This document is a brief introduction to getting started with M5GFX, a library for the Arduino IDE.

about M5GFX

M5GFX is a library for M5Stack products to handle display devices with different specifications, such as LCD, OLED, and e-Ink Display, using a common API. (There are some different APIs for initialization, etc.)

Supported Models and Peripherals

Depending on the available memory, a combination of main device + UnitLCD or main device + UnitOLED is also possible.

Main Devices

  • M5Stack Core Basic/Gray/Fire/M5Go

  • M5Stack Core2/Core2 for AWSIoT Edukit

  • M5StickC/M5StickCPlus

  • M5Tough

  • M5Paper

  • M5CoreInk

  • M5Station

Units

  • UnitLCD

  • UnitOLED

AtomDisplay

  • AtomDisplay/AtomDisplayLite

How To Install Library

Arduino IDE

Click to menu→「sketch」→「Include Library」→「Manage Library...」. Open Library Manager and search M5GFX

Include Library

notice: Include header files vary depending on the device used.

Main Devices

UnitLCD

UnitOLED

M5AtomDisplay

When combining MultipleInclude when combining the main device with UnitLCD or UnitOLED.

Example:

#include <M5GFX.h>
#include <M5UnitOLED.h>

M5GFX gfx;
M5UnitOLED oled;

Combine with M5Stack libraries

M5GFX is available on its own, but can be combined with M5Unified and other M5Stack product libraries.

M5Unified

  • M5GFX is available with M5.Lcd (or M5.Display). (Include of M5GFX is not necessary)

    #include <M5Unified.h>
    
    void setup() {
        auto cfg = M5.config();
        M5.begin(cfg);
    
        M5.Display.init();
        M5.Display.startWrite();
        M5.Display.println("Hello World!");
        M5.Display.endWrite();
    }
    void loop() {
    }
    

M5Stack Product Libraries

  • Include M5GFX.h, and you need to define it. Note that if you use M5.Lcd (or M5.Display), it will use the display driver included in the respective library.

    #include <M5Stack.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.begin();
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    void loop() {
    }
    

When executing a drawing function, enclose them in startWrite(),endWrite().

When drawing a single line (drawLine) or a single line of text (drawString), the speed does not change because the drawing is executed internally, but when multiple drawing operations are performed, startWrite() first and endWrite() after the drawing is executed will speed up the drawing.

For a detailed description of startWrite(),endWrite(), see the [appendix].

**notice:**After startWrite() is executed, the SPI bus is allocated for panel access until endWrite() is executed. Therefore, if SD card access is not performed after endWrite() is executed, the device may crash or freeze, resulting in unexpected behavior. Please implement exclusive processing, especially when performing parallel processing.

(Only M5Paper)e-Ink display

M5Paper's e-Ink display allows the user to specify the drawing mode.

  • epd_mode_t::epd_fastest
    Fastest mode, no black-and-white inversion occurs when drawing. Afterimages are most likely to remain.

  • epd_mode_t::epd_fast
    In high-speed mode, black-and-white inversion does not occur when drawing. Afterimages tend to remain.

  • epd_mode_t::epd_text
    High quality mode, black and white inversion occurs momentarily. Suitable for displaying text on a white background.

  • epd_mode_t::epd_quality
    High quality mode, black and white inversion occurs momentarily. For image.

About M5GFX's Color Code

ColorCode

M5GFX can handle RGB888 format (24bit). 5GFX uses variable types to distinguish color formats from RGB565 format (16bit) and RGB332 format (8bit). The color code correspondence is as follows.

  • uint32_t
    RGB888 format(24bit)
  • uint16_t(int)
    RGB565 format(16bit)
  • uint8_t
    RGB332 format(8bit)

**notice:**Please note that when porting an existing source to M5GFX, if you make a mistake in specifying the type of the variable for the color code, different colors will be displayed. For example, if 0xFFFF (black) in RGB565 format is assigned to the unit32_t variable as shown below, it will be light blue in RGB888 format.

#include <Arduino.h>
#include <M5GFX.h>

M5GFX gfx;

void setup()
{
  gfx.begin();
  uint32_t color888 = 0xFFFF;
  uint16_t color565 = 0xFFFF;
  gfx.setTextSize(3);

  gfx.startWrite();
  gfx.setTextColor(color888);
  gfx.println("Color888");
  gfx.setTextColor(color565);
  gfx.println("Color565");
  gfx.endWrite();

}

void loop() {
}

Color representation of OLED and e-Ink display

OLED and e-Ink displays are monochromatic. If a color is specified, the shading and fill pattern will change.

HelloWorld

Combine M5Unified and M5GFX

M5GFX is available in M5.Display (or M5.Lcd). (Include is not required)

#include <M5Unified.h>

void setup() {
    auto cfg = M5.config();
    M5.begin(cfg);

    M5.Display.init();

    M5.Display.startWrite();
    M5.Display.println("Hello World!");
    M5.Display.endWrite();
}

void loop() {
}

Combine M5Stack MainDevice's Librariy and M5GFX

Note that if you use M5.Display (or M5.Lcd), you will use the display driver included in the respective library.

  • M5Stack

    #include <M5Stack.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.begin();
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    
    void loop() {
    }
    
  • M5Core2

    #include <M5Core2.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.begin();
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    
    void loop() {
    }
    
  • M5StickC

    #include <M5StickC.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.begin();
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    
    void loop() {
    }
    
  • M5StickC-Plus

    #include <M5StickCPlus.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.begin();
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    
    void loop() {
    }
    
  • M5Tough

    #include <M5Tough.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.begin();
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    
    void loop() {
    }
    
  • M5EPD

    #include <M5EPD.h>
    #include <M5GFX.h>
    
    M5GFX gfx;
    
    void setup(void)
    {
        gfx.init();
        gfx.setEpdMode(epd_fast);
        gfx.setTextSize(5);
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    
    void loop() {
    }
    
  • M5Core-Ink

    #include <M5CoreInk.h>
    #include <M5GFX.h>
    
    static M5GFX gfx;
    
    void setup() {
        M5.begin();
        gfx.begin();
    
        gfx.startWrite();
        gfx.println("Hello World!");
        gfx.endWrite();
    }
    
    void loop() {
    }
    

M5UnitLCD

#include <M5UnitLCD.h>

M5UnitLCD gfx;

void setup(void)
{
  gfx.init();
  gfx.setRotation(1);

  gfx.startWrite();
  gfx.println("Hello World!");
  gfx.endWrite();
}

void loop() {
}

M5UnitOLED

#include <M5UnitOLED.h>

M5UnitOLED gfx;

void setup()
{
  gfx.init();
  gfx.setRotation(1);

  gfx.startWrite();
  gfx.println("Hello World!");
  gfx.endWrite();
}

void loop() {
}

M5AtomDisplay

#include <M5AtomDisplay.h>

M5AtomDisplay gfx(1280, 720);

void setup()
{
  gfx.init();
  gfx.setRotation(1);

  gfx.startWrite();
  gfx.println("Hello World!");
  gfx.endWrite();
}

void loop() {
}

Combine M5GFX and UnitLCD

#include <M5GFX.h>
#include <M5UnitLCD.h>

M5GFX gfx1;
M5UnitLCD gfx2;

void setup() {
    gfx1.init();
    gfx2.init();
    gfx1.println("Hello World! MainDisplay");
    gfx2.println("Hello World! UnitLCD");
}

void loop() {
}

Combine M5GFX and UnitOLED

#include <M5GFX.h>
#include <M5UnitOLED.h>

M5GFX gfx1;
M5UnitOLED gfx2;

void setup(void) {
    gfx1.init();
    gfx2.init();

    gfx1.startWrite();
    gfx1.println("Hello World! MainDisplay");
    gfx1.endWrite();

    gfx2.startWrite();
    gfx2.println("Hello World! UnitLCD");
    gfx2.endWrite();
}

void loop() {
}
On This Page