Bad news : finding out how to program the M5Core is really, really unintuitive.
Good news : this page will clarify things to the point a baby will be able to do it.
But first, a quick note : if you ever wonder how to turn off your M5Core, here’s how :
· Make sure the USB cable is unplugged
· Double-click the power button
Like I said, not very intuitive.
1.1. Download Stuff
The M5Stack requires installing on your PC at least two pieces of software :
· The CP2104 driver for the USB-UART chip it uses to communicate with the M5Core
· M5Burner : the tool for burning and configuring firmware on the M5Core
Then, depending on your preference, there’s a choice of online and offline development environments.
To get this software, go to the official site : https://m5stack.com/pages/download
Installing the CP2104 driver is both easy and mandatory. If done correctly, two things will happen when you connect your M5Core to your PC using a USB cable :
· The M5Core will turn on
· A new COM port will appear on your PC
1.2. The M5Burner
This program requires no installation, just decompress the ZIP file into its own folder and run the executable. Note that if you’re using the offline (“desktop”) IDE, M5Burner is integrated into it.
M5Burner essentially a firmware-flashing tool. You will need it in order to update your M5Core’s firmware and/or change firmware. It supports other firmware besides the in-house UIFlow (which is based on MicroPython). It also supports other hardware devices. Maybe I’ll look into those in the future.
Its most important feature, however, is firmware configuration : you will need almost any time you’re developing with M5Stack products, as it allows you to control how the device boots and what it runs when it does.
Note that M5Burner appears capable of working “over the air”, but this requires you to setup the M5Core as a WiFi access point and then connect your PC to it, which is likely to prove more cumbersome than plugging in a USB cable in most cases.
The user interface looks like an “app store” that lets you choose between different firmware :
Let’s stick with UIFlow, since it says “official” next to its name. There are three buttons :
· “Download”, which morphs into “Remove” once you’ve used it to download a firmware version locally.
· “Burn”, which should be in the middle since it’s the next logical step. This flashes the M5Core with the firmware.
· “Configuration”, which, despite being in the middle, can only be done after having burned the firmware. This lets you configure the way the firmware starts on your device.
That configuration feature is actually a very important part of working with the M5Stack devices, and as a result you are likely to keep M5Burner open any time you’re programming.
1.3. UIFlow Development Tools
This name UIFlow covers a few things. It’s the name of both the official firmware for the M5Stack products and that of the official development tools associated with the firmware.
Those development tools are :
· A web-based IDE you can run in your browser (https://flow.m5stack.com/)
· An offline IDE you can download where you got M5Burner from
A very nice thing about those tools is that the web-based and offline versions have the same user interface. You will not need to learn how to use two different tools. Much appreciated !
In order to use UIFlow it’s important to understand a few things :
· The web-based IDE (a.k.a. “M5Flow”) can talk to the M5Core only through WiFi.
· The offline IDE (a.k.a. “UIFlow Desktop IDE”) can talk to the M5Core only through USB.
Therefore, you don’t get to choose which type of IDE you’re using : if you want to program wirelessly, you must use the online IDE, which means both your PC and your M5Core must be connected to the internet. If you want to program offline, you can only do so over a USB cable. Period.
Now that this bitter pill has been swallowed, let’s look at UIFlow firmware configuration.
1.4. UIFlow firmware configuration
UIFlow is essentially a miniature operating system, complete with a boot sequence. Exactly what happens during that boot sequence can be configured using M5Burner.
Note : the following information pertains to UIFlow version 1.6.0 and may not be accurate for later versions.
The UIFlow configuration dialog box in M5Burner looks like this :
The API key is a unique ID for this device. This isn’t a hardware address like a MAC address, you can generate a new API key if you need to. It’s used to let the web-based UIFlow IDE find your device and connect to it. This doesn’t seem very secure at all… best keep yours a secret !
The Start Mode is either “Internet Mode”, “USB Mode” or “App Mode” :
· “App Mode” launches the last Python program you ran on the device. Note that the M5Core has a small file system that can hold several programs.
· “USB Mode” is for programming the device through USB. It only works with the offline (“desktop”) version of the UIFlow IDE.
· “Internet Mode” is for programming the device through the web-based UIFlow IDE. This obviously requires that your M5Core be connected to the internet via WiFi.
Quick Start enables or disables a one-second “boot screen” that appears whenever the M5Core resets. The boot screen allows you to interrupt the boot process and enter system menus using the three buttons under the display. Those menus provide functions similar to the M5Burner’s configuration dialog box, so you may want to disable the boot screen when shipping code to people you don’t trust. Such as young children and self-proclaimed experts. You can always claim you’re only doing it to make the device boot faster by one second. You can only disable this mode through M5Burner.
Server lets you select which M5Stack server you will be using to connect to your device when using the “Internet Mode”. The URL should be the same as the one in your browser when running the online UIFlow IDE.
Wifi lets you enter the SSID and password for the WiFi network your device will belong to. What’s important to understand is that this network must have internet access for “Internet Mode” to work. Also, it doesn’t need to be the same network your PC is connected to : you will be programming through the internet, not through your local network.
If you provide WiFi credentials to UIFlow, the M5Core will attempt to connect to WiFi every time it starts. You’ll see how well that works on its little display.
Now let’s look at the online IDE.
1.5. The Online UIFlow IDE
Since the M5Stack and ESP32 are decidedly targeting IoT application, it’s not surprising that there’s an online, web-based development environment for the M5Stack. It’s called M5Flow and it lives at https://flow.m5stack.com/.
Note that in order to use this online IDE you will first need to use M5Burner to configure your device’s firmware into “Internet Mode” and setup its WiFi. When it reboots, it’ll show you an API key. Lo and behold, that’s also the very first thing the online IDE will ask you :
The reason is simple : the online IDE will flash your code to your device over the internet. It needs to know which device is yours, so as not to run your code on the device of a total stranger. The API key is what makes this possible, while keeping it simple… and very unsecure. But hey, this is only while you’re developing. Once you release your code, you will switch your firmware to “App Mode” and the online IDE will not be able to talk to your device anymore. Or so we’d expect.
Once you click “OK”, you will get to the IDE proper. It should tell you right away if it managed to connect to your device or not. Since the online and offline IDE have the same user interface, I won’t go any further and move on to the offline IDE.
1.6. The Offline (Desktop) IDE
As with M5Builder, the UIFlow Desktop IDE requires no installation : simply decompress the ZIP file into its own folder and launch the executable. This is what you’ll see :
It’s simplistic but does the job. Basically, you’ve got your GUI design tool to the left and your code editor to the right. You can code in Python or in Blockly, with instantaneous translation between both : just hit the button for your desired language at the top of the interface.
Bottom left is your device connection status. Since this is the offline IDE, it shows a COM port. On the web-based IDE it will show an API key instead. Both identify the device the IDE is talking to, so make sure it’s the right one and that it says “Connected” in green next to it.
Top right are some useful icon. There’s the traditional triangular “Run” button, of course. You know what it does. There’s also a DEMO button, which allows you to load all sorts of demo programs. Those demos cover all the peripheral modules sold by M5Stack, saving you a lot of time when you want to test those shiny toys you just received in the mail.
For a quick spin, click the DEMO button and select the Timer demo. Mainly because it requires no external hardware. You should see this :
Or, if you switch to Python :
You can try running it just to make sure everything works, but other than that it’s not going to blow your mind. The mind-blowing stuff will require more effort.