M5Unified

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) / S3Bat / S3Mini
• M5STAMPPLC
• M5Dial
• M5DinMeter
• M5Capsule
• M5Cardputer / M5CardputerADV
• M5VAMeter
• M5AirQ
• M5PaperS3
• M5PaperColor
• M5PaperMono
• M5PaperDIY
• M5PowerHub
• M5StopWatch
• M5StackChan
• M5ChainCaptain
• M5DualKey

Supported devices (ESP32-C3)

• M5STAMPC3 / C3U

Supported devices (ESP32-C5)

• M5STAMPC5
• M5ToughC5

Supported devices (ESP32-C6)

• M5NanoC6
• M5UnitC6L
• M5STAMPC6
• ArduinoNessoN1

Supported devices (ESP32-H2)

• M5NanoH2

Supported devices (ESP32-P4)

• M5Tab5
• M5STAMPP4
• M5UnitPoEP4

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

Notes

Arduino as an ESP-IDF component

When arduino-esp32 is used as an ESP-IDF component together with this library, the library links the Arduino component automatically (it looks for a component named arduino, arduino-esp32 or espressif__arduino-esp32 in the build) so that it is compiled with the same ARDUINO definitions as the application. Without that, the application and the library would see different layouts of the same classes. Set M5UNIFIED_ARDUINO_COMPONENT= (CMake cache variable) if your Arduino component has another name, or M5UNIFIED_ARDUINO_COMPONENT=OFF to disable this.

Hardware information

ESP32 GPIO list

| |M5Stack BASIC GRAY |M5Stack GO/FIRE |M5Stack Core2(AWS) Tough |M5Stick C/CPlus |M5Stick CPlus2 |M5Stack CoreInk |M5Paper |M5Station |M5ATOM Lite/Matrix ECHO/U PSRAM |M5STAMP

PICO | | |:------------------:|:---------------------------------:|:---------------------------------:|:-------------------------------------:|:----------------------------:|:-------------------------:|:----------------------:|:---------------------:|:---------------------:|:---------------------------------------:|:------------------:|:------------------:| |GPIO 0 ADC2_CH1|M-Bus IIS_MK |M-Bus IIS_MK |M-Bus SPK_LRCK PDM_C(Core2)|HAT PAD PDM_C |HAT PDM_C |EPD_RST | --- | --- | --- | |GPIO 0 ADC2_CH1| |GPIO 1 USB_TX |M-Bus Serial |M-Bus Serial |M-Bus Serial |Serial |Serial |Serial |Serial |Serial |Serial |Serial |GPIO 1 USB_TX | |GPIO 2 ADC2_CH2|M-Bus |M-Bus |M-Bus SPK_D |PAD Beep(CPlus) |Beep |Beep |PW_Hold |ReadEn | --- | --- |GPIO 2 ADC2_CH2| |GPIO 3 USB_RX |M-Bus Serial |M-Bus Serial |M-Bus Serial |Serial |Serial |Serial |Serial |Serial |Serial |Serial |GPIO 3 USB_RX | |GPIO 4 ADC2_CH0|TF_CS |TF_CS |TF_CS | --- |PW_Hold |EPD_BUSY |TF_CS |RGB LED | --- | --- |GPIO 4 ADC2_CH0| |GPIO 5 |M-Bus |M-Bus |LCD_CS |LCD_CS |LCD_CS |BTN_HAT |EXT_5V |LCD_CS |Bus(P) PDM_C(U) | --- |GPIO 5 | |GPIO 9 | --- | --- | --- |InfraRed | --- |EPD_CS | --- | --- | --- | --- |GPIO 9 | |GPIO10 | --- | --- | --- |LED | --- |LED | --- | --- | --- | --- |GPIO10 | |GPIO12 ADC2_CH5|M-Bus IIS_SK |M-Bus IIS_SK |SPK_BCLK | --- |LCD_RST |PW_Hold |SPI_MOSI |USB_PW |InfraRed | --- |GPIO12 ADC2_CH5| |GPIO13 ADC2_CH4|M-Bus IIS_WS |M-Bus IIS_WS |M-Bus RXD2 |SPI_SCLK |SPI_SCLK |MI-Bus RXD2 |SPI_MISO |PORT.C1 | --- | --- |GPIO13 ADC2_CH4| |GPIO14 ADC2_CH6|LCD_CS |LCD_CS |M-Bus TXD2 | --- |LCD_D/C |MI-Bus TXD2 |SPI_SCLK |PORT.C1 | --- | --- |GPIO14 ADC2_CH6| |GPIO15 ADC2_CH3|M-Bus IIS_OUT |M-Bus RGB LED |LCD_D/C |SPI_MOSI |SPI_MOSI |EPD_D/C |EPD_CS |LCD_RST | --- | --- |GPIO15 ADC2_CH3| |GPIO16 PSRAM |M-Bus RXD2 |M-Bus PORT.C RXD2 | --- | --- |--- | --- | --- |PORT.C2 RXD2 | --- | --- |GPIO16 PSRAM | |GPIO17 PSRAM |M-Bus TXD2 |M-Bus PORT.C TXD2 | --- | --- |--- | --- | ---