Development guide

LILYGO UI separates the user interface toolkit, the launcher, the application projects, and the target sysroot. This keeps a host simulation build useful while preserving a reproducible AArch64 target workflow.

Runtime layers

Layer	Responsibility	Reference
Application	Independent executable, UI, state, and device-specific behavior.	template
Launcher	Discovers applications from JSON manifests and presents the application grid.	launcher
AppKit	LVGL, fonts, system status, status bar, and runtime services shared by applications.	cm0-appkit
Sysroot and toolchain	AArch64 headers, libraries, package overlays, and CMake cross-compilation settings.	CM0BspBuilder
Project workflow	Initialization, host tests, cross-builds, Debian packaging, and SSH deployment.	lpm

AppKit integration

The AppKit README documents CMake package integration with the LilyGoUI package. A consumer uses the exported targets after locating the package:

find_package(LilyGoUI CONFIG REQUIRED)

The documented targets include:

• LilyGoUI::LVGL
• LilyGoUI::UIFonts
• LilyGoUI::SystemStatus
• LilyGoUI::StatusBar
• LilyGoUI::Runtime

Applications compile and statically link their AppKit and LVGL code. On a host, the project uses SDL2 and FreeType; on the target, the CM0 sysroot supplies the DRM/FreeType environment.

Keyboard input

Applications use cm0_app_run() and the default LilyGoUI::Runtime input group. AppKit handles keyboard discovery, hotplug, key mapping, focus navigation, and software-keyboard suppression. Connect business actions to control events, and mark modal focus scopes and scrollable browsing regions as needed.

The keyboard integration guide provides code examples, a key behavior reference, focus styling, and validation and release checklists.

Launcher metadata and layout

Applications are independent executables. The launcher discovers them through JSON manifests, which keeps the application registry separate from the launcher binary. The launcher README describes a default logical canvas of 568 × 1232 in portrait orientation, a 96 px status bar, and up to 18 applications per page in a 3 × 6 portrait or 6 × 3 landscape grid.

Treat these values as the current launcher defaults, not as a guarantee for every future hardware profile. Check the upstream repository when designing a layout that depends on exact dimensions.

Build and release path

The intended contribution path is:

1. start from template;
2. use lpm to configure a host build and validate the UI;
3. build against the CM0 sysroot generated by CM0BspBuilder;
4. create a Debian artifact; and
5. publish or register the application through packages.

The separate cm0-appkit and launcher repositories are the best references for API and runtime behavior. Avoid depending on private implementation details when a public AppKit target or manifest field exists.