How to get started with M5Unified library

This document will guide you through the process of getting started with M5Unified, a library for the Arduino IDE and ESP-IDF.
* This document is based on information in M5Unified v0.0.7.

What is M5Unified?

M5Unified is a library to handle ESP32-based M5Stack products with ArduinoFramework.

Until now, M5Stack/M5Core2/M5StickC/M5StickCPlus/M5Atom had separate libraries for each product, and their usage (APIs) were also different. With M5Unified, all M5Stack series can be handled with the same usage (API), which is very convenient.

Also, once you get used to M5Unified, you can run different M5Stack series (e.g., M5Stack with screen and M5Atom without screen) with a single program code.

M5Unified can be used not only with Arduino framework but also with ESP-IDF framework.

Supported devices

Devices other than those listed below may also be supported. Please check M5Unified repository for the latest information.

Main device

• M5Stack Basic / Gray / Go / Fire

• M5Stack Core2 / Core2 for AWSIoT EduKit / M5Tough

• M5StickC / M5StickCPlus

• M5Stack CoreInk

• M5Paper

• M5Atom Lite / Matrix / Echo / PSRAM / U

• M5Stamp Pico / C3 /C3U

• M5Station

External Display

• Unit LCD

• Unit OLED

• Atom Display / Lite (Connect to M5Atom Lite / Matrix / PSRAM)

External Speaker

• SPK HAT (connects to M5StickC / M5StickCPlus / M5Stack CoreInk)

• Atomic SPK (connects to M5Atom Lite / PSRAM)

Install ArduinoIDE

Install ArduinoIDE

Install the library

Start ArduinoIDE and follow the steps below to install M5Unified.

How to use the library manager

Install M5Unified library.

• 1."Sketch" -> "Include Library" -> "Manage Libraries..." you will see the "Library Manager" on the left side of the editor.

• 2.Enter M5Unified in the "Filter your search" field and click "Install" when the "M5Unified by M5Stack" field appears.

3.

• 3.If you see "Install Library Dependencies", click "Install All".

The Library Manager may be used many times when using other Units, Modules, HAT, and BASE. Please remember how to use it.

Entering the program source

Enter the program code for HelloWorld or blinking RGB LEDs in the ArduinoIDE editor.

HelloWorld (for models with display)

The display and serial monitor will show "HelloWorld! on the display and serial monitor, and counts the numbers every second.

#include <M5Unified.h> // Make the M5Unified library available to your program.

// global variables (define variables to be used throughout the program)
uint32_t count;


// setup function is executed only once at startup.
// This function mainly describes the initialization process.
void setup() {

  auto cfg = M5.config(); // Assign a structure for initializing M5Stack
  // If config is to be set, set it here
  // Example.
  // cfg.external_spk = true;

  M5.begin(cfg);                        // initialize M5 device

  M5.Display.setTextSize(3);            // change text size
  M5.Display.print("Hello World!!!") ;  // display Hello World! and one line is displayed on the screen
  Serial.println("Hello World!!!") ;    // display Hello World! and one line on the serial monitor
  count = 0;                            // initialize count

}

// loop function is executed repeatedly for as long as it is running.
// loop function acquires values from sensors, rewrites the screen, etc.
void loop() {

  M5.Display.setCursor(0, 20);             // set character drawing coordinates (cursor position)
  M5.Display.printf("COUNT: %d\n", count); // display count on screen
  Serial.printf("COUNT: %d\n", count);  // display count serially
  count++;                              // increase count by 1
  delay(1000);                          // wait 1 second(1,000msec)

}

Blinking RGB LEDs (for models with RGB LEDs such as M5Atom and M5Stamp)

M5Unifed v0.0.7 does not support RGB LEDs and requires an external library such as FastLED.
Refer to Install Library and install the library "FastLED".

The serial monitor will display "Hello World! on the serial monitor and blinks the RGB LED green every second.

#include <M5Unified.h> // enable the M5Unified library.
#include <FastLED.h> // enable FastLED (RGB LED) library.

// Specify the number of RGB LEDs (25 for M5Atom Matrix).
#define NUM_LEDS 1
// Specify DATA PIN of RGB LEDs.
#define LED_DATA_PIN 27

// global variables (define variables to be used throughout the program)
uint32_t count;
CRGB leds[NUM_LEDS];

// setup function is executed only once at startup.
// This function mainly describes the initialization process.
void setup() {

  auto cfg = M5.config(); // assign a structure for initializing M5Stack
  // If config is to be set, set it here
  // Example.
  // cfg.external_spk = true;

  M5.begin(cfg); // initialize M5 device, Display is also initialized
  FastLED.addLeds<WS2811, LED_DATA_PIN, GRB>(leds, NUM_LEDS); // initialize RGB LEDs
  FastLED.setBrightness(20); // set the brightness (more than 20 may break due to heat.)
  Serial.println("Hello World!!!") ; // display Hello World!!! on serial monitor and one line is displayed on the serial monitor
  count = 0; // initialize count

}

// loop function is executed repeatedly for as long as it is running.
// loop function acquires values from sensors, rewrites the screen, etc.
void loop() {

  leds[0] = CRGB::Red; // set LED[0] to red
  FastLED.show(); // display LEDs
  delay(500); // wait 0.5 seconds
  leds[0] = CRGB::Black; // set LED to black
  FastLED.show(); // show LEDs (lights off because they are black)
  delay(500); // wait 0.5 seconds

  Serial.printf("COUNT: %d\n", count); // display count value on serial
  count++; // increase count by 1.
}

Compile

1. Connect device to PC

Connect the device to which the program is to be written to the PC.

Select the board.

• Open the menu "Tools" -> "Boards" -> "M5Stack" and select the board you want to write on.

3. Select the port

Check and select the port to which the device is connected. (The image shows the COM? port on Windows.)

• Port name for each OS

? > The name may vary depending on the chip in the device and the OS version.

4. Compile

Execute Sketch -> Write from the menu to write the program to the device after compiling. If an error occurs, it will be displayed in orange, so check the message to find out.

Related links

Parameters of M5.begin()

For details on items that can be set in M5.config(), see here .

Example usage

Creating

I plan to introduce concrete examples of how to get sensor values, control motors, etc.

Porting points to M5Unified (from product-specific libraries)

Many of the information available on the Internet uses product-specific libraries and cannot be used as is. In such cases, please refer to the following document for porting to M5Unified.

Porting points to M5Unified