M5GFX Graphics Library

M5GFX supports a wide range of M5Stack hardware, including:

• M5Stack (Basic / Gray / GO / Fire)
• M5Stack Core2
• M5Stack CoreS3 / CoreS3SE
• M5Stack CoreInk
• M5Stick C / C Plus / C Plus2
• M5Paper / M5PaperS3
• M5Tough
• M5Station
• M5ATOMS3 / ATOMS3R
• M5Dial
• M5DinMeter
• M5Cardputer / M5CardputerADV
• M5VAMeter
• M5Tab5
• ArduinoNessoN1
• UnitOLED / UnitMiniOLED / UnitLCD
• UnitRCA / ModuleRCA
• UnitGLASS / UnitGLASS2
• AtomDisplay / ModuleDisplay

M5GFX is compatible with the following development frameworks:

• ESP-IDF
• Arduino for ESP32

PSRAM Requirements

Contrary to the product label "FOR ATOM PSRAM ONLY", PSRAM is NOT required. The library works with:

• ATOM Lite
• ATOM Matrix

This is because the frame buffer is managed on the FPGA side rather than the ESP32 side.

Hardware Differences (Lite vs PSRAM)

• ATOM Lite: Uses ESP32 PICO-D4.
• ATOM PSRAM: Uses ESP32 PICO-V3-02.
• Pinout Warning: The pinout on the back differs. The ATOM PSRAM has a G5 pin where the ATOM Lite had a G23 pin. The G23 pin is not available on the ATOM PSRAM model.

Once the environment is set up:

1. Open the PlatformIO_SDL folder in PlatformIO.
2. In the PlatformIO sidebar, navigate to PROJECT TASKS.
3. Select native -> General -> Upload.
   • Note for ARM processors (e.g., M1/M2 Mac): Use native_arm instead of native.
4. The window may appear behind other windows; check your task tray.

Controls:

• Use the keyboard keys 'L' or 'R' to spin the image.

To use the Unit GLASS, include the M5UnitGLASS.h library and call the init method on your M5UnitGLASS instance. You must specify the SDA pin, SCL pin, and the I2C frequency.

Method Signature: display.init(SDA, SCL, Freq)

• SDA: The GPIO number for the SDA pin.
• SCL: The GPIO number for the SCL pin.
• Freq: The I2C communication frequency (e.g., 400000u for 400kHz).

#include <M5UnitGLASS.h>

M5UnitGLASS display;

void setup(void)
{
  // Initialize with SDA, SCL, and Frequency
  display.init(GPIO_NUM_21, GPIO_NUM_22, 400000u);
}

To use platform = native in PlatformIO, you must install the necessary build tools for your operating system.

Windows

1. Install MSYS2.
2. Run the following command in the MSYS2 terminal to install gcc and gdb:

   pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-gdb

3. Add these paths to your system PATH environment variable:
   • C:\msys64\mingw64\bin
   • C:\msys64\ucrt64\bin
   • C:\msys64\usr\bin

Linux

Run the following in your terminal:

sudo apt update
sudo apt install build-essential

macOS

Install Xcode Command Line Tools:

xcode-select --install

To use M5GFX on M5 PaperS3 with versions prior to v0.2.7, use the following platformio.ini configuration. This ensures PSRAM is enabled with the correct qio_opi memory type and includes the required epdiy dependency from GitHub.

[env:PaperS3]
platform = espressif32
board = esp32-s3-devkitm-1
framework = arduino
board_upload.flash_size = 16MB
board_upload.maximum_size = 16777216
board_build.arduino.memory_type = qio_opi
build_flags = -DBOARD_HAS_PSRAM
lib_deps = epdiy=https://github.com/vroland/epdiy.git

You can run M5GFX on a PC for development and testing using Visual Studio Code, PlatformIO, and the SDL2 library. This environment simulates the graphics output on your computer.

Prerequisites

1. Install Visual Studio Code and the PlatformIO extension.
2. Ensure your system has a C++ compiler and debugger installed (see Platform Native Setup).

To use the ATOM Display, include <M5AtomDisplay.h> and create an instance of M5AtomDisplay. You must call display.init() during setup to initialize the hardware.

Key lifecycle methods:

• display.init(): Initializes the display.
• display.startWrite(): Begins a write sequence (useful for batching pixel operations).
• display.endWrite(): Ends a write sequence.

Note: The audio output function is not included in this library.

#include <M5AtomDisplay.h>

M5AtomDisplay display;

void setup() {
  display.init();
  display.setRotation(1);
  display.setColorDepth(24);
  
  display.startWrite();
  // ... drawing operations ...
  display.endWrite();
}

void loop() {
  // ... loop operations ...
}

To convert BDF files into C source files compatible with the u8g2 format, use bdfconv.exe. This process utilizes a map file (specifically a modified ja.map based on japanese3.map) to handle Japanese character sets.

Command Flags:

• -v: Verbose mode
• -b 0: Bit depth/offset setting
• -f 1: Format setting
• -M "japanese3.map": Specifies the map file for character encoding
• -o <path>: Specifies the output .c file path
• -n <name>: Specifies the internal font name

Example conversion:

bdfconv.exe -v -b 0 -f 1 -M "japanese3.map" ..\bdf\lgfx_font_japan_mincho_8.bdf -o ..\output\lgfx_font_japan_mincho_8.c -n lgfx_font_japan_mincho_8

When using arduino-esp32 as an ESP-IDF component alongside M5GFX, the library attempts to automatically link the Arduino component by searching for names like arduino, arduino-esp32, or espressif__arduino-esp32. This ensures the library and application share the same ARDUINO definitions.

If your Arduino component uses a different name, you must set the M5GFX_ARDUINO_COMPONENT CMake cache variable to that name. To disable this automatic linking, set M5GFX_ARDUINO_COMPONENT=OFF.

# Example: Setting a custom name for the Arduino component
set(M5GFX_ARDUINO_COMPONENT "your_custom_arduino_name" CACHE STRING "")

# Example: Disabling automatic linking
set(M5GFX_ARDUINO_COMPONENT OFF CACHE STRING "")