Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
M

M5ez

> 编程语言
Open source

Complete interface builder for the M5Stack, an ESP32 based mini tinker-computer

386 stars0 likes0 views
WebsiteGitHub

About

Complete interface builder for the M5Stack, an ESP32 based mini tinker-computer

M5ez The easy way to program on the M5Stack

M5ez (pronounced "M5 easy") is a complete interface builder library for the M5Stack ESP32 system. It allows even novice programmers to create good looking interfaces. It comes with menus as text or as images, message boxes, very flexible button setup (including different length presses and multi-button functions), 3-button text input (you have to see it to believe it) and built-in Wifi support. Now you can concentrate on what your program does, and let M5ez worry about everything else.

written by Rop Gonggrijp, with help and contributions from many others

Introduction

The M5Stack is a small computer that is a tinkerer's dream. It is based on Espressif's ESP32 chip (with WiFi and Bluetooth), it has a 320x240 pixel color screen, three buttons, a speaker, an SD slot and it allows you to stack boards below it, each in their own plastic enclosure. The makers sell boards for GSM, GPS and LoRa (LOng RAnge radio) as well as a motor controller board and an empty experimenter board. The Chinese operation that makes them appears to sell a lot of them and I could get mine off of Amazon in a week. If you like to build things that you can hold in your hand and not just write code for yet another naked-looking board plugged into your USB port, this thing is your friend.

On the software side, the easiest way to program these is using the Arduino IDE. M5Stack provides a library which, when you include it, creates an m5 object instance that allows access to the various hardware components in the device. For instance: the display driver is accessible through commands all starting with m5.lcd..

Making something that looks good and allows users to interact with it is not simple though: you have to program everything yourself. If you try to make something a little more complex, you quickly get bogged down in figuring out where things go on the display, what state your interface is in, etc etc.

In the budding M5Stack community, there have been some initiatives to make it easier to create user interfaces. Most notably a M5Stack forum user named Calin make something called "M5Stack MultiApp" which allows more easy integration of multiple existing programs into one app. His work serves as an inspiration for my work. But as much as you could have multiple programs have a common user interface, creating the programs still was nowhere near simple enough.

Enter M5ez, our contribution to making programming on the M5Stack a lot easier. We hope you'll enjoy programming with this.

Other products by M5

M5 is not only making the M5stack anymore. There's now an M5Stick that is an even smaller ESP32 system with a smaller screen, there's the M5 Atom which has no screen and just LEDs, and soon there will be an M5stack Core2 which has a capacitive touch screen. We plan to support some of these devices, the stick support will be rolled out soon.

Alternatives

UiFlow

Since writing M5ez, there has been another interface toolkit for the M5Stack, called UiFlow. It uses a web-and-cloud-based IDE that can be seen as "blocky" symbols or as python and creates micropython code. UiFlow supports a lot of the hardware sold in conjunction with the M5Stack and is very much geared towards learning and education.

That said, building the functionality that comes "packaged" with M5ez would take quite a bit of work with UiFlow. If you have existing things that run on Arduino, like programming in C and/or with the Arduino IDE, then M5ez might be the better choice. Also it is generally easier to create consistent and visually pleasing interfaces in M5ez, and complex things can take surprisingly little work.

 

Getting started

M5ez is an Arduino library. To start using it with the Arduino IDE:

  • Choose Sketch -> Include Library -> Manage Libraries...
  • Type M5ez into the search box.
  • Click the row to select the library.
  • Click the Install button to install the library.
  • Repeat this process for the ezTime library

in File -> Examples you will now see an M5ez heading down under "Examples from custom libraries"

You'll have your first application on the screen in no time. You can also start with one of the sketches below in the "Menus" section of the documentation. In fact we strongly recommend that you play around with the M5ez demo application, since it is a comprehensive showcase of M5ez's functionality that will give you a good feel for what you can and cannot do with M5ez.

 

If you get fatal error: ezTime.h: No such file or directory

Note that it says above that you need to install two libraries: M5ez and ezTime.

Alternatively, you can install M5ez without the time library (and without the on-screen clock), by commenting out #define M5EZ_CLOCK in file m5ez.h in the M5ez library directory.

 

Structure of documentation

You've now seen the Introduction and Getting Started sections of the manual. Below is the User Manual which lists all the functions of M5ez in detail. At the end there's a Table of Contents which may be of help finding something.

Tech Notes

Separate from this document, there is a directory tech_notes where we keep useful technical notes that may be a bit too obscure or in-depth for a general user manual.

 

M5ez User Manual

M5ez is a complete system for building appliance-grade interfaces for the M5Stack. It comes with a lot of the common functionality built-in that a programmer would otherwise have to create. While it is very easy to create functional programs — just have a look at the examples that come with the library — the entire library can be a bit overwhelming because of how much it offers. The following is a reference for programmers that want to get the most out of M5ez. It is certainly not necessary to know or fully understand every function, but at some point you probably want to go through this document very quickly to see what M5ez can do for you.

If you feel anything is still unclear after reading this document, please file an issue in the repository. I take documentation seriously — if something is not clear in here, it is as much a bug as something that's wrong with the software itself. Pull requests for typos etc. gladly accepted.

 

How it all works

As you can see from the examples, the commands that activate M5ez's functionality start with ez.. That ez refers to an object ez that is within the "root namespace" of the sketch. Within it are commands like ez.msgBox, but also other objects. For instance: commands that deal with the entire screen are prefixed with ez.screen., WiFi commands start with ez.wifi. and so forth.

After you include the library with #include , those objects all exist. To get things going you then — in the void setup() part of your sketch — do ez.begin(). This replaces m5.begin, which is called from within ez.begin(). You still need to #include before #include if you want to use any commands from the m5 library in your sketch.

 

Screen

The screen object deals with the entire screen, which consists of an optional header at the top, optional buttons at the bottom and an area called "the canvas" in between.

void ez.screen.clear()

void ez.screen.clear(uint16_t color)

uint16_t ez.screen.background()

If you clear the screen, the header and buttons are hidden, the canvas is cleared, and the current background color is set to the color you specify, or to the background color from the current theme (ez.theme->background, see the chapter on themes) if you do not specify a color. ez.screen.background() will return the currently set background color.

If you clear the screen, the header and buttons are hidden, so the canvas takes up the entire screen.

 

Header

The header is the bar at the top of the screen. In the default theme it is 30 pixels high and blue, and it has text in font &FreeSansBold9pt7b, but all of that can be changed, either by modifying the values in the current theme on the fly or by creating your own theme.

Showing, hiding, title

void ez.header.show(String title = "")

void ez.header.title(String title = "")

bool ez.header.shown()

void ez.header.clear(bool wipe = true)

ez.header.show will show the header, either with the present title or with a new one provided as an argument. ez.header.title will merely change the title, but will not change whether the header is displayed or not. ez.header.shown() returns true or false depending on whether the header is currently shown, and ez.header.clear removes the header, returning the top of the screen to the canvas. If you set wipe to false, it will not draw background pixels there. (This may help prevent flicker or add a bit of performance if you're about to clear the canvas anyway.)

Your own header widgets

The clock and WiFi signal strength displayed in the M5ez header are "widgets". You can register your own code to display widgets too.

void ez.header.insert(uint8_t position, String name, uint16_t width, void (*function)(uint16_t x, uint16_t w), bool leftover = false)

void ez.header.remove(String name)

uint8_t ez.header.position(String name)

void ez.header.draw(String name = "")

ez.header.insert lets you add your own header widget. The header widget positions start at 0 (the leftmost widget), and position specifies t the left of which widget to insert the new one. name is just a name you use to refer to your widget. The names title, clock and wifi are reserved for use by M5ez.

Exactly one widget can be specified as leftover, meaning it gets all the pixels not claimed by any other widgets. By default, this is the widget called "title" that holds the header title. All other widgets must have a width in pixels specified.

function refers to the name of the function that draws your widget. It must be a function that returns nothing (void) and that takes two uint16_t arguments: the x position and width of your widget. This function will be called by the header code whenever the header is redrawn. But you can also force a redraw with ez.header.draw. For instance: the clock code calls for the clock widget to be redrawn every minute, for instance. Note that you would never call your widget draw function directly, because your code doesn't know where all the widgets are within the header. You would only ever call it indirectly using ez.header.draw("your_widget_name"), which will then see if the header is currently displayed, and if so lookup x position and width and call your draw function.

Your widget draw function has to make sure to stay inside the lines: not lower than ez.theme->header_height, not further left than x, not further right than x + w. If you want to be able to use your widget with multiple themes, your code should probably also respect ez.theme->header_bgcolor and ez.theme->header_fgcolor to make sure things look pretty.

ez.header.position will return the relative position of an existing header widget, starting with 0 for the leftmost widget, adding one for each further widget. This can be quite useful. For instance, if you want to make sure a widget is insert directly to the left of the title, you can specify ez.header.insert(ez.header.position("title"), .... If you specify (ez.header.position("title") + 1 your new widget gets inserted directly to the right of the title.

As the name implies, ez.header.remove removes the widget with the given name.

 

Canvas

The "canvas" is M5ez's name for the area between the header and buttons. So if there are no header and no buttons, the canvas is the whole screen. Once they are d

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

C++adafruit-gfxarduinobeginnersclock

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言