A collection of M5CardputerZero applications developed with the M5Stack_Linux_Libs SDK. This project demonstrates how to build graphical UI applications with LVGL 9.5 on the M5CardputerZero (AArch64 Linux) device.
The repository contains two main projects and several example/helper projects:
- HelloWorld - A basic user demo that shows a status bar and simple UI
- APPLaunch - An application launcher with rich features such as multi-app navigation, LoRa communication, and audio playback
The UI is generated by SquareLine Studio 1.5.0 and supports two display backends: SDL2 simulation mode for local debugging and Linux Framebuffer mode for running on the device.
launcher/
├── SDK/ # M5Stack_Linux_Libs SDK (git submodule)
│ ├── components/ # Component libraries (lvgl_component, DeviceDriver, etc.)
│ ├── examples/ # SDK examples
│ └── tools/ # Build toolchain scripts (SCons)
├── projects/
│ ├── UserDemo/ # Basic user demo project
│ ├── APPLaunch/ # Application launcher project (core)
│ │ ├── SConstruct # Top-level project build script
│ │ ├── config_defaults.mk # Default build config (Linux Framebuffer mode)
│ │ ├── darwin_config_defaults.mk # macOS build config
│ │ ├── win_x86_sdl2_config_defaults.mk # Windows SDL2 simulator config
│ │ ├── win_x86_cross_config_defaults.mk # Windows-to-device cross config
│ │ ├── setup.ini # SSH deployment config
│ │ └── main/ # Main application source
│ │ ├── SConstruct # Component build script
│ │ ├── src/
│ │ │ └── main.cpp # Program entry point
│ │ └── ui/ # UI code
│ │ ├── ui.h / ui.cpp # UI initialization
│ │ ├── launch.cpp / launch.h # App list and launch logic
│ │ ├── app_registry.* # Built-in app enable/disable registry
│ │ ├── ui_launch_page.* # Home carousel UI
│ │ ├── launcher_ui_runtime.* # LVGL runtime/home bootstrap
│ │ ├── animation/ # Animation effects
│ │ └── page_app/ # Built-in app pages
│ ├── Calculator/ # Calculator
│ ├── AppStore/ # App store
│ └── HelloWorld/ # Hello World example
├── ext_components/ # External components (Miniaudio, RadioLib, etc.)
├── docs/ # Project documentation
├── scripts/ # Repository helper tools
├── README.md
├── README_ZH.md
└── README_JA.md
- Graphical UI based on LVGL 9.5
- Supports two display backends:
- SDL2: PC-side simulation and debugging (default build mode)
- Linux Framebuffer (ST7789V): Runs on the M5CardputerZero device
- evdev keyboard/touch input support (device side)
- SCons + Kconfig build system, with flexible configuration through
scons menuconfig
- Application launcher UI with multi-app navigation (carousel page switching)
- Built-in app pages: CLI/ST terminal, Game, Setting, Compass, IP Panel, File, SSH, Mesh, Rec, Camera, LoRa, and Tank Battle, plus command/external entries such as Python, Store, and Math
- LoRa communication (based on RadioLib SX1262)
- Audio playback (based on Miniaudio)
- Battery status monitoring and display
- Global shortcut key hints (ESC / Shift / SYM)
- Application process lock management (long-press Home to force-close an app)
- Multi-threaded task pool (C-Thread-Pool)
- macOS cross-compilation support
- Status bar display: M5Stack Zero logo, clock time, and battery percentage
- Main content area: app name + page content placeholder
The project is mainly developed in a Linux environment and is also compatible with cross-platform builds. Detailed build instructions are below.
sudo apt update
sudo apt install python3 python3-pip libffi-dev libsdl2-dev
pip3 install parse scons requests tqdm
pip3 install setuptools-rust paramiko scpPython version must be >= 3.8.
git clone --recursive https://github.com/CardputerZero/launcher.git
cd launcherIf the repository has already been cloned but submodules have not been initialized:
git submodule update --init --recursiveEnter HelloWorld to build:
# Enter the project directory
cd projects/HelloWorld
# Clean the environment
scons distclean
# Build with 8 threads
scons -j8# Enter the project directory
cd projects/HelloWorld
# Load the configuration
export CONFIG_DEFAULT_FILE=linux_x86_sdl2_config_defaults.mk
# Clean the environment
scons distclean
# Build with 8 threads
scons -j8cd dist/
./HelloWorld# Install the cross-compilation toolchain
sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
# Enter the project directory
cd projects/HelloWorld
# Load the configuration
export CONFIG_DEFAULT_FILE=linux_x86_cross_cp0_config_defaults.mk
# Clean the environment
scons distclean
# Build with 8 threads
scons -j8python3 -m venv launcher-python-venv
source launcher-python-venv/bin/activate
pip3 install parse scons requests tqdm
pip3 install setuptools-rust paramiko scpPython version must be >= 3.8.
git clone --recursive https://github.com/CardputerZero/launcher.git
cd launcherIf the repository has already been cloned but submodules have not been initialized:
git submodule update --init --recursiveEnter HelloWorld to build:
# Install the cross-compilation toolchain
brew tap messense/macos-cross-toolchains
brew install aarch64-unknown-linux-gnu
# Enter the project directory
cd projects/HelloWorld
# Load the configuration
export CONFIG_DEFAULT_FILE=mac_cross_cp0_config_defaults.mk
# Clean the environment
scons distclean
# Build with 8 threads
scons -j8Windows builds use the same SCons entry point under projects/APPLaunch. Use an MSYS2 MinGW shell for the native SDL2 simulator build so that gcc, g++, pkg-config, SDL2, and FreeType are available in PATH.
pacman -S --needed \
mingw-w64-ucrt-x86_64-gcc \
mingw-w64-ucrt-x86_64-pkgconf \
mingw-w64-ucrt-x86_64-SDL2 \
mingw-w64-ucrt-x86_64-freetype \
mingw-w64-ucrt-x86_64-python-pip
python -m pip install parse scons requests tqdm setuptools-rust paramiko scpcd projects/APPLaunch
scons distclean
export CONFIG_DEFAULT_FILE=win_x86_sdl2_config_defaults.mk
scons -j8
cd dist
./M5CardputerZero-APPLaunch.exeInstall the SysGCC Raspberry64 Windows AArch64 Linux cross toolchain from https://sysprogs.com/getfile/2542/raspberry64-gcc14.2.0.exe, and update CONFIG_TOOLCHAIN_PATH in projects/APPLaunch/win_x86_cross_config_defaults.mk if it is not installed at D:\app\SysGCC\bin.
cd projects/APPLaunch
scons distclean
export CONFIG_DEFAULT_FILE=win_x86_cross_config_defaults.mk
scons -j8The cross-build output is dist/M5CardputerZero-APPLaunch and runs on the CardputerZero device. The first cross-build may download the SDK sysroot package into SDK/github_source/static_lib_v0.0.4.
# View/modify build configuration (graphical menu)
scons menuconfig
# Clean build artifacts
scons -c
# Full clean (including configuration cache)
scons distclean
# After configuring the host IP and operation command in setup.ini,
# use scons push to transfer files to the device and execute the specified command.
scons pushThis program is a desktop UI application running on the CardputerZero device. It provides a basic operation interface for the small LCD screen.
For device builds, SDL2 simulator builds, and cross-compilation, use the platform-specific build commands above with cd projects/APPLaunch. APPLaunch provides its own configuration files, including linux_x86_sdl2_config_defaults.mk, linux_x86_cross_cp0_config_defaults.mk, mac_cross_cp0_config_defaults.mk, win_x86_sdl2_config_defaults.mk, and win_x86_cross_config_defaults.mk.
# Optional: install dpkg to use dpkg-deb; otherwise the Python builder is used.
python3 scripts/debian_packager.pyThis command generates a DEB installation package. After transferring the package to the device with scp, install it with sudo dpkg -i ./***.deb.
After installing the DEB package with dpkg, the program is automatically started by the APPLaunch.service systemd user service.
After installation, use systemd commands to view and control it:
pi@pi:~ $ systemctl --user status APPLaunch.service
● APPLaunch.service - APPLaunch Service
Loaded: loaded (/usr/lib/systemd/user/APPLaunch.service; enabled; preset: enabled)
Active: active (running) since Mon 2026-06-08 15:58:19 CST; 23min ago
Invocation: aa5c4e3ca94742deb2fe0dc67467e670
Main PID: 664 (M5CardputerZero)
Tasks: 7 (limit: 448)
CPU: 1min 19.265s
CGroup: /user.slice/user-1000.slice/user@1000.service/app.slice/APPLaunch.service
└─664 /usr/share/APPLaunch/bin/M5CardputerZero-APPLaunch
Jun 08 15:58:19 pi systemd[664]: Started APPLaunch.service - APPLaunch Service.Run on the device (using Framebuffer):
# Auto-detect the ST7789V Framebuffer device
./dist/M5CardputerZero-APPLaunch
# Or manually specify the Framebuffer device
export LV_LINUX_FBDEV_DEVICE=/dev/fb0
./dist/M5CardputerZero-APPLaunch
# Specify the keyboard input device
export LV_LINUX_KEYBOARD_DEVICE=/dev/input/by-path/platform-3f804000.i2c-event
./dist/M5CardputerZero-APPLaunchThe UI is designed and generated by SquareLine Studio 1.5.0, with a resolution of 320x170 (ST7789V screen).
| Area | Content |
|---|---|
| Top status bar | Logo, clock time, battery percentage, WiFi information |
| Main content area | Application carousel pages (left/right page navigation) |
| Global hints | ESC / Shift / SYM shortcut hint overlay |
Built-in app pages include: CLI/ST terminal, Game, Setting, Compass, IP Panel, File, SSH, Mesh, Rec, Camera, LoRa, and Tank Battle. APPLaunch can also expose command or external-process entries such as Python, Store, and Math.