M5Unified

June 2, 2026 · View on GitHub

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
  • M5PaperColor
  • M5PaperMono
  • M5PowerHub
  • M5StopWatch

Supported devices (ESP32-C3)

  • M5STAMPC3 / C3U

Supported devices (ESP32-C6)

  • M5NanoC6
  • M5UnitC6L
  • ArduinoNessoN1

Supported devices (ESP32-H2)

  • M5NanoH2

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
BASIC
GRAY
M5Stack
GO/FIRE
M5Stack
Core2(AWS)
Tough
M5Stick
C/CPlus
M5Stick
CPlus2
M5Stack
CoreInk
M5PaperM5StationM5ATOM
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
SerialSerialSerialSerialSerialSerialSerialGPIO 1
USB_TX
GPIO 2
ADC2_CH2
M-Bus
M-Bus
M-Bus
SPK_D
PAD
Beep(CPlus)
BeepBeepPW_HoldReadEn------GPIO 2
ADC2_CH2
GPIO 3
USB_RX
M-Bus
Serial
M-Bus
Serial
M-Bus
Serial
SerialSerialSerialSerialSerialSerialSerialGPIO 3
USB_RX
GPIO 4
ADC2_CH0
TF_CSTF_CSTF_CS---PW_HoldEPD_BUSYTF_CSRGB LED------GPIO 4
ADC2_CH0
GPIO 5M-BusM-BusLCD_CSLCD_CSLCD_CSBTN_HATEXT_5VLCD_CSBus(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_RSTPW_HoldSPI_MOSIUSB_PWInfraRed---GPIO12
ADC2_CH5
GPIO13
ADC2_CH4
M-Bus
IIS_WS
M-Bus
IIS_WS
M-Bus
RXD2
SPI_SCLKSPI_SCLKMI-Bus
RXD2
SPI_MISOPORT.C1------GPIO13
ADC2_CH4
GPIO14
ADC2_CH6
LCD_CSLCD_CSM-Bus
TXD2
---LCD_D/CMI-Bus
TXD2
SPI_SCLKPORT.C1------GPIO14
ADC2_CH6
GPIO15
ADC2_CH3
M-Bus
IIS_OUT
M-Bus
RGB LED
LCD_D/CSPI_MOSISPI_MOSIEPD_D/CEPD_CSLCD_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
---------------PORT.C2
TXD2
------GPIO17
PSRAM
GPIO18M-Bus
SPI_SCLK
M-Bus
SPI_SCLK
SPI_SCLKLCD_RST---MI-Bus
SPI_SCLK
PORT.CSPI_SCLK---GPIO18
GPIO19M-Bus
SPI_MISO
M-Bus
SPI_MISO
M-Bus---LED
InfraRed
RTC_INTPORT.CLCD_D/CBus
SPK_C(ECHO)
*PDM_D(U)
GPIO19
GPIO21M-Bus
PORT.A
I2C0_SDA
M-Bus
PORT.A
I2C0_SDA
I2C1_SDAI2C1_SDAI2C1_SDAMI-Bus
I2C1_SDA
I2C1_SDAI2C1_SDABus
I2C1_SCL
GPIO21
GPIO22M-Bus
PORT.A
I2C0_SCL
M-Bus
PORT.A
I2C0_SCL
I2C1_SCLI2C1_SCLI2C1_SCLMI-Bus
I2C1_SCL
I2C1_SCLI2C1_SCLBus
SPK_D(ECHO)
GPIO22
GPIO23M-Bus
SPI_MOSI
M-Bus
SPI_MOSI
SPI_MOSILCD_D/C---MI-Bus
SPI_MOSI
EPD_RSTSPI_MOSIBus
PDM_D(ECHO)
---GPIO23
GPIO25
DAC1
M-Bus
SPK_DAC
M-Bus
SPK_DAC
M-Bus
RGB LED(AWS)
HAT(CPlus)
PAD
HATMI-Bus
HAT
PORT.A
I2C0_SDA
PORT.B1Bus
I2C1_SDA
GPIO25
DAC1
GPIO26
DAC2
M-BusM-Bus
PORT.B
M-BusHAT
PAD
HATMI-Bus
HAT
PORT.BPORT.B2PORT.A
I2C0_SDA
GPIO26
DAC2
GPIO27
ADC2_CH7
LCD_D/CLCD_D/CM-BusAXP192 VBUSENLCD_BLBTN_PWREPD_BUSYIMU_INTRGB LEDRGB LEDGPIO27
ADC2_CH7
GPIO32
ADC1_CH4
LCD_BLLCD_BLM-Bus
PORT.A
I2C0_SDA
PORT.A
I2C0_SDA
PORT.A
I2C0_SDA
PORT.A
I2C0_SDA
PORT.A
I2C0_SCL
PORT.A
I2C0_SDA
PORT.A
I2C0_SCL
PORT.A
I2C0_SDA
GPIO32
ADC1_CH4
GPIO33
ADC1_CH5
LCD_RSTLCD_RSTM-Bus
PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
PORT.BPORT.A
I2C0_SCL
Bus
PDM_C(ECHO)
PORT.A
I2C0_SCL
GPIO33
ADC1_CH5
GPIO34
ADC1_CH6
M-Bus
IIS_IN
M-Bus
MIC_ADC
IIS_IN
M-Bus
PDM_D(Core2)
PDM_DPDM_DMI-Bus
SPI_MISO
---USB Current?---GPIO34
ADC1_CH6
GPIO35
ADC1_CH7
M-BusM-BusM-BusRTC_INTBTN_PWRBAT_VBAT_VPORT.B1------GPIO35
ADC1_CH7
GPIO36
ADC1_CH0
M-BusM-Bus
PORT.B
M-BusHAT
PAD
HATMI-Bus
HAT
TP_INTPORT.B2------GPIO36
ADC1_CH0
GPIO37
ADC1_CH1
BTN_CBTN_C---BTN_ABTN_ASW_UpSW_UpBTN_A------GPIO37
ADC1_CH1
GPIO38
ADC1_CH2
BTN_BBTN_BM-Bus
SPI_MISO
PADBAT_VSW_PressSW_PressBTN_B------GPIO38
ADC1_CH2
GPIO39
ADC1_CH3
BTN_ABTN_ATP_INTBTN_BBTN_BSW_DownSW_DownBTN_CBTNBTNGPIO39
ADC1_CH3
M5Stack
BASIC
GRAY
M5Stack
GO/FIRE
M5Stack
Core2(AWS)
Tough
M5Stick
C/CPlus
M5Stick
CPlus2
M5Stack
CoreInk
M5PaperM5StationM5ATOM
Lite/Matrix
ECHO/U
PSRAM
M5STAMP
PICO

ESP32C3 GPIO list

M5Stamp
C3
M5Stamp
C3U
GPIO 0PORT.A
I2C0_SCL
PORT.A
I2C_SCL
GPIO 0
GPIO 1PORT.A
I2C0_SDA
PORT.A
I2C_SDA
GPIO 1
GPIO 2RGB LEDRGB LEDGPIO 2
GPIO 3BTN_ABusGPIO 3
GPIO 4BusBusGPIO 4
GPIO 5BusBusGPIO 5
GPIO 6BusBusGPIO 6
GPIO 7BusBusGPIO 7
GPIO 8BusBusGPIO 8
GPIO 9---BTN_AGPIO 9
GPIO10BusBusGPIO10
GPIO18
USB
PORT.U
D-
USB
PORT.U
D-
GPIO18
USB
GPIO19
USB
PORT.U
D+
USB
PORT.U
D+
GPIO19
USB
GPIO20USB
Serial
Bus
GPIO20
GPIO21USB
Serial
Bus
GPIO21
M5Stamp
C3
M5Stamp
C3U

ESP32S3 GPIO list

M5Stack
CoreS3
CoreS3SE
M5ATOMS3R
/ S3RCam
M5ATOMS3
/ S3Lite
M5ATOMS3UM5STAMPS3M5DialM5CapsuleM5Cardputer
GPIO 0M-Bus
SPK_LRCK
I2Cx_SCL
forIMU
------Bus
BTN_A
------BTN_AGPIO 0
GPIO 1PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
BusPORT.B---PORT.A
I2C0_SCL
GPIO 1
GPIO 2PORT.A
I2C0_SDA
PORT.A
I2C0_SDA
PORT.A
I2C0_SDA
PORT.A
I2C0_SDA
BusPORT.BBeepPORT.A
I2C0_SDA
GPIO 2
GPIO 3LCD_CSCAM_Y2vdd3v3vdd3v3BusBeep---KEY_MATRIXGPIO 3
GPIO 4TF_CSCAM_Y6InfraRed---BusLCD_RSInfraRedKEY_MATRIXGPIO 4
GPIO 5M-BusBusBus---BusLCD_MOSI---KEY_MATRIXGPIO 5
GPIO 6M-BusBusBus---BusLCD_SCKBAT_ADCKEY_MATRIXGPIO 6
GPIO 7M-BusBusBus---BusLCD_CS---KEY_MATRIXGPIO 7
GPIO 8M-Bus
PORT.B
BusBus---BusLCD_RSTI2C1_SDAKEY_MATRIXGPIO 8
GPIO 9M-Bus
PORT.B
I2Cy_SCL
forCam
------BusLCD_BL---KEY_MATRIXGPIO 9
GPIO10M-BusCAM_VSYNC------BusRFID_INTI2C1_SCLBAT_ADCGPIO10
GPIO11I2C1_SCLCAM_Y8------BusI2C1_SDATF_CSKEY_MATRIXGPIO11
GPIO12I2C1_SDAI2Cy_SDA
forCam
---InfraRedBusI2C1_SCLTF_MOSITF_CSGPIO12
GPIO13M-Bus
SPK_D
CAM_Y9------Bus
PORT.A
I2C0_SDA
PORT.A
I2C0_SDA
PORT.A
I2C0_SDA
KEY_MATRIXGPIO13
GPIO14M-Bus
MIC_IN
LCD_CS
CAM_HREF
---BusBusTP_INTTF_CLKTF_MOSIGPIO14
GPIO15CAM_D6LCD_SCLKLCD_CS---Bus
PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
KEY_MATRIXGPIO15
GPIO16CAM_D7IMU_INTLCD_BL---FPC---------GPIO16
GPIO17M-Bus
PORT.C
CAM_Y7LCD_SCLKBusFPC---------GPIO17
GPIO18M-Bus
PORT.C
POWER_N------FPC---------GPIO18
GPIO19
USB
USB
D--
USB
D--
USB
D--
USB
D--
USB
D--
USB
D--
USB
D--
USB
D--
GPIO19
USB
GPIO20
USB
USB
D++
USB
D++
USB
D++
USB
D++
USB
D++
USB
D++
USB
D++
USB
D++
GPIO20
USB
GPIO21I2C_INTLCD_MOSI
CAM_XCLK
LCD_MOSI---RGB LEDRGB LEDRGB LEDRGB_LEDGPIO21
GPIO33SPK_WCKOPI PSRAMLCD_DC---FPC------LCD_RSTGPIO33
GPIO34SPK_BCKOPI PSRAMLCD_RST---FPC------LCD_RSGPIO34
GPIO35M-Bus
SPI_MISO
LCD DC
OPI PSRAMRGB LEDRGB LEDFPC------LCD_DATGPIO35
GPIO36M-Bus
SPI_SCLK
OPI PSRAM------FPC------LCD_SCKGPIO36
GPIO37M-Bus
SPI_MOSI
OPI PSRAM------FPC------LCD_CSGPIO37
GPIO38CAM_HREFBusBus
I2C1_SDA
PDM_DATFPC------LCD_BLGPIO38
GPIO39CAM_D2BusBus
I2C1_SCL
PDM_CLKBus---TF_MISOTF_MISOGPIO39
GPIO40CAM_D3CAM_PCLK---BusBusENCODER_BMIC_CLKTF_CLKGPIO40
GPIO41CAM_D4BTN_ABTN_ABTN_ABusENCODER_AMIC_DATSPK_BCLKGPIO41
GPIO42CAM_D5LCD_D/D
CAM_Y3
---BusBusBTN_ABTN_ASPK_SDATAGPIO42
GPIO43M-Bus
SerialTX
---------Bus------I2S_LRCLKGPIO43
GPIO44M-Bus
SerialRX
---------Bus------InfraRedGPIO44
GPIO45CAM_PCLKI2Cx_SDA
forIMU
------------------GPIO45
GPIO46CAM_VSYNCCAM_Y4------BusHOLDHOLDMIC_DATGPIO46
GPIO47CAM_D9InfraRed------------------GPIO47
GPIO48CAM_D8LCD_RST
CAM_Y5
------------------GPIO48
M5Stack
CoreS3
M5ATOMS3R
/ S3RCam
M5ATOMS3
/ S3Lite
M5ATOMS3UM5STAMPS3M5DialM5CapsuleM5Cardputer

AXP192 power management IC connections

M5Stack
Core2
M5Stack
Tough
M5Stick
C
M5Stick
CPlus
M5Station
GPIO0
LDO0
BUS PW ENBUS PW ENMIC VCCMIC VCCPortA1.A2 ENGPIO0
LDO0
GPIO1SYS LEDTP RST------PortB1 ENGPIO1
GPIO2SPK ENSPK EN------PortB2 ENGPIO2
GPIO3------------PortC1 ENGPIO3
GPIO4LCD RST
TP RST
LCD RST------PortC2 ENGPIO4
EXTENPORT 5V ENPORT 5V ENPORT 5V ENPORT 5V ENPORT 5V ENEXTEN
BACKUPRTC BATRTC BATRTC BATRTC BAT---BACKUP
LDO1RTC VDDRTC VDDRTC VDDRTC VDDRTC VDDLDO1
LDO2LCD PW
Periph PW
LCD PW
Periph PW
LCD BLLCD BL---LDO2
LDO3VIB MOTORLCD BLLCD PWLCD PWLCD BLLDO3
DCDC1ESP32 VDDESP32 VDDESP32 VDDESP32 VDDESP32 VDDDCDC1
DCDC2---------------DCDC2
DCDC3LCD BL------------DCDC3

AXP2101 usage

M5Stack
Core2v1.1
M5Stack
CoreS3
CoreS3SE
ALDO1---VDD 1v8ALDO1
ALDO2LCD RSTVDDA 3v3ALDO2
ALDO3SPK ENCAM 3v3ALDO3
ALDO4Periph PW
TF,TP,LCD
TF 3v3ALDO4
BLDO1LCD BLAVDDBLDO1
BLDO2PORT 5V ENDVDDBLDO2
DLDO1/DC1VIB MOTORLCD BLDLDO1/DC1
DLDO2/DC2------DLDO2/DC2
BACKUPRTC BATRTC BATBACKUP

PinMap

M5Stack
BASIC/GRAY
GO/FIRE
FACES II
M5Stack
Core2
Core2AWS
TOUGH
M5Stack
CoreS3
CoreS3SE
Bus
M-Bus

M-Bus

M-Bus
※ HPWR=not connected to the ESP32. Used by modules capable of supplying 12V power.
M5Stack
BASIC/GRAY
GO/FIRE
FACES II
M5Stack
Core2
Core2AWS
TOUGH
M5Stack
CoreS3
M5Paper M5Station
PortA
PortA

PortA

PortA

PortA

PortA
PortB
PortB

PortB

PortB

PortB

PortB1

PortB2
PortC
PortC

PortC

PortC

PortC

PortC1

PortC2
PortD
PortD

PortD
PortE
PortE

PortE / 485
TOUGH485:12V
M5Stick
C
M5Stick
C Plus
M5Stack
CoreInk
M5Stamp
PICO
M5Stamp
C3
M5Stamp
C3U
PortA
HAT
Bus
MI-Bus
ATOM
Lite
ATOM
Matrix
ATOM
ECHO
ATOM
PSRAM
ATOM
U
PortA
Bus
ATOMS3
/S3Lite
NanoC6/Cardputer
PortA
Bus

SPI device

M5Stack
BASIC
GRAY
GO/FIRE
M5Stack
Core2
Tough
M5Stick
C
M5Stick
CPlus
M5Stack
CoreInk
M5Paper
DisplayILI9342C
320×240
CS:G14
ILI9342C
320×240
CS:G5
ST7735S
80×160
CS:G5
ST7789V2
135×240
CS:G5
GDEW0154M09
200×200
CS:G9
IT8951
960×540
CS:G15
Display
TF CardCS:4CS:4---------CS:4TF Card

I2C device

M5Stack
BASIC/GRAY
GO/FIRE
M5Stack
Core2
M5Stack
Tough
M5Stack
CoreS3
M5Stick
C
CPlus
M5Stack
CoreInk
M5PaperATOM
Matrix
M5Station
Touch
Panel
---FT6336U
38h
CHSC6540
2Eh
FT5xxx
38h
------GT911
14h or 5Dh
------Touch
Panel
RTC---BM8563
51h
BM8563
51h
BM8563
51h
BM8563
51h
BM8563
51h
BM8563
51h
---BM8563
51h
RTC
Power
Manage
IP5306
75h
AXP192
34h
AXP192
34h
AXP2101
34h
AXP192
34h
---------AXP192
34h
Power
Manage
IMUMPU6886
68h
MPU6886
68h (Ext)
---BMI270
69h
MPU6886
68h
------MPU6886
68h
MPU6886
68h (opt)
IMU
IMU
(old lot)
SH200Q
6Ch
---------SH200Q
6Ch
------------IMU
(old lot)
ENV---------LTR553ALS
23h
------SHT30
44h
------ENV
EEPROM------------------FM24C02
50h
------EEPROM
Camera---------GC0308
21h
---------------Camera
Speaker---------AW88298
36h
---------------Speaker
Microphone---------ES7210
40h
---------------Microphone
GPIO Expander---------AW9523B
58h
---------------GPIO Expander
Current
Voltage
Monitor
------------------------INA3221
40h/41h
(opt)
Current
Voltage
Monitor