Skip to content

m5stack/M5Unified

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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
  • M5ATOMS3 / S3Lite / S3U
  • M5STAMPS3
  • M5Dial
  • M5DinMeter
  • M5Capsule
  • M5Cardputer
  • M5VAMeter

Supported devices (ESP32-C3)

  • M5STAMPC3 / C3U

Supported devices (ESP32-C6)

  • M5NanoC6

Supported external displays and video adapters

  • Unit LCD
  • Unit OLED
  • Unit Mini OLED
  • Unit RCA
  • Unit GLASS
  • Unit GLASS2
  • ATOM Display adapter (HDMI output for M5ATOM Lite / Matrix / PSRAM / S3 / S3Lite)
  • Module Display adapter (HDMI output for M5Stack Core / Core2 / Tough)
  • Module RCA adapter (composite NTSC/PAL output for M5Stack Core / Core2 / Tough)

Supported external speakers and audio adapters

  • SPK HAT (with M5StickC / CPlus / M5Stack CoreInk)
  • SPK HAT2 (with M5StickCPlus)
  • ATOMIC SPK (with M5ATOM Lite / PSRAM / ATOMS3 / S3Lite)
  • Module Display adapter (Audio over HDMI for M5Stack Core / Core2 / Tough)
  • 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
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
--- --- --- --- --- PORT.C2
TXD2
--- --- GPIO17
PSRAM
GPIO18 M-Bus
SPI_SCLK
M-Bus
SPI_SCLK
SPI_SCLK LCD_RST --- MI-Bus
SPI_SCLK
PORT.C SPI_SCLK --- GPIO18
GPIO19 M-Bus
SPI_MISO
M-Bus
SPI_MISO
M-Bus --- LED
InfraRed
RTC_INT PORT.C LCD_D/C Bus
SPK_C(ECHO)
*PDM_D(U)
GPIO19
GPIO21 M-Bus
PORT.A
I2C0_SDA
M-Bus
PORT.A
I2C0_SDA
I2C1_SDA I2C1_SDA I2C1_SDA MI-Bus
I2C1_SDA
I2C1_SDA I2C1_SDA Bus
I2C1_SCL
GPIO21
GPIO22 M-Bus
PORT.A
I2C0_SCL
M-Bus
PORT.A
I2C0_SCL
I2C1_SCL I2C1_SCL I2C1_SCL MI-Bus
I2C1_SCL
I2C1_SCL I2C1_SCL Bus
SPK_D(ECHO)
GPIO22
GPIO23 M-Bus
SPI_MOSI
M-Bus
SPI_MOSI
SPI_MOSI LCD_D/C --- MI-Bus
SPI_MOSI
EPD_RST SPI_MOSI Bus
PDM_D(ECHO)
--- GPIO23
GPIO25
DAC1
M-Bus
SPK_DAC
M-Bus
SPK_DAC
M-Bus
RGB LED(AWS)
HAT(CPlus)
PAD
HAT MI-Bus
HAT
PORT.A
I2C0_SDA
PORT.B1 Bus
I2C1_SDA
GPIO25
DAC1
GPIO26
DAC2
M-Bus M-Bus
PORT.B
M-Bus HAT
PAD
HAT MI-Bus
HAT
PORT.B PORT.B2 PORT.A
I2C0_SDA
GPIO26
DAC2
GPIO27
ADC2_CH7
LCD_D/C LCD_D/C M-Bus AXP192 VBUSEN LCD_BL BTN_PWR EPD_BUSY IMU_INT RGB LED RGB LED GPIO27
ADC2_CH7
GPIO32
ADC1_CH4
LCD_BL LCD_BL M-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_RST LCD_RST M-Bus
PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
PORT.B PORT.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_D PDM_D MI-Bus
SPI_MISO
--- USB Current? --- GPIO34
ADC1_CH6
GPIO35
ADC1_CH7
M-Bus M-Bus M-Bus RTC_INT BTN_PWR BAT_V BAT_V PORT.B1 --- --- GPIO35
ADC1_CH7
GPIO36
ADC1_CH0
M-Bus M-Bus
PORT.B
M-Bus HAT
PAD
HAT MI-Bus
HAT
TP_INT PORT.B2 --- --- GPIO36
ADC1_CH0
GPIO37
ADC1_CH1
BTN_C BTN_C --- BTN_A BTN_A SW_Up SW_Up BTN_A --- --- GPIO37
ADC1_CH1
GPIO38
ADC1_CH2
BTN_B BTN_B M-Bus
SPI_MISO
PAD BAT_V SW_Press SW_Press BTN_B --- --- GPIO38
ADC1_CH2
GPIO39
ADC1_CH3
BTN_A BTN_A TP_INT BTN_B BTN_B SW_Down SW_Down BTN_C BTN BTN GPIO39
ADC1_CH3
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

ESP32C3 GPIO list

M5Stamp
C3
M5Stamp
C3U
GPIO 0 PORT.A
I2C0_SCL
PORT.A
I2C_SCL
GPIO 0
GPIO 1 PORT.A
I2C0_SDA
PORT.A
I2C_SDA
GPIO 1
GPIO 2 RGB LED RGB LED GPIO 2
GPIO 3 BTN_A Bus GPIO 3
GPIO 4 Bus Bus GPIO 4
GPIO 5 Bus Bus GPIO 5
GPIO 6 Bus Bus GPIO 6
GPIO 7 Bus Bus GPIO 7
GPIO 8 Bus Bus GPIO 8
GPIO 9 --- BTN_A GPIO 9
GPIO10 Bus Bus GPIO10
GPIO18
USB
PORT.U
D-
USB
PORT.U
D-
GPIO18
USB
GPIO19
USB
PORT.U
D+
USB
PORT.U
D+
GPIO19
USB
GPIO20 USB
Serial
Bus
GPIO20
GPIO21 USB
Serial
Bus
GPIO21
M5Stamp
C3
M5Stamp
C3U

ESP32S3 GPIO list

M5Stack
CoreS3
CoreS3SE
M5ATOMS3
/ S3Lite
M5ATOMS3U M5STAMPS3 M5Dial M5Capsule M5Cardputer
GPIO 0 M-Bus
SPK_LRCK
--- --- Bus
BTN_A
--- --- BTN_A GPIO 0
GPIO 1 PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
Bus PORT.B --- PORT.A
I2C0_SCL
GPIO 1
GPIO 2 PORT.A
I2C0_SDA
PORT.A
I2C0_SDA
PORT.A
I2C0_SDA
Bus PORT.B Beep PORT.A
I2C0_SDA
GPIO 2
GPIO 3 LCD_CS vdd3v3 vdd3v3 Bus Beep --- KEY_MATRIX GPIO 3
GPIO 4 TF_CS InfraRed --- Bus LCD_RS InfraRed KEY_MATRIX GPIO 4
GPIO 5 M-Bus Bus --- Bus LCD_MOSI --- KEY_MATRIX GPIO 5
GPIO 6 M-Bus Bus --- Bus LCD_SCK BAT_ADC KEY_MATRIX GPIO 6
GPIO 7 M-Bus Bus --- Bus LCD_CS --- KEY_MATRIX GPIO 7
GPIO 8 M-Bus
PORT.B
Bus --- Bus LCD_RST I2C1_SDA KEY_MATRIX GPIO 8
GPIO 9 M-Bus
PORT.B
--- --- Bus LCD_BL --- KEY_MATRIX GPIO 9
GPIO10 M-Bus --- --- Bus RFID_INT I2C1_SCL BAT_ADC GPIO10
GPIO11 I2C1_SCL --- --- Bus I2C1_SDA TF_CS KEY_MATRIX GPIO11
GPIO12 I2C1_SDA --- InfraRed Bus I2C1_SCL TF_MOSI TF_CS GPIO12
GPIO13 M-Bus
SPK_D
--- --- Bus
PORT.A
I2C0_SDA
PORT.A
I2C0_SDA
PORT.A
I2C0_SDA
KEY_MATRIX GPIO13
GPIO14 M-Bus
MIC_IN
--- Bus Bus TP_INT TF_CLK TF_MOSI GPIO14
GPIO15 CAM_D6 LCD_CS --- Bus
PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
PORT.A
I2C0_SCL
KEY_MATRIX GPIO15
GPIO16 CAM_D7 LCD_BL --- FPC --- --- --- GPIO16
GPIO17 M-Bus
PORT.C
LCD_SCLK Bus FPC --- --- --- GPIO17
GPIO18 M-Bus
PORT.C
--- --- FPC --- --- --- GPIO18
GPIO19
USB
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++
GPIO20
USB
GPIO21 I2C_INT LCD_MOSI --- RGB LED RGB LED RGB LED RGB_LED GPIO21
GPIO33 SPK_WCK LCD_DC --- FPC --- --- LCD_RST GPIO33
GPIO34 SPK_BCK LCD_RST --- FPC --- --- LCD_RS GPIO34
GPIO35 M-Bus
SPI_MISO
LCD DC
RGB LED RGB LED FPC --- --- LCD_DAT GPIO35
GPIO36 M-Bus
SPI_SCLK
--- --- FPC --- --- LCD_SCK GPIO36
GPIO37 M-Bus
SPI_MOSI
--- --- FPC --- --- LCD_CS GPIO37
GPIO38 CAM_HREF Bus
I2C1_SDA
PDM_DAT FPC --- --- LCD_BL GPIO38
GPIO39 CAM_D2 Bus
I2C1_SCL
PDM_CLK Bus --- TF_MISO TF_MISO GPIO39
GPIO40 CAM_D3 --- Bus Bus ENCODER_B MIC_CLK TF_CLK GPIO40
GPIO41 CAM_D4 BTN_A BTN_A Bus ENCODER_A MIC_DAT SPK_BCLK GPIO41
GPIO42 CAM_D5 --- Bus Bus BTN_A BTN_A SPK_SDATA GPIO42
GPIO43 M-Bus
SerialTX
--- --- Bus --- --- I2S_LRCLK GPIO43
GPIO44 M-Bus
SerialRX
--- --- Bus --- --- InfraRed GPIO44
GPIO45 CAM_PCLK --- --- --- --- --- --- GPIO45
GPIO46 CAM_VSYNC --- --- Bus HOLD HOLD MIC_DAT GPIO46
GPIO47 CAM_D9 --- --- --- --- --- --- GPIO47
GPIO48 CAM_D8 --- --- --- --- --- --- GPIO48
M5Stack
CoreS3
M5ATOMS3
/ S3Lite
M5ATOMS3U M5STAMPS3 M5Dial M5Capsule M5Cardputer

AXP192 power management IC connections

M5Stack
Core2
M5Stack
Tough
M5Stick
C
M5Stick
CPlus
M5Station
GPIO0
LDO0
BUS PW EN BUS PW EN MIC VCC MIC VCC PortA1.A2 EN GPIO0
LDO0
GPIO1 SYS LED TP RST --- --- PortB1 EN GPIO1
GPIO2 SPK EN SPK EN --- --- PortB2 EN GPIO2
GPIO3 --- --- --- --- PortC1 EN GPIO3
GPIO4 LCD RST
TP RST
LCD RST --- --- PortC2 EN GPIO4
EXTEN PORT 5V EN PORT 5V EN PORT 5V EN PORT 5V EN PORT 5V EN EXTEN
BACKUP RTC BAT RTC BAT RTC BAT RTC BAT --- BACKUP
LDO1 RTC VDD RTC VDD RTC VDD RTC VDD RTC VDD LDO1
LDO2 LCD PW
Periph PW
LCD PW
Periph PW
LCD BL LCD BL --- LDO2
LDO3 VIB MOTOR LCD BL LCD PW LCD PW LCD BL LDO3
DCDC1 ESP32 VDD ESP32 VDD ESP32 VDD ESP32 VDD ESP32 VDD DCDC1
DCDC2 --- --- --- --- --- DCDC2
DCDC3 LCD BL --- --- --- --- DCDC3

AXP2101 usage

M5Stack
Core2v1.1
M5Stack
CoreS3
CoreS3SE
ALDO1 --- VDD 1v8 ALDO1
ALDO2 LCD RST VDDA 3v3 ALDO2
ALDO3 SPK EN CAM 3v3 ALDO3
ALDO4 Periph PW
TF,TP,LCD
TF 3v3 ALDO4
BLDO1 LCD BL AVDD BLDO1
BLDO2 PORT 5V EN DVDD BLDO2
DLDO1/DC1 VIB MOTOR LCD BL DLDO1/DC1
DLDO2/DC2 --- --- DLDO2/DC2
BACKUP RTC BAT RTC BAT BACKUP

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
Display ILI9342C
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 Card CS:4 CS:4 --- --- --- CS:4 TF Card

I2C device

M5Stack
BASIC/GRAY
GO/FIRE
M5Stack
Core2
M5Stack
Tough
M5Stack
CoreS3
M5Stick
C
CPlus
M5Stack
CoreInk
M5Paper ATOM
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
IMU MPU6886
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