Introducing the M5Unified Library

This slide was used at "M5StackOpenDay2024" held at the M5Stack office on November 18, 2024.

Introducing "M5Unified", an integrated library that can be used for the entire M5Stack series.

Transcript

1. Introducing the M5Unified Library Core, Core2, Tough, StickC/CPlus, CoreInk, Paper, Station, Atom, Stamp… One library for all devices
2. What is「M5Unified」？ ・Library for the M5Stack series, compatible with Arduino and ESP-IDF environments ・Can be used with almost all models equipped with the ESP32 series. ・Same operation whether the display is LCD , EPD or OLED !! ・Same operation whether the speaker is I2S audio, analog connection, or buzzer !! M5Unified.h M5Unified.h M5Unified.h M5Unified.h M5Unified.h M5Unified.h M5Unified.h
3. What is「M5Unified」？ ・Also compatible with ATOM,ATOMS3,STAMPC3,STAMPS3 ・Supports external display ! M5Unified.h M5Unified.h M5Unified.h M5Unified.h M5Unified.h M5Unified.h
4. ・Supports multiple displays including the built-in display + external display ! What is「M5Unified」？ M5Unified.h M5Unified.h M5Unified.h M5Unified.h M5Unified.h M5Unified.h M5Unified.h
5. ・It can be used in the same way for both color and monochrome ! ・Since monochrome color reduction is performed automatically, you don't have to worry about differences with color LCDs! What if the screen is monochrome ?
6. ・Of course, it also supports external speakers. 　・HAT SPK 　・HAT SPK2 　・ATOMIC SPK 　・Module RCA 　・Module Display ※ Speakers other than those listed above can also be used with a little configuration. What if the speakers are external?
7. What's more, it can run on a PC without using the actual devices! ・It can be run on a PC using the cross-platform library “SDL” ・SDL=Simple DirectMedia Layer ・Common source code supports Windows,macOS,Linux ・Display・Speaker・Button・Touch with mouse It works the same on any OS. How to use =>> M5GFX/examples/PlatformIO_SDL/README.md https://github.com/m5stack/M5GFX/blob/master/examples/PlatformIO_SDL/README.md
8. How to use M5Unified? ・Install both “M5Unified” and “M5GFX” from the Library Manager ※ It is already registered in the ArduinoIDE , PlatformIO , ESP Component Registry
9. How to use M5Unified? ・「#include <M5Unified.h>」is OK for any model ・Moreover, Model detection is done at runtime, even if you select the wrong target model in the board manager, it will usually work normally. 　(e.g.You can also select M5StickC and write Core2 .) #include <M5Unified.h> void setup() { M5.begin(); } void loop() { M5.update(); M5.Display.print( "Hello M5Stack!"); }
10. How to use an external display ? ・It will work if you add the 「#include」 for the external display to the beginning. 　※ Write it before 「#include <5Unified.h> 」 #include <M5AtomDisplay.h> #include <M5UnitLCD.h> #include <M5UnitOLED.h> #include <M5Unified.h> void setup() { M5.begin(); } void loop() { M5.update(); M5.Display.print( "Hello M5Stack!"); }
11. How to use multiple displays ? ・Just perform the operation on M5.Displays(#). ・The number of displays can be obtained using the M5.getDisplayCount() . #include <M5ModuleDisplay.h> #include <M5UnitLCD.h> #include <M5UnitOLED.h> #include <M5Unified.h> void setup() { M5.begin(); int c=M5.getDisplayCount(); for(int i=0;i<c;i++) { M5.Displays(i).print(i); } } Displays(0) Displays(1) Displays(2) Displays(3)
12. How to use a speaker ? ・For simple sounds, use the M5.Speaker.tone . Argument 1 sets the frequency. Argument 2 sets the playback time. ・It runs in the background as a separate task. ・The example on the right plays the three notes C, E, and G in order, (It creates a chord!) ・Up to eight sounds can be layered. #include <M5Unified.h> void setup() { M5.begin(); M5.Speaker.tone(523.251, 2000); delay(500); M5.Speaker.tone(659.255, 2000); delay(500); M5.Speaker.tone(783.991, 2000); }
13. How to use external speakers? ・Just perform the configuration when executing the M5.begin function. #include <M5Unified.h> void setup() { auto cfg = M5.config(); // Set the display you want to use to true. cfg.external_speaker.hat_spk = true; cfg.external_speaker.hat_spk2 = true; cfg.external_speaker.atomic_spk = true; cfg.external_speaker.module_rca = true; cfg.external_speaker.module_display=true; M5.begin(cfg); }
14. Tips for working on multiple devices . ・This is a library that can be used on any device, but… It requires some ingenuity when writing the code. For example… ・The drawing coordinates are calculated by yourself. ・Switch drawing layouts according to screen ratio. ・Switch button operation method according to the model. ・The drawing destination is switched depending on whether or not there is an external displays.
15. Tips for working on multiple devices . (e.g. How to draw a circle in the screen center?) ・If you write it like the code on the right... If the resolution is 320x240, it will be displayed in the center of the screen as intended. M5.Display.fillCircle( 160, // X Center 120, // Y Center 60, // radius TFT_GREEN // color );
16. Tips for working on multiple devices . (e.g. How to draw a circle in the screen center?) ・But if the resolution is different... 　The position will shift. M5.Display.fillCircle( 160, // X Center 120, // Y Center 60, // radius TFT_GREEN // color );
17. Tips for working on multiple devices . (e.g. How to draw a circle in the screen center?) ・Just calculate the coordinates! 　M5.Display.width() 　M5.Display.height() Divide by 2 to get the center position. M5.Display.fillCircle( M5.Display.width() / 2, M5.Display.height() / 2, M5.Display.height() / 4, TFT_GREEN );
18. Tips for working on multiple devices . (e.g. How to change the layout by aspect ratio?) ・Split left and right to display different content. However, depending on the device, it may be divided into long, thin pieces. Want to divide it into as close to a square as possible, right? M5.Display.fillRect( 0, 0, M5.Display.width() / 2, M5.Display.height(), TFT_BLUE); M5.Display.fillRect( M5.Display.width() / 2, 0, M5.Display.width() / 2, M5.Display.height(), TFT_YELLOW);
19. Tips for working on multiple devices . (e.g. How to change the layout by aspect ratio?) ・Just compare the width and height and branch. 　If it is horizontal, split it into left and right halves. 　If it is vertical, split it into upper and lower halves. if (M5.Display.width() >= M5.Display.height()) { // split it into // left and right halves } else { // split it into // upper and lower halves }
20. Tips for working on multiple devices . (e.g. How to standardize operation methods?) ・For example, when creating a UI, 　「Button A」= Move to left 　「Button B」= Enter 　「Button C」= Move to right 　 implement the above operation method... if (M5.BtnA.wasClicked()){ // Move to left } if (M5.BtnB.wasClicked()){ // Enter } if (M5.BtnC.wasClicked()){ // Move to right } A B C
21. Tips for working on multiple devices . (e.g. How to standardize operation methods?) ・CoreInk and Paper seem fine as is . ・But, StickC/CPlus does not have button C, so it is not possible to move right. Also, button A should be the confirmation operation. A B C A B C A B PWR EXT PWR if (M5.BtnA.wasClicked()){ // Move to left } if (M5.BtnB.wasClicked()){ // Enter } if (M5.BtnC.wasClicked()){ // Move to right }
22. ・Create a branch using M5.getBoard() function ! ・Changed processing for StickC/CPlus . 　PWR = Move to left / A = Enter / B = Move to right. A B C A B C A B PWR HAT PWR Tips for working on multiple devices . (e.g. How to standardize operation methods?) switch (M5.getBoard()) { case m5gfx::board_M5StickC: case m5gfx::board_M5StickCPlus: // For StickC/CPlus // PWR=Left,A=Enter,B=Right break; default: // For other models // A=Left,B=Enter,C=Right break; }
23. ・e.g. If you use ModuleDisplay with M5Stack, When using M5.Display, it is drawn on the built-in LCD. ・Can I use ModuleDisplay if it is connected ? Tips for working on multiple devices . (e.g. How to prioritize external screens) #include <M5ModuleDisplay.h> #include <M5Unified.h> void setup() { M5.begin(); M5.Display.print(”which?”); } M5.Display
24. ・Just specify the screen you want to use first with the M5.setPrimaryDisplayType function! ※ If the screen is not found it has no effect. Tips for working on multiple devices . (e.g. How to prioritize external screens) #include <M5ModuleDisplay.h> #include <M5Unified.h> void setup() { M5.begin(); M5.setPrimaryDisplayType({ m5gfx::board_M5ModuleDisplay}); M5.Display.print(”which?”); } M5.Display
25. Advantages and disadvantages of M5Unified Advantages： ・One code can easily support multiple models. ・Since the model can be identified at run time, there is no need to separate the execution binary for each model. ・M5Unified functions can be used in both Arduino and ESP-IDF environments. disadvantages： ・Not fully compatible with previous libraries. ・Support for model-specific functions is not yet complete. ( encoder , camera , RFID ) ・A signal may be sent from GPIO at startup to identify the model.
26. Please make use of M5Unified !!! Thank you for your attention !