bmorcelli/Launcher: an ESP32 firmware loader designed to stay out of the way

An installed program takes the boot, and the loader only appears on a keypress

The way this project works is easier to understand from the usage notes than from the description. You power the device on and a Launcher start screen appears, and pressing the select or enter button takes you into the loader. From there you choose OTA to install new binaries from online services, either M5Burner or a GitHub link. After the installation, the README says, when you turn on the device the installed program will launch if you don't press anything. That single sentence is the design. The loader is not a shell you use daily, it is a bootloader with a user interface that gets out of the way the moment you have something else to run, and the only thing standing between you and a bricked device is a button press at power on. For a hardware family as fragmented as ESP32 development boards, where the same chip appears in a M5Stack, a Lilygo watch, a Seeed reTerminal, a Waveshare watch, a CYD board and a Marauder, that is the feature. A single installed application can be replaced with a completely different one, from a different project, on hardware that was never designed to run more than one. The device list is the reason the project exists, and the consequence is that a device becomes a general purpose platform rather than a fixed product.

Three ways onto the device, and a file name that has to match your board

There are three documented routes to get the loader onto a board, and the README names them without expanding any of them into commands. The first is a web page, the Launcher Flasher hosted with the project documentation, which is the path most people take and the only one that needs nothing but a browser. The second is M5Burner, the flashing tool from the same hardware family, for the M5 boards the project is named after. The third is the route for everyone else: download the binary file for your device from the releases, and flash it with a browser based flasher or with esptool.py. That route is worth reading twice because of one detail. The file is named after the device, with the device name substituted into a fixed pattern, so picking the wrong one is the default failure mode for someone who does not know which board they have, and the release page rather than the README is where the mapping lives. The README gives no command line, no flash arguments and no baud rate, so this article cannot walk you through the third route, and the honest position is that the tool names are all you get from this page. What is documented is the outcome to expect: a start screen that responds to the select or enter key, and from there a menu whose options are the same five across every port.

The SD card rules, and where the current support is wider than the advice

An SD card is optional, and the README says having one gives a better experience without making it a requirement, and it even links a printable hat for one of the smaller boards. If you do use one, the requirements are stated as a troubleshooting list, which reads like a support article because that is what it is. The card must be SDHC rather than SDXC, which rules out the 64 gigabyte and larger cards most people now buy. The maximum given is 32 gigabytes, and the author's own choice is 8 or 16. It has to be formatted as FAT32, with Rufus named as the tool. And the partition scheme has to be MBR rather than GPT, which is the setting people miss when they format a card with a current default. Then there is a sentence that updates all of it. exFAT and larger cards have been supported since release 2.8.0, and smaller ones are still recommended. So the troubleshooting list describes the safe subset rather than the current support, and a reader who follows it will never hit a card size problem, while a reader who assumes SDXC is still unsupported will buy the wrong card. The card's role in the system is broader than storage. Its management menu creates, deletes, renames and copies folders and files, and it installs binaries from it, so the card is both an install source and a persistent home for the things the device runs.

The web interface edits NVS and installs binaries over the network

The web user interface is the feature that changes the security picture, and it is worth describing exactly rather than in general terms. It manages the files on the SD card, and it installs binaries wirelessly using the OTA option, and it edits text files, and it deploys installations from the file list. The one that deserves attention is the NVS editing, described as editing non volatile storage information covering UiFlow2 data, Launcher settings and others. NVS is the key value store the ESP32 firmware ecosystem uses for configuration, so this is not a settings screen for the loader alone, it is a way to read and rewrite the stored state of other applications running on the same device, over a browser, with no cable attached. Combined with wireless binary installation, the consequence is straightforward. A device with the loader on it and the web interface enabled can be reflash and have its stored data rewritten by anything that can reach it on the network. Neither the OTA installation path nor the web interface is documented as verifying anything about the binary it fetches, and the OTA option takes an M5Burner reference or a GitHub link, so the file that ends up running on the device is chosen by whoever chose the link. That is a reasonable design for a development board on a bench and a poor one for a device on a shared or guest network, and the honest way to use it is to enable the wireless install path when you need it rather than leaving it on.

A partition manager with a flash layout, and the buttons that exist as an undo

Two menu entries deal with the flash layout, and between them they give you a partition manager on a device that has no operating system to speak of. The partition manager views the current scheme, creates partitions, deletes them, formats them, resizes them, and backs up and restores the data partitions, meaning the SPIFFS or the FAT partition. The configuration menu overlaps with it, and holds a change partition scheme option described as allowing larger applications or UiFlow2 to be installed, a list of the partitions, an option to clear the FAT partition, and a pair of entries for saving a copy of the SPIFFS partition and restoring it later. Read those two features together and the intent is visible. A wrong partition scheme is one of the few mistakes on an ESP32 board that produces a device that will not boot, and the save and restore entries exist because the author has hit that. That makes the save button the most important control in the entire interface and the easiest to skip, since it appears in a list between brightness and rotation. The sensible discipline is to save the SPIFFS copy before touching anything in either menu, and to treat a partition scheme change as a firmware operation rather than a settings operation, because it is one. The remaining configuration entries are ordinary, covering charge mode, brightness, dim time, interface colour, rotation, and a choice between showing all files and only binary files.

The stealth options, and the warning that comes attached to them

The most interesting entries in the unreleased changelog are not ports, they are two options that make the loader harder to summon. The first disables starting Launcher from deep sleep, and the reason given is that some e ink firmwares use aggressive deep sleep controls to save energy, which by default triggered the loader's boot screen and added delay to a device's own recovery. The second starts Launcher when a button is pressed during a restart, meaning you will see the boot screen only if you press that button while powering on, restarting, or recovering from deep sleep. Together the two options are described in the changelog as making Launcher stealthy, appearing only when you want it. That is a genuinely good fix for the stated problem, and it introduces the project's clearest risk, because the changelog says to use it with care and warns that on devices with an exposed reset button, getting back to Launcher can become impossible on some devices. The logic is not hard to follow. A device that boots straight into the installed firmware, whose deep sleep does not surface the loader, and whose only recovery path is a button the configuration did not map, is a device with no documented route back to the thing that installed its firmware. Two constraints are also stated. The boot button itself cannot be configured for this function, and the option is only available on devices with GPIO driven buttons, so a device with only a touchscreen, a keyboard or an encoder does not get the option at all. Which devices are affected is not enumerated, so the check has to be made per board.

Board bring-up is the maintenance model, and main is ahead of the releases

The changelog is the clearest statement of what maintaining this project actually means, and it is a list of ports and per board fixes rather than features. The unreleased section adds support for several SeeedStudio boards including two XIAO variants ported on what the entry calls a headless environment, a reTerminal with an eight inch display, a monochrome e paper reTerminal and a SenseCAP indicator, plus a Waveshare AMOLED touch watch contributed by someone else, and a beta entry for an XTeink device with a validated display controller. Below that sit fixes for two Lilygo touchscreens, a random crash in the OTA function on one M5Stack tablet, and a changed display backend for another. Each of those lines is a board, a display driver, a touch driver or a boot interaction, which means the cost of supporting a new device is a port rather than a patch, and the cost of a firmware framework change is a round of fixes across all of them. Two details from the same page deserve attention. The version documented at the top of the changelog is ahead of the newest published release, so the source on the main branch describes work that is not yet in a release binary. And the known issues section states that UiFlow 1 does not work with the loader because it uses an older MicroPython distribution built on an older ESP-IDF distribution, described as containing a number of things the author could not work out, which is a candid admission of a compatibility wall. The to-do list is two items long, a user interface rewrite marked with a question mark and a move to the ESP-IDF platform, which tells you the project is still on the Arduino framework and knows it. The licence is MIT, the build is configured through a platformio file with a directory of board definitions, and the deeper explanation of how any of this works lives in the project wiki rather than in the README.

Editorial conclusion

Launcher is worth installing on a development board you own and intend to keep re-flashing, because it turns a laptop with a USB cable into a menu on the device and removes the cable from most of the loop. The two features to read twice before using it are the ones that reach furthest. The web interface edits the device NVS data, which holds other applications' stored settings, and it installs binaries over the network, so on an untrusted network anyone who can reach the device can replace its firmware, and the OTA path takes a link rather than a verified artefact with no checksum or signature step documented. Second, the stealth options can leave a device with no way back, and the README's own warning about exposed reset buttons is not a formality. Two things to verify first. Save the SPIFFS copy from the configuration menu before you change a partition scheme or clear the FAT partition, because the restore buttons are the only undo described. And pick the binary yourself rather than from the catalogue page, since the trust decision is entirely yours once the cable is gone.

Frequently asked questions

Official sources

1. bmorcelli/Launcher on GitHub
2. License: MIT
3. Project website
4. README
5. Releases