This repository is the Meshtastic device UI C++20 library. It supports embedded Arduino-based devices and Linux/Portduino; this checkout does not define PlatformIO environments (platformio.ini/variants). For firmware builds, use the consuming firmware repository's target and build instructions rather than assuming a local PlatformIO target here.
The standalone native build uses CMake, Portduino, LVGL, and doctest. From this repository root:
cmake -B build -S .
cmake --build build -j
ctest --test-dir build --output-on-failureENABLE_DOCTESTS defaults on when this repository is configured as the top-level CMake project. The native build is useful for host-side behavior and regression tests, but it does not replace compiling or exercising the relevant hardware target.
include/contains public interfaces and headers.source/contains the UI library implementations, including graphics, input, communications, filesystem, and utility code.src/contains Meshtastic protobuf/constants integration and the library entry point.portduino/contains native-platform support.drivers/contains device-specific support code.generated/contains generated LVGL/EEZ Studio view sources, organized by view dimensions.tests/contains the CMake/doctest test executable's test cases.cmake/defines external dependency setup; CMake fetches several dependencies withFetchContent.
- C++20 is required (
CMAKE_CXX_STANDARDis 20 and extensions are disabled). - Follow existing subsystem boundaries: public contracts generally live under
include/, with implementations undersource/. Reuse established interfaces and factories, such asIClientBase,IStorage,DisplayDriverFactory, andViewFactory; do not add a parallel abstraction without a concrete need. - New shared UI behavior should work across all supported devices. Do not scatter
#ifdef DEVICE_Xchecks through shared logic to handle individual boards. - Put device-specific behavior behind the narrowest suitable existing abstraction. When a new behavior genuinely differs by device, prefer an abstract interface with device-specific implementations selected by a factory, following patterns such as
DisplayDriverandDisplayDriverFactory. - Keep device-specific compile-time checks at platform or factory registration boundaries when required by the build or hardware APIs. Follow the existing conditional-registration patterns; do not add an interface or factory when the existing abstraction already handles the variation.
- Use RAII and the ownership style already used by the surrounding code. Consider embedded memory and lifetime costs when adding allocations, but do not replace appropriate dynamic collections with fixed-size storage by default.
- Native tests compile against the library and Portduino/LVGL support. They are host tests, not hardware tests; avoid requiring attached peripherals or assuming native execution proves hardware behavior. Use the existing doctest conventions (
TEST_CASE,SUBCASE, andCHECK) and test the narrow behavior changed.
Do not hand-edit files under generated/; changes there are overwritten by UI generation. Update the corresponding UI authoring source and regenerate the affected view using the project's established workflow. Keep view-specific references scoped to the matching generated/ui_<dimensions>/ directory.
The CMake build currently selects ui_320x240. In the PlatformIO library integration, extra_script.py selects a generated view from the consuming build's VIEW_* definition and adds portduino/ when ARCH_PORTDUINO is defined. When changing generated-view or platform integration, preserve both build paths.
CMakeLists.txt uses configure-time source globs. Rerun cmake -B build -S . after adding or removing source files so the build picks up the changes.
Device-specific UI settings are compiler flags in the device's platformio.ini, either in the consuming firmware repository's variant or in a standalone PlatformIO integration. Keep pin and panel configuration with that target instead of hard-coding it into shared UI code.
- If LovyanGFX supports both the TFT panel and touch controller, use the generic driver. Define
LGFX_DRIVER_TEMPLATE, setLGFX_DRIVER=LGFX_GENERIC, and setGFX_DRIVER_INC=\"graphics/LGFX/LGFX_GENERIC.h\". Add the panel, touch, bus, GPIO, rotation, and dimensions flags required by that board. Seecrowpanel_small_esp32s3_baseinfirmware/variants/esp32s3/elecrow_panel/platformio.ini. - If the generic LovyanGFX configuration cannot represent the hardware, add a board-specific LovyanGFX device definition under
include/graphics/LGFX/, then setLGFX_DRIVERandGFX_DRIVER_INCto that class and header. Include the header insource/graphics/driver/DisplayDriverFactory.cppunder the corresponding board define so the driver class is available to the factory. SeeLGFX_ELECROW70.handcrowpanel_large_esp32s3_basein the same firmware variant. - Select a UI view independently from the display resolution.
320x240is the CMake default and a common TFT layout; other view implementations are available, but views are not restricted to matching resolutions. The architecture allows any view to be used at any resolution, with the layout adapting to the display; some views may simply look better at particular resolutions or aspect ratios.VIEW_*selects the layout, not a resolution compatibility check. On Portduino, the display is created at runtime using thePanelsettings in the host's.yamlconfiguration. On embedded targets,DISPLAY_SET_RESOLUTIONmakes the LVGL display use the resolution reported by the LovyanGFX driver and should be used when view and device resolution do not match.