M5Stack-SD-Updater

ABOUT

• M5Stack-SD-Updater is an Platform.io/Arduino library for M5Stack or Odroid-Go to package your apps on a SD card and load them from a menu such as the default SD Menu example of this project or @lovyan03's Treeview based SD Menu. For a Micropython compatible version of this library, see the M5Stack_MicroPython custom_sdupdater

• It is inspired by gamebuino, however it does not use a modified bootloader.

• Video demonstration

• This project by tobozo - built on M5Stack-SAM by Tom Such. Further credits listed below.

• Contributors welcome !

🏭 M5Stack-SD-Menu EXAMPLE SKETCH PREREQUISITES:

Micro SD Card (TF Card) - formatted using FAT32. Max size 32 Gb.

Make sure you have the following libraries: - they should be installed in: ....\Documents\Arduino\libraries

• M5Stack library or ESP32-Chimera-Core - this is probably already installed - if not you can get it from the Arduino Library Manager or by performing a manual installation

• M5Stack-SD-Updater (this project): get it from the Arduino Library Manager or by performing a manual installation

• ArduinoJSON: https://github.com/bblanchon/ArduinoJson/ available in the Arduino Library Manager

• M5StackSAM: https://github.com/tobozo/M5StackSAM/ (modified version until patch is merged) (custom version now bundled with the launcher)

🍱 UNPACKING THE BINARIES

For your own lazyness, you can use @micutil's awesome M5Burner and skip the next steps.

... or customize your own menu and make the installation manually :

1) Open both sketches from the "examples/M5Stack-SD-Update" menu.

2) Download the SD-Content 💾 folder from the release page and unzip it into the root of the SD Card. Then put the SD Card into the M5Stack. This zip file comes preloaded with precompiled apps and the relative meta information for the menu.

3) Compile the "M5Stack-SD-Menu.ino" example.
This sketch is the menu app. It must be (a) compiled and saved to the root directory of a micro SD card for persistence and (b) flashed onto the M5Stack.

(a) In the Arduino IDE, go to Sketch / Export compiled binary , and compile the file. Rename the file "menu.bin" and copy it to the micro SD card. (b) Next, flash "menu.bin" to the M5Stack.

Note that you won't need to (a) copy it if you previously extracted the SD-Content folder on the SD card.

4) Make sketches compatible with the SD-Updater Menu .

The brief bit of code in the "M5Stack-SDLoader-Snippet.ino" sketch can be used to make any Arduino compatible sketch compatible for use with the SD-Updater menu.

In your sketch, find the line where the core library is included:

   // #include <M5Stack.h>
   // #include <M5Core2.h>
   // #include <ESP32-Chimera-Core.h>
   // #include <M5StickC.h>

And add this:

    #include <M5StackUpdater.h>

In your setup() function, find the following statements:

    M5.begin();

And add this:

    checkSDUpdater();

Then do whatever you need to do (button init, timers) in the setup and the loop. Your app will be ready to run normally except at boot if the Button A is pressed, it will load the "menu.bin" from the sd card.

Touch UI has no buttons, this raises the problem of detecting a 'pushed' state when the touch is off. As a compensation, an UI will be visible for 2 seconds after every ESP.restart(), and this visibility can be forced in the setup :

    checkSDUpdater( SD, MENU_BIN, 2000 );

Headless setups can overload SDUpdater::assertStartUpdate with their own button/sensor/whatever detection routine.

    Serial.begin( 115200 );

    if(digitalRead(BUTTON_A_PIN) == 0) {
      Serial.println("Will Load menu binary");
      updateFromFS(SD);
      ESP.restart();
    }

Custom SD-Load scenarios can be achieved using non default values:

    M5.begin();

    checkSDUpdater(
      SD,           // filesystem (default=SD)
      MENU_BIN,     // path to binary (default = /menu.bin, empty string = rollback only)
      0,            // wait delay, (default=0, will be forced to 2000 upon ESP.restart() )
      TFCARD_CS_PIN // (usually default=4 but your mileage may vary)
    );

Export the compiled binary ( on the Arduino IDE menu go to: Sketch / Export Compiled Binary ).

(Optional) Rename the file to remove unnecessary additions to the name. The filename will be saved as "filename.ino.esp32.bin". Edit the name so it reads "filename.bin". This is purely for display purposes. The file will work without this change.

Use one of following methods to get the app on the M5Stack:

• Manually copy it to the sd card

• Existing installations (menu.bin already copied and loaded on the M5Stack): clear the content of the examples/M5Stack-SD-Menu/data folder, copy the compiled binary there and use the ESP32 Sketch Data Uploader utility (available from the Tools menu in the Arduino IDE).

📚 USAGE:

When an app is loaded in memory, booting the M5Stack with the BTN_A pushed will flash back the menu.bin into memory.

When the menu is loaded in memory, it will list all available apps on the sdcard and load them on demand.

Booting the M5Stack with the BTN_A pushed will power it off.

The ESP32 Sketch Data Uploader can be used to send .bin, jpg, json, mod and mp3 files onto the M5Stack. The menu.bin will take care of dumping them on the SD Card.

Some artwork/credits can be added for every uploaded binary, the menu will scan for these file types:

• .bin compiled application binary

• .jpg image/icon (max 200x100)

• .json file with dimensions descriptions:

{"width":128,"height":128,"authorName":"tobozo","projectURL":"http://short.url","credits":"** http://very.very.long.url ~~"}

If no info is provided, it will be pulled from the app's repository public information.

⚠️ The jpg/json file names must match the bin file name, case matters! jpg/json files are optional but must both be set if provided. The value for "credits" JSON property will be scrolled on the top of the screen while the value for projectURL JSON property will be rendered as a QR Code in the info window. It is better provide a short URL for projectURL so the resulting QR Code has more error correction.

🚫 LIMITATIONS:

• SD Library limits file names (including path) to 32 chars, M5StackSAM has a slightly higher limit.
• Short file names may be treated as 8.3 (e.g 2048.bin becomes 2048.BIN).
• FAT specifications prevent having more than 512 files on the SD Card, but this menu is limited to 256 Items anyway.
• Long file names will eventually get covered by the jpg image, better stay under 8 chars (not including the extension).

🔘 OPTIONAL:

The default binary name to be loaded can be changed at compilation time by customizing the MENU_BIN constant:

#define MENU_BIN "/my_custom_menu.bin"
#include "M5StackUpdater.h"

The M5Stack automatically detects and uses the M5Stack-Faces addon (gameboy only).

The JoyPSP Controls for M5Stack SD Menu necessary code is now disabled in the menu example but the code stays here and can be used as a boilerplate for any other two-wires input device.

The JoyPSP code is optimized for a 4 Wires PSP JoyPad breakout on Pins 35 and 36, but it shouldn't be a problem to adapt/extend to other analog joystick models.

⚠️ KNOWN ISSUES

qrcode.h not found, or duplicate declarations errors can occur during compilation of M5Stack-SD-Menu.ino.

Reason: M5Stack recently embedded the qrcode.h library into their own core. If your version of M5stack core is older than 0.1.8, Arduino IDE will probably complain.

Solution 1: choose between one of the two includes in M5Stack-SD-Menu.ino:

#include "qrcode.h" ← use this with M5Stack-Core 0.1.6 and older, comment out the other one

or

#include "utilities/qrcode.h ← use this with M5Stack-Core 0.1.7, comment out the other one

Solution 2: in your library manager, downgrade the M5Stack-SD-Menu to an earlier version (0.0.1) until you update M5Stack library

Solution 3: upgrade your M5Stack core version to 0.1.8

Compilation #pragma warnings/errors in the Arduino IDE can be solved by setting the debug level to default in the Arduino preferences window. See #3

vMicro: currently can't compile at all, see #5. Looking for a solution that works with both vMicro and Arduino IDE.

🛣 ROADMAP:

Not defined yet, but looking at how fast this library landed in platform.io, there's a possibility it will soon exist in different flavours (i.e. as an ESP-IDF component) or with more features. Contributors welcome!

#️⃣ REFERENCES:

🎬	Video demonstration	https://youtu.be/myQfeYxyc3o
🎬	Video demo of Pacman + sound	Source
🎬	Video demo of NyanCat	Source
🎓	Macsbug's article on M5Stack SD-Updater	🇯🇵 🇬🇧 (google translate)

🙏 CREDITS:

👍	M5Stack	M5Stack	https://github.com/m5stack/M5Stack
👍	M5StackSam	Tom Such	https://github.com/tomsuch/M5StackSAM
👍	ArduinoJSON	Benoît Blanchon	https://github.com/bblanchon/ArduinoJson/
👍	QRCode	Richard Moore	https://github.com/ricmoo/qrcode
👍	@Reaper7	Reaper7	https://github.com/reaper7
👍	@PartsandCircuits	PartsandCircuits	https://github.com/PartsandCircuits
👍	@lovyan03	らびやん	https://github.com/lovyan03
👍	@matsumo	Matsumo	https://github.com/matsumo