DOCSEARCHbyAlgolia
Submit Docs

Launcher for ESP32

repository·main·Indexed 23 days ago

https://github.com/bmorcelli/launcher

An application launcher for ESP32-based devices such as M5Stack, Lilygo, and Marauder. It provides a centralized interface to manage, update, and launch binaries via OTA, SD cards, or a Web User Interface (WUI). Key features include a Partition Manager (PMan), wireless file management, and a Node.js-based WebUI Dev Server for testing the interface without hardware.

Tokens
5.8K
Snippets
9
Records
40
Agent score
84%

What's inside Launcher

  1. Launcher Feature Overview

    main

    Launcher provides several functional modules for managing your ESP32 device:

    OTA (Over-The-Air Update)

    • Install binaries from online repositories (M5Burner or GitHub links) without a USB cable.
    • Use the WUI (Web User Interface) to install binaries from your computer or smartphone.
    • Install binaries directly from your SD card.

    SD (SD Card Management)

    • File operations: Create folders, delete files/folders, rename files, and copy/paste files.
    • Install binaries directly from the SD card.

    WUI (Web User Interface)

    • Manage files on the SD Card wirelessly.
    • Install binaries wirelessly via the OTA option.
    • Edit text files and NVS information (e.g., UiFlow2 data, Launcher settings).
    • Deploy installations from the file list.

    CFG (Configurations/Customization)

    • Adjust device settings: Charge Mode, Brightness, Dim time, UI color, and Rotation.
    • Manage SPIFFS: Choose whether to ask for SPIFFS installation (primarily for Orca One).
    • File visibility: Toggle between seeing 'All files' or 'Only Bins' (default).
    • Partition management: Change partition schemes, list partitions, clear the FAT partition, and Save/Restore SPIFFS.

    PMan (Partition Manager)

    • View, create, delete, format, and resize partitions.
    • Back up and restore data partitions (SPIFFS or FAT).

  2. Manage SD Card and Files via WebUI

    main

    The Launcher WebUI provides a wireless interface to manage your device's storage and firmware.

    Capabilities:

    • File Management: Create, delete, rename, copy, paste, and move files and folders on the SD card.
    • Firmware Installation: Install new binaries wirelessly.
    • Partition Management: View partitioning information and manage partitions.
    • Configuration Editing: Edit text files and NVS (Non-Volatile Storage) fields saved in memory.
    • Bulk Uploads: Supports multi-file upload via drag-and-drop or folder selection.

  3. Hardware limitations for Lilygo T-HMI

    main

    The Lilygo T-HMI board cannot use the SDCard Sniffer feature because the SDCard CS Pin is physically grounded, making the bus permanently unavailable.

    To use SPI devices (like CC1101 or NRF24), you must solder the MISO, MOSI, and SCK pins to the touchscreen SPI line. Note that this may cause navigation issues on the touchscreen and requires testing.

  4. Manage Firmware via OTA (Over-The-Air)

    main

    Launcher includes an OTA feature that allows you to list and install programs available in the M5Burner database directly from the internet.

    Key Features:

    • Firmware List: Browse available firmware, which can be filtered and ordered (e.g., by 'Latest update').
    • Multi-part Downloads: For firmware composed of multiple files (e.g., bootloader.bin, partitions.bin, firmware.bin, and data.bin), Launcher fetches them individually and merges them at runtime into a single file ready for flashing.
    • Update All: If you have previously downloaded firmware stored at {dwn_path}/downloaded.json, you can use the [Update All] option to check for new versions and download all updates directly to your SD card.

  5. Simulate the OTA update flow

    main

    The backend mock supports the new firmware OTA flow. When a manifest is provided, the server validates partition ranges, ensures exactly one app type partition exists, and orders parts by sourceOffset to simulate sequential writing of the uploaded file.

    The OTA sequence:

    1. GET /OTA?update=1: Enter update mode.
    2. POST /OTA: Send command=0, size, and the manifest.
    3. POST /OTAFILE: Upload the complete binary.

    If no manifest is provided, the server falls back to a simulated legacy behavior.

  6. Understand simulated NVS and Partition Manager (PMan) behavior

    main

    NVS (Non-Volatile Storage)

    NVS data is persisted in nvs_mock.json in the server directory. It persists across restarts. The key launcher/token is protected and cannot be exposed or edited, mimicking actual firmware behavior.

    Partition Manager (PMan)

    The PMan simulates the partition table model (src/partition_table_model.cpp).

    • Persistence: The 'flashed' state is stored in partitions_mock.json.
    • Pending Changes: Edits like resize, create, or delete are held in memory as "pending changes". You must call action=apply to persist these to partitions_mock.json. Use action=discard to cancel them.
    • Formatting: action=format is only permitted when there are no pending edits.
    • Backup/Restore: action=backup and action=restore are simulated; they do not copy real data but manage fictitious file paths in memory via a label to test the UI flow.
    • Protection: System partitions (nvs, otadata), the running partition, and factory/test partitions are protected from modification, following firmware rules.

  7. Backup and Restore Data Partitions

    main

    Launcher includes a backup system for data partitions (like SPIFFS or FAT).

    • Backup: Saves the relationship between a backup and its corresponding binary in /bkp/backupData.json. This requires an SD card.
    • Restore: When reinstalling firmware, the system can restore the associated data. The app icon and PMan (Partition Manager) will display the status of the backup data.
    • Merging: During firmware installation, you may be prompted to merge existing SPIFFS/FAT data into the chosen binary by selecting SPIFFS Yes during the install process.

  8. Cardputer ADV Hardware Specifications

    main

    The Cardputer ADV differs from the original Cardputer in its keyboard implementation. It uses an I2C-based controller rather than a direct GPIO matrix.

    FeatureCardputer ADV Specification
    Keyboard ControllerTCA8418 I2C controller
    I2C Address0x34
    SDA PinGPIO8
    SCL PinGPIO9
    Interrupt PinGPIO11
    Matrix Size7 rows × 8 columns
    Key Detection100ms polling interval

    Detected I2C Devices:

    • 0x18: Likely accelerometer/IMU
    • 0x34: TCA8418 keyboard controller
    • 0x69: Likely additional sensor

  9. How to use Launcher

    main

    Once installed, follow these steps to operate the application:

    1. Turn on your device.
    2. On the Launcher start screen, press the M5/Sel (Enter) button to enter the Launcher interface.
    3. To install new binaries wirelessly, choose the OTA option. This allows you to install binaries from online services (M5Burner or GitHub links).
    4. Automatic Launching: If you do not press any buttons after an installation, the device will automatically launch the newly installed program upon the next power cycle.

  10. Install and run the Launcher WebUI Dev Server

    main

    The Launcher WebUI Dev Server is a Node.js backend that replicates the behavior of src/webInterface.cpp. It allows you to test the web interface without requiring ESP32 hardware by using a local directory as a simulated SD card.

    Requirements

    • Node.js 16+
    • No external dependencies required

    Running the server

    You must provide a <root-folder> which will be treated as the SD card. All file operations (list, download, upload, delete) will occur within this directory.

    Using node directly:

    node server.js <root-folder>

    Using npm (from the backend/ directory):

    npm start -- <root-folder>

    Configuring Port and Credentials: Use environment variables to set the PORT, WUI_USR (username), and WUI_PWD (password).

    PORT=3000 WUI_USR=admin WUI_PWD=minhasenha node server.js C:\pasta

    Once started, access the interface at http://localhost:8080. The default login is admin / admin.

    node server.js C:\Users\bmorc\Downloads

  11. Structure of a new board definition

    main

    To add support for a new hardware board in Launcher, you must create a specific directory structure and provide several files. Replace [board] with your specific board name throughout the following paths.

    Required files for a complete board implementation:

    • boards/pinouts/[board].h: Defines flags and pinouts for the board.
    • boards/[board]/interface.cpp: Contains board-specific setup code.
    • boards/_JsonFiles/[board].json: The board configuration file.
    • boards/[board]/[board].ini: The PlatformIO configuration for the device.
    boards
├── _JsonFiles
│   └── [board].json
├── [board]
│   ├── interface.cpp
│   └── [board].ini
└── pinouts
    ├── pins_arduino.h
    └── [board].h

  12. Install Launcher on ESP32 devices

    main

    You can install Launcher on M5Stack, Lilygo, CYD, Marauder, and other ESP32 devices using one of the following three methods:

    1. Launcher Flasher: Use the web-based Launcher Flasher.
    2. M5Burner: Use the standard M5Burner application.
    3. Manual Flash: Download the specific .bin file for your device from the GitHub Releases page and flash it using web.esphome.io or esptool.py. The file follows the naming convention Launcher-{YourDevice}.bin.