M5GFX Setup

M5GFX is a library for operating display devices on M5Stack products. Users can call APIs in this library to achieve various display effects and touch effects.

• Include header files and display definitions
• M5GFX.h
  • Constructor
• M5UnitLCD.h
  • Constructor
  • Functions
    • init
    • setup
• M5UnitOLED.h
  • Constructor
  • Functions
    • init
    • setup
• M5AtomDisplay.h
  • Constructor
  • Functions
    • setResolution
• List of APIs requiring additional header files

Include header files and display definitions

Each device requires different header files. M5Stack devices mainly use the header file M5GFX.h; other devices such as Unit LCD require the header file M5UnitLCD.h, and similarly for Unit OLED and Atom Display.

M5GFX.h

Supported devices:

M5Stack Core Controllers, such as M5Fire, M5Core2, M5Tough, M5StickC, M5Paper, M5Tab, etc.

Constructor

Constructor prototype:

M5GFX(void)

Description:

• Creates an M5GFX object, which by default points to the current device

Sample program:

#include <M5GFX.h>

M5GFX display;

void setup() {
    display.begin();
    uint16_t x = display.width() / 2;
    uint16_t y = display.height() / 2;

    display.drawCenterString("M5Stack", x, y);
}

void loop() {
}

M5UnitLCD.h

Supported devices:

M5Stack Unit LCD

Constructor

Constructor prototype:

M5UnitLCD( uint8_t pin_sda = M5UNITLCD_SDA, uint8_t pin_scl = M5UNITLCD_SCL, uint32_t i2c_freq = M5UNITLCD_FREQ, 
           int8_t i2c_port = -1, uint8_t i2c_addr = 0x3E )

Description:

• Creates an M5UnitLCD object and sets I2C parameters

Parameters:

• pin_sda: SDA pin number of the device LCD
• pin_scl: SCL pin number of the device LCD
• i2c_freq: I2C communication frequency
• i2c_port: I2C port (usually not used)
• i2c_addr: I2C address (usually not used)

Functions

init

Function prototype:

void init( uint8_t pin_sda, uint8_t pin_scl, uint32_t i2c_freq = M5UNITLCD_FREQ, int8_t i2c_port = -1, uint8_t i2c_addr = 0x3E )

Description:

• Initialization settings

Parameters:

• pin_sda: SDA pin number of the device LCD
• pin_scl: SCL pin number of the device LCD
• i2c_freq: I2C communication frequency
• i2c_port: I2C port (usually not used)
• i2c_addr: I2C address (usually not used)

setup

Function prototype:

setup(uint8_t pin_sda = M5UNITLCD_SDA, uint8_t pin_scl = M5UNITLCD_SCL, uint32_t i2c_freq = M5UNITLCD_FREQ, 
      int8_t i2c_port = -1, uint8_t i2c_addr = 0x3E)

Description:

• Change initial settings

Parameters:

• pin_sda: SDA pin number of the device LCD
• pin_scl: SCL pin number of the device LCD
• i2c_freq: I2C communication frequency
• i2c_port: I2C port (usually not used)
• i2c_addr: I2C address (usually not used)

Sample program:

#include <M5UnitLCD.h>
M5UnitLCD display;

void setup() {
    display.init( 21, 22, 400000 );
    display.setup( 21, 22, 400000 );
    uint16_t x = display.width() / 2;
    uint16_t y = display.height() / 2;

    display.drawCenterString("M5Stack", x, y);
}

void loop() {
}

M5UnitOLED.h

Supported devices:

M5Stack Unit OLED

Constructor

Constructor prototype:

M5UnitOLED( uint8_t pin_sda = M5UNITOLED_SDA, uint8_t pin_scl = M5UNITOLED_SCL, uint32_t i2c_freq = M5UNITOLED_FREQ, 
            int8_t i2c_port = -1, uint8_t i2c_addr = 0x3C)

Description:

• Creates an M5UnitOLED object and sets I2C parameters

Parameters:

• pin_sda: SDA pin number of the device LCD
• pin_scl: SCL pin number of the device LCD
• i2c_freq: I2C communication frequency
• i2c_port: I2C port (usually not used)
• i2c_addr: I2C address (usually not used)

Functions

init

Function prototype:

void init( uint8_t pin_sda, uint8_t pin_scl, uint32_t i2c_freq = M5UNITOLED_FREQ, int8_t i2c_port = -1, uint8_t i2c_addr = 0x3C )

Description:

• Initialization settings

Parameters:

• pin_sda: SDA pin number of the device LCD
• pin_scl: SCL pin number of the device LCD
• i2c_freq: I2C communication frequency
• i2c_port: I2C port (usually not used)
• i2c_addr: I2C address (usually not used)

setup

Function prototype:

setup(uint8_t pin_sda = M5UNITLCD_SDA, uint8_t pin_scl = M5UNITLCD_SCL, uint32_t i2c_freq = M5UNITLCD_FREQ, 
      int8_t i2c_port = -1, uint8_t i2c_addr = 0x3C)

Description:

• Change initial settings

Parameters:

• pin_sda: SDA pin number of the device LCD
• pin_scl: SCL pin number of the device LCD
• i2c_freq: I2C communication frequency
• i2c_port: I2C port (usually not used)
• i2c_addr: I2C address (usually not used)

Sample program:

#include <M5UnitOLED.h>
M5UnitOLED display;

void setup() {
    display.init( 21, 22, 400000 );
    display.setup( 21, 22, 400000 );
    uint16_t x = display.width() / 2;
    uint16_t y = display.height() / 2;

    display.drawCenterString("M5Stack", x, y);
}

void loop() {
}

M5AtomDisplay.h

Supported devices:

M5Stack Atom Display, AtomDisplayLite

Constructor

Constructor prototype:

M5AtomDisplay( unit16_t logical_width = 1280, uint16_t logical_height = 720, float refresh_rate = 0.0f, uint16_t output_width = 0, uint16_t output_height = 0, 
               uint_fast8_t scale_w = 0, uint_fast8_t scale_h = 0, uint32_t pixel_clock = 74250000)

Description:

• Creates an M5AtomDisplay object and sets I2C parameters

Parameters:

• logical_width: Logical screen width handled by the program
• logical_height: Logical screen height handled by the program
• refresh_rate: Screen refresh rate
• output_width: Actual output screen width
• output_height: Actual output screen height
• scale_w: Magnification of logical width
• scale_h: Magnification of logical height

Functions

setResolution

Function prototype:

bool setResolution(uint16_t logical_width = 0, uint16_t logical_height = 0, float refresh_rate = 0.0f, uint16_t output_width = 0, uint16_t output_height = 0, 
                   uint_fast8_t scale_w = 0, uint_fast8_t scale_h = 0, uint32_t pixel_clock = 74250000)

Description:

• Change initial resolution settings

Parameters:

• logical_width: Logical screen width handled by the program
• logical_height: Logical screen height handled by the program
• refresh_rate: Screen refresh rate
• output_width: Actual output screen width
• output_height: Actual output screen height
• scale_w: Magnification of logical width
• scale_h: Magnification of logical height
• pixel_clock: Pixel clock frequency

Sample program:

#include <M5AtomDisplay.h>
M5AtomDisplay display( 640, 480, 60 );

void setup() {
    display.setResolution( 320, 240, 60 );
    uint16_t x = display.width() / 2;
    uint16_t y = display.height() / 2;

    display.drawCenterString("M5Stack", x, y);
}

void loop() {
}

List of APIs requiring additional header files

Some APIs in M5GFX must include other corresponding header files in addition to M5GFX.h (or M5UnitLCD.h, M5UnitOLED.h, M5AtomDisplay.h), otherwise they cannot be called successfully.
The relevant APIs and header files are as follows: