Skip to content

Functionalities explained

Jump to bottom
Pirata edited this page Aug 21, 2026 · 3 revisions

Launcher features and menus

Launcher opens to a main menu. The exact layout changes by screen size and device capabilities, but the current menu can include SD, OTA, WUI, USB, PMan, CFG, and installed app shortcuts.

Boot screen and fastboot

Before the main menu, Launcher shows a boot screen. Pressing the select/enter button opens Launcher; doing nothing boots the selected app when Boot to Launcher is disabled.

Installed apps are also drawn as cards on the boot screen:

  • On touchscreen devices, tapping a card boots that app immediately.
  • On keyboard devices, the first ten apps get a digit shortcut, shown in the top-left corner of each card. Pressing 1..9 or 0 boots that slot.

This is the fastest path to a firmware you use often, since it skips the main menu entirely.

Shortcuts

Devices with a keyboard can bind an SD card binary to a key.

  • Bind it from the file browser: select a .bin and choose Bind to key.
  • Review or remove bindings in CFG > Manage shortcuts, which lists each bound key with a Remove action and offers Reset All.
  • From the main menu, pressing a bound key installs and runs that binary directly.

Bindings are stored with the rest of the Launcher configuration, so they survive reboots.

SD

SD opens the SD card browser.

From the file browser you can:

  • enter folders
  • install .bin firmware files
  • bind a .bin to a keyboard key, on devices with a keyboard
  • create folders
  • rename files and folders
  • copy files
  • paste copied files into another folder
  • delete files and folders

The file list can show only binaries or all files, depending on the See All Files setting. Dotfiles can also be hidden or shown.

OTA

OTA opens the online installer. Launcher connects to WiFi and queries LauncherHub for firmware metadata.

If Favorites are configured, or if you have previously downloaded firmware to the SD card, the OTA entry first shows a chooser with:

  • OTA List — the normal LauncherHub catalog
  • Favorite List — your saved LauncherHub IDs and direct links
  • Check for Updates — only shown when downloaded firmware is tracked on the SD card

The OTA list supports:

  • firmware list browsing
  • pagination
  • ordering by downloads, name, or latest update
  • starred firmware filtering
  • text search
  • version selection
  • direct online install
  • download to SD card
  • adding firmware to Favorites

Checking for updates

Every firmware you download to the SD card is recorded in downloaded.json, inside your downloads folder. Check for Updates sends that list to LauncherHub, which answers with the entries that have a newer version available. From the resulting list you can update a single firmware or pick [Update All] to download every new file straight to the SD card.

Multi-part firmware

Some LauncherHub entries publish firmware as several files — bootloader.bin, partitions.bin, firmware.bin, and data.bin. Launcher fetches each part in sequence and merges them into a single file on the SD card, which is then flashed like any other merged binary. This happens automatically; there is nothing to configure.

WUI

WUI starts the Web User Interface. Connect with a browser to the IP address shown on the device.

The WebUI menu has Config, OTA, Files, Partitions, and a link to the online firmware list.

Files

  • browse SD card files
  • upload one or more files
  • upload folders through supported browsers
  • download files from the SD card
  • delete files and folders
  • create folders
  • rename files and folders
  • install a firmware file already on the SD card

Uploads are queued and sent strictly one at a time. Sending several files in parallel could drop connections on the device's small HTTP server, so the queue is serial by design — large batches and large individual files take longer, but they complete.

OTA

  • upload and install firmware directly from the computer or phone
  • analyze the selected binary before flashing
  • split merged firmware when app and SPIFFS sections are detected

Partitions

The WebUI exposes the same partition operations as PMan:

  • list the current partition table
  • create a partition
  • resize a partition
  • delete a partition
  • format a partition
  • back up a data partition to the SD card
  • restore a data partition from a backup
  • apply or discard the pending changes

Config

  • Reboot
  • SD Pins — configure SD card pins, mainly for headless builds
  • WiFi — set the network credentials
  • User/Pass — change the WebUI login
  • NVS — open the NVS editor
  • Logout

Editors

The text editor handles text-like files such as .txt, .ini, .conf, .c, .cpp, .h, .hpp, .js, .css, .htm, and .html.

The NVS editor shows and edits stored fields, except protected internal keys. Blob and unsupported key types are shown read-only instead of being corrupted on save. The editor also has an Erase BLE Bonds button for clearing stored Bluetooth pairings.

Default WebUI credentials are admin / launcher.

USB

USB appears on devices with USB OTG support. It exposes the SD card as a USB mass storage device, so the SD card can be managed from a computer without removing it from the device.

The option requires a mounted SD card. If no SD card is present, Launcher will ask you to insert one.

PMan

PMan is the Partition Manager.

Use it to inspect and modify the device partition table. It shows system, app, data, and free regions. Protected partitions are marked with *.

For existing partitions, available actions can include:

  • Details
  • Associate to Bin — link a data partition to the firmware that owns it, so backups and restores follow that app
  • Backup
  • Restore data
  • Edit Size
  • Remove
  • Format

For free space, available actions can include:

  • Add OTA
  • Add FAT
  • Add SPIFFS

The menu also offers Erase BLE Bonds. With developer mode enabled, it adds Wipe Flash memory and Format NVS Partition. Both are destructive and ask for confirmation first.

Changes are staged first. Use Apply Changes to write the new table or Discard Changes to reload the current table.

Partition changes can erase or move data. Back up important FAT or SPIFFS partitions before editing layouts.

CFG

CFG opens Launcher settings.

Current settings can include:

  • Charge Mode
  • Brightness
  • Dim time
  • UI Color
  • Orientation
  • See All Files
  • Show Dotfiles
  • Auto Backup
  • Boot to Launcher
  • Ask to copy SPIFFS
  • Auto connect to known Wifi
  • Partition Manager
  • Manage shortcuts, on devices with a keyboard
  • Boot Animation, when developer mode is enabled
  • Deactivate Dev, when developer mode is enabled
  • Calibrate Touch, on resistive touch devices
  • Start CardKb, on devices with CardKB2 support
  • Retry WiFi Module, when the WiFi co-processor failed to start
  • Reset Configs/Wifi, when developer mode is enabled
  • Restart
  • Turn-off, on supported devices

Boot to Launcher controls whether the device always stays in Launcher or automatically boots an installed app. The label is shown as a checkbox-style toggle.

Ask to copy SPIFFS controls whether Launcher asks before installing SPIFFS/LittleFS data when the firmware includes or declares one.

Auto Backup controls whether Launcher offers to back up an app's data partition before removing or overwriting it. When enabled, deleting an app that owns data offers Backup Data partition, Remove Without Backup, or Cancel.

Auto connect to known Wifi controls whether Launcher silently connects to a saved network when it needs one. Turn it off if you would rather pick the network every time.

Retry WiFi Module only appears when the WiFi co-processor was latched off at boot. Choosing it clears the guard and reboots so the bring-up runs again.

Installed app shortcuts

Installed firmware can appear directly on the main menu. Selecting an installed app opens actions:

  • Launch the app
  • Rename App
  • Backup Data, when the app has linked data partitions
  • Delete the app
  • Cancel

Backup Data lists each data partition the app owns, marked [Backed up] or [No backup], and lets you back up or restore each one.

Deleting an app removes its OTA app partition entry. If the app has linked FAT data partitions, Launcher can back them up first, then remove them, compact the partition table, and restart.

Data backups

Backups live on the SD card under /bkp, in folders named {appNum}-{appName} so they stay readable. The link between a backup and the firmware that produced it is recorded in /bkp/backupData.json, which is what lets Launcher offer the right backup back to you when you reinstall that firmware. App icons and PMan show whether backup data exists.

This feature needs an SD card.

Serial interface

Launcher accepts commands over the serial port. Type help for the list. It covers WiFi setup, partition editing, navigation injection, touch calibration, and SDIO pin configuration, which makes it the practical way to configure devices without a keyboard or touchscreen, such as the StickC Plus 2.

See Serial interface for the full command reference.

Keyboards

Beyond built-in keyboards, Launcher supports M5 Grove I2C keyboards on Port A: CardKB 1.1, CardKB2, and the Tab5 keyboard. Supported hosts include StickC, StickC Plus 1.1, StickC Plus 2, StickS3, Tab5, CoreS3, Core2, and Core. On devices where the Grove 5V rail is switchable, Launcher keeps it powered from boot so the keyboard can be detected; CFG > Start CardKb re-runs detection if you plug one in later.

On two-button devices, navigation uses long presses: front button short press moves to the next item and long press selects; side button short press moves to the previous item and long press escapes. On a keyboard, holding Escape flips movement from Left/Up to Right/Down.

Headless builds

Headless ESP32 and ESP32-S3 builds are intended for devices without the normal display/button UI. SD card pins can be configured and stored — from the WebUI Config > SD Pins page, or over serial — and the WebUI is the primary management path.

SD card notes

For the best compatibility:

  • use SDHC, not SDXC
  • use 32 GB or smaller cards
  • format as FAT32
  • use MBR partitioning, not GPT
  • prefer 8 GB or 16 GB cards when possible

Some devices share SPI between the display, touch controller, LoRa hardware, and SD card. Launcher includes board-specific setup to reduce bus conflicts, but SD card quality and formatting still matter.

Clone this wiki locally