# M5Unified and the case for one namespace across a device family

> M5Unified is a C++ library that gives M5Stack hardware a single API surface across dozens of boards, so a sketch written for one Core does not have to be rewritten for a CoreS3 or a Paper. The trade is that the library is a compatibility layer with real consequences, including a hard dependency on M5GFX and an Arduino-as-ESP-IDF-component trap that silently breaks class layouts.

**m5stack/M5Unified** — Unified library for M5Stack series

- Repository: https://github.com/m5stack/M5Unified
- Stars: 717 · Forks: 130
- Language: C++
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/m5stack-m5unified

## What one namespace actually abstracts

M5Unified is a library for the built-in hardware of M5Stack controllers, and all of its functionality is reached through the m5 namespace. The README lists what that covers.

Display access, fonts and graphical primitives come first, in conjunction with M5GFX, which the library requires to be installed. Then there is touchscreen and hardware button access, speaker and microphone access, power and battery charging control, accelerometer, gyroscope and magnetometer access, and real-time clock and wakeup timer access.

The point of the library is that these are the things that differ between boards. An M5Stack Core has a 320 by 240 screen, a CoreS3 has a larger touch panel, a CoreInk is an e-ink display with no backlight, and a Paper is a different panel again. Writing against one API means the sketch asks for a button press or a power-off rather than for a specific GPIO pin.

This is why the supported device list is so long, and it spans the whole ESP32 family. The list covers ESP32 boards such as the Core, Core2, M5Stick C, CoreInk, M5Station, M5Paper and the ATOM line, ESP32-S3 boards such as the CoreS3, M5StickS3, the ATOM S3 family, M5Cardputer, M5Dial, M5DinMeter, M5Capsule, M5AirQ and the M5PaperS3 variants, and then the newer silicon: ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2 and ESP32-P4 boards such as the M5Tab5 and M5STAMPP4.

There are also supported external displays and video adapters, external speakers and audio adapters, and other accessories such as Unit RTC and Unit IMU. A library that covers this many peripherals is necessarily an abstraction over a lot of variation, and the interesting questions are where that abstraction holds and where it leaks.

## The M5GFX dependency is not optional

M5Unified requires M5GFX to be installed, and that is the single most consequential line in the README for anyone deciding whether to use the library.

The display support is not built into M5Unified. It is provided in conjunction with M5GFX, which is a separate project with its own documentation and its own per-adapter guides, linked in the README for the Unit RCA, Unit GLASS and ATOM Display adapters. So a project that wants a screen is taking on two libraries and the adapter configuration that goes with the second one.

That arrangement makes sense for the vendor, since M5GFX is where the panel driver and the display configuration live, and it lets a single display abstraction serve both the on-board screens and the external adapters. It also means the board support list in M5Unified and the adapter support list in M5GFX have to be read together, which is exactly what a newcomer is warned about in the README's list of functionality built into the ESP32 ecosystem rather than the library.

That warning section is unusually honest for a hardware library. It states that some functionality is built into the ESP32 framework or available elsewhere, independent of any M5Stack hardware, and does not require or have explicit support in M5Unified. Network access over WiFi is built into the ESP32, micro SD card access works because SD cards are generic SPI devices, and there is also an infrared remote control transmitter and a colour-changing LED on some boards. The README's point is that a newcomer asking where M5Unified support for a feature is should first consider that it is either already in the platform or generic enough for any library to handle, including ones in the Arduino library manager that work with any platform.

## Examples that show the shape of the API

In the Arduino IDE, once the library is installed through the Library Manager, the examples appear under File, Examples, M5Unified, Basic. There is a combined demonstration, HowToUse, that exercises several functions in one sketch, and then a set of separate ones that each isolate a subsystem.

Displays prints text on each of the supported M5Stack displays. Button detects and responds to button presses. Touch detects and reacts to touch events. Speaker plays wave audio through the built-in speaker and through accessories that support audio. Rtc connects to an Internet time server over WiFi and sets the built-in clock. Microphone records a short clip and plays it back through the speaker. Imu demonstrates the accelerometer, gyro and magnetometer.

Advanced examples cover playing audio over Bluetooth and streaming and decoding MP3.

The structure tells you how the library is meant to be learned. Each subsystem is a self-contained sketch, so a new user can open the one matching the hardware they have and read working code rather than API documentation. The M5Unified header is all that is required, given as a single include line, and the library is usable from both the Arduino IDE and ESP-IDF, which are the two supported frameworks.

There is also an examples directory structure worth knowing about for anyone contributing: a Basic folder, an Advanced folder, a Test folder, and a PlatformIO_SDL example, the last of which suggests the library can be exercised against a software SDL target rather than only on physical hardware.

## The Arduino-as-ESP-IDF-component trap

The Notes section documents a subtle failure mode that is worth understanding before you build with ESP-IDF.

When arduino-esp32 is used as an ESP-IDF component alongside 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 the library 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. That is the failure: not a compile error, not a missing symbol, but two translation units disagreeing about the size or offsets of a type, which produces memory corruption that shows up far away from the cause.

Two CMake cache variables let you control this. Setting M5UNIFIED_ARDUINO_COMPONENT to a name handles the case where your Arduino component has a different name than the three searched for, and setting M5UNIFIED_ARDUINO_COMPONENT to OFF disables the automatic linking altogether.

The presence of that second option is a hint that the automatic behaviour is not always what you want. If you are mixing an Arduino-based library into an ESP-IDF build where the definitions are deliberately different, you need a way to opt out, and this is it.

The repository layout backs up the multi-toolchain story: component.mk for the Arduino build system, idf_component.yml for the ESP-IDF component manager, library.json and library.properties for PlatformIO and the Arduino IDE respectively, and a CMakeLists.txt at the root.

## What is not coming, and what is still missing

The README includes a section titled Desirable examples worthy of future contribution, which is a candid list of what does not exist yet.

The first is a Power example: detecting the battery level and charging state, powering off, and entering deep sleep mode when power off is unavailable. The second is battery lifespan management, described as a sketch that runs the battery down to an optimum storage percentage of around 40 percent before powering off as fully as possible, and separately charges it to a lifespan-preserving 75 percent maximum, on each device where the power management hardware supports it. The third is RTC wakeup, using the real-time clock to set a wakeup timer to power on or bring the device out of sleep mode after a set number of seconds, on devices that support it.

That last item is worth pausing on, because M5Unified does provide real-time clock and wakeup timer access, and yet a demonstration of using the RTC to wake the device is listed as desirable rather than shipped. The access and the complete usage pattern are not the same thing, and this is a good example of the gap between a library providing a primitive and a library providing a recipe.

The documentation also has a Hardware information section with an ESP32 GPIO list laid out as a table per board, and that table is cut off in the version of the README available here, right after the M5ATOM Lite and Matrix columns begin. So the one place you would look up exact pin assignments for a specific board is not fully readable without the full file.

A final note on the release history: the repository is not archived, the last push was on 2026-10-20, and the recent tags are 0.2.27 from 2026-10-20, 0.2.26 from 2026-10-13 and 0.2.25 from 2026-10-02. A 0.x version on a library covering this many devices is a signal to pin your version deliberately. The licence is MIT.

## Conclusion

M5Unified is a good fit for a team shipping firmware across several M5Stack form factors, since the display, IMU, audio and power calls stay the same when the board changes, and it works from both the Arduino IDE and ESP-IDF. It is a poor fit if you are on a single board, since the abstraction costs more than it returns, and a poor fit if you need the full GPIO map, because the README's hardware table is cut off before the pin assignments. Before adopting, confirm the exact board revision you ship is in the supported device list, and if you build with ESP-IDF, check that the Arduino component is linked automatically or set M5UNIFIED_ARDUINO_COMPONENT, because a mismatch means your application and your library disagree about the layout of the same classes.

## FAQ

### What is M5Unified and what hardware does it support?

M5Unified is a C++ library exposing the built-in hardware of M5Stack controllers through the m5 namespace, covering displays, touch, buttons, speaker, microphone, power, IMU and RTC. It supports ESP32, ESP32-S3, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2 and ESP32-P4 boards across the M5Stack, M5Stick, M5ATOM, M5Paper and M5Stamp lines.

### Do I need M5GFX to use M5Unified?

Yes. The README states that M5Unified requires M5GFX to be installed, and the display access, fonts and graphical primitives are provided in conjunction with M5GFX rather than being built into M5Unified itself.

### How do I use M5Unified in an ESP-IDF project built with arduino-esp32?

The library links the Arduino component automatically by looking for a component named arduino, arduino-esp32 or espressif__arduino-esp32 in the build. If yours has a different name, set the CMake cache variable M5UNIFIED_ARDUINO_COMPONENT to that name, or set it to OFF to disable the automatic linking.

### Which frameworks can I build M5Unified projects with?

The supported frameworks are ESP-IDF and the Arduino IDE. In the Arduino IDE, the library is installed through Library Manager and the example programs then appear under File, Examples, M5Unified, Basic.

## Sources

- [Issues](https://github.com/m5stack/M5Unified/issues)
- [License: MIT](https://github.com/m5stack/M5Unified/blob/master/LICENSE)
- [m5stack/M5Unified on GitHub](https://github.com/m5stack/M5Unified)
- [README](https://github.com/m5stack/M5Unified/blob/master/README.md)
- [Releases](https://github.com/m5stack/M5Unified/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/m5stack-m5unified