M5Unified

Arduino / ESP-IDF Library for M5Stack Series

Usage

This library provides access to the built-in hardware of M5Stack controllers. Library functionality is available through the m5 namespace, and includes the following:

• LCD display access, fonts, and graphical primitives (in conjunction with M5GFX)
• Touchscreen and hardware button access
• Speaker and microphone access
• Power and battery charging control
• Accelerometer, gyroscope, magnetometer access
• Real-time clock and wakeup timer access

M5Unified requires M5GFX to be installed.

How To Use

#include "M5Unified.h"

Examples and Demonstrations

In the Arduino IDE, once the M5Unified library is installed through Library Manager, the following example programs are available under File > Examples > M5Unified > Basic.

• Combined demonstration: A demonstration exhibiting several functions in a single example is in HowToUse

Separate examples

• Displays: A basic demonstration of printing text on each of the supported M5Stack displays is in Displays.
• Buttons: A demo of detecting and responding to button presses is in Button.
• Touch: A demo of detecting and reacting to touch events is in Touch.
• Speaker: An example of playing wave audio through built-in speakers and accessories that support audio is in Speaker
• Clock: An example of connecting to an Internet time server over WiFi and setting the built-in clock is in RTC.
• Microphone: An example that records a short clip and plays it back through the speaker is in Microphone.
• IMU: An example demonstrating the accelerometer / gyro / magnetometer is in IMU
• Advanced examples include playing audio over Bluetooth and streaming and decoding MP3 audio, and are in the Advanced folder.

M5Stack hardware functionality supported by the ESP32 ecosystem

The following functionality is built in to the ESP32 framework or available elsewhere, independent of any hardware included in the M5Stack products, and do not require or have explicit support in the M5Unified library. To use these functions, simply use existing ESP32 or Arduino supporting libraries. This list is provided for the benefit of newcomers who may be asking where the "M5Unified" support for a particular feature is found, before discovering that it's either already part of the basic ESP32 platform, or a device that is generic enough (e.g. I2C or SPI) to be fully supported with generic libraries found online, including in the Arduino library manager, that work with any platform.

• Network access using WiFi (built into ESP32)
• Micro SD card access (SD cards are generic SPI devices)
• Infrared remote control transmitter
• Color-changing LED (e.g. on Atom)

Desirable examples worthy of future contribution

• Power: A demonstration of detecting the battery level and charging state, powering off, and entering deep sleep mode when power off is unavailable.
• Battery lifespan management: An example/utility sketch that runs the battery down to an optimum storage percentage (~40%) before powering off as fully as possible, and as a separate function, charges it to a lifespan-preserving 75% maximum, on each M5Stack device where the power management hardware supports this.
• RTC wakeup: A demonstration of using the realtime clock to set a wakeup timer to power-on, or bring the device out of sleep mode after a pre-determined number of seconds, on devices that support this.

Supported frameworks

• ESP-IDF
• Arduino IDE

Supported devices (ESP32)

• M5Stack Core (BASIC / GRAY / GO / FIRE)
• M5Stack Core2 / Core2 v1.1 / Tough
• M5Stick C / CPlus / CPlus2
• M5Stack CoreInk
• M5Station
• M5Paper
• M5ATOM Lite / Matrix / ECHO / PSRAM / U
• M5STAMP PICO

Supported devices (ESP32-S3)

• M5Stack CoreS3 / CoreS3SE
• M5StickS3
• M5ATOMS3 / S3Lite / S3U
• M5ATOMS3R / S3RExt / S3RCam / ECHO S3R
• M5STAMPS3 (S3 / S3A)
• M5Dial
• M5DinMeter
• M5Capsule
• M5Cardputer / M5CardputerADV
• M5VAMeter
• M5PaperS3
• M5PowerHub

Supported devices (ESP32-C3)

• M5STAMPC3 / C3U

Supported devices (ESP32-C6)

• M5NanoC6
• M5UnitC6L
• ArduinoNessoN1

Supported devices (ESP32-P4)

• M5Tab5

Supported external displays and video adapters

• Unit LCD
• Unit OLED
• Unit Mini OLED
• Unit RCA (without ESP32S3 series)
• Unit GLASS
• Unit GLASS2
• ATOM Display adapter (HDMI output for M5ATOM Lite / Matrix / PSRAM / S3 / S3Lite / S3R / S3RCam / S3RExt )
• Module Display adapter (HDMI output for M5Stack Core / Core2 / Tough / CoreS3 / CoreS3SE )
• Module RCA adapter (composite NTSC/PAL output for M5Stack Core / Core2 / Tough / (without ESP32S3 series))

Supported external speakers and audio adapters

• SPK HAT (with M5StickC / CPlus / M5Stack CoreInk)
• SPK HAT2 (with M5StickCPlus)
• ATOMIC SPK (with M5ATOM Lite / PSRAM / S3 / S3Lite / S3R / S3RCam / S3RExt )
• ATOMIC ECHO BASE (with M5ATOM Lite / PSRAM / S3 / S3Lite / S3R / S3RCam / S3RExt )
• Module Display adapter (Audio over HDMI for M5Stack Core / Core2 / Tough / CoreS3 / CoreS3SE )
• Module RCA adapter (M5Stack Core / Core2 / Tough)

Other supported external accessories

• Unit RTC
• Unit IMU

Hardware information

ESP32 GPIO list

| |M5Stack<BR>BASIC<BR>GRAY |M5Stack<BR>GO/FIRE |M5Stack<BR>Core2(AWS)<BR>Tough |M5Stick<BR>C/CPlus |M5Stick<BR>CPlus2 |M5Stack<BR>CoreInk |M5Paper |M5Station |M5ATOM<BR>Lite/Matrix<BR>ECHO/U<BR>PSRAM |M5STAMP<BR>PICO | | |:------------------:|:---------------------------------:|:---------------------------------:|:-------------------------------------:|:----------------------------:|:-------------------------:|:----------------------:|:---------------------:|:---------------------:|:---------------------------------------:|:------------------:|:------------------:| |GPIO 0<BR>ADC2_CH1|M-Bus<BR>IIS_MK |M-Bus<BR>IIS_MK |M-Bus<BR>SPK_LRCK<BR>PDM_C(Core2)|HAT<BR>PAD<BR>PDM_C |HAT<BR>PDM_C |EPD_RST | --- | --- | --- | |GPIO 0<BR>ADC2_CH1| |GPIO 1<BR>USB_TX |M-Bus<BR>Serial |M-Bus<BR>Serial |M-Bus<BR>Serial |Serial |Serial |Serial |Serial |Serial |Serial |Serial |GPIO 1<BR>USB_TX | |GPIO 2<BR>ADC2_CH2|M-Bus<BR> |M-Bus<BR> |M-Bus<BR>SPK_D |PAD<BR>Beep(CPlus) |Beep |Beep |PW_Hold |ReadEn | --- | --- |GPIO 2<BR>ADC2_CH2| |GPIO 3<BR>USB_RX |M-Bus<BR>Serial |M-Bus<BR>Serial |M-Bus<BR>Serial |Serial |Serial |Serial |Serial |Serial |Serial |Serial |GPIO 3<BR>USB_RX | |GPIO 4<BR>ADC2_CH0|TF_CS |TF_CS |TF_CS | --- |PW_Hold |EPD_BUSY |TF_CS |RGB LED | --- | --- |GPIO 4<BR>ADC2_CH0| |GPIO 5 |M-Bus |M-Bus |LCD_CS |LCD_CS |LCD_CS |BTN_HAT |EXT_5V |LCD_CS |Bus(P)<BR>PDM_C(U) | --- |GPIO 5 | |GPIO 9 | --- | --- | --- |InfraRed | --- |EPD_CS | --- | --- | --- | --- |GPIO 9 | |GPIO10 | --- | --- | --- |LED | --- |LED | --- | --- | --- | --- |GPIO10 | |GPIO12<BR>ADC2_CH5|M-Bus<BR>IIS_SK |M-Bus<BR>IIS_SK |SPK_BCLK | --- |LCD_RST |PW_Hold |SPI_MOSI |USB_PW |InfraRed | --- |GPIO12<BR>ADC2_CH5| |GPIO13<BR>ADC2_CH4|M-Bus<BR>IIS_WS |M-Bus<BR>IIS_WS |M-Bus<BR>RXD2 |SPI_SCLK |SPI_SCLK |MI-Bus<BR>RXD2 |SPI_MISO |PORT.C1 | --- | --- |GPIO