Display System Management
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Display System Management in FlxOS is responsible for orchestrating the visual output hardware and high-level graphics frameworks. It serves as the bridge between the hardware-specific display drivers and the user interface modules, ensuring consistent control over brightness, rotation, and rendering states. The system is designed to be modular, supporting both a rich graphical mode powered by LVGL and a "headless" mode for resource-constrained or remote operation scenarios.
The core of this system is the DisplayManager, which centralizes control over the display Hardware Abstraction Layer (HAL). It integrates with the SystemManager for initial hardware setup and provides observables for other system services to react to display state changes, such as orientation shifts or brightness adjustments.
Sources: main/core/system/display/DisplayManager.hpp, main/main.cpp:21-44, README.md
Core Architecture
The display management architecture follows a layered approach, decoupling the underlying graphics library from the system-level controls.
Hardware Abstraction Layer (HAL)
The system utilizes LovyanGFX as the primary driver backend, which supports over 30 different display drivers. This HAL is integrated with LVGL 9, which handles the high-level UI component rendering and animations. The DisplayManager acts as the primary controller for this stack.
The diagram shows the relationship between the system managers, the HAL, and the rendering engine.
Sources: ROADMAP.md:126-135, main/core/system/display/DisplayManager.hpp, main/CMakeLists.txt:47-51
Execution Flow
The display system initialization occurs during the early stages of the system boot process. If the system is not in headless mode, the GuiTask is spawned to manage the LVGL heartbeats and rendering cycles.
This sequence illustrates the startup flow for display-related components.
Sources: main/main.cpp:21-44, main/CMakeLists.txt:20-45
System Configurations
The display system behavior is heavily influenced by compile-time configurations defined in the build system.
| Configuration | Description | Impact |
|---|---|---|
CONFIG_FLXOS_HEADLESS_MODE | Disables all graphical components. | Excludes lvgl and LovyanGFX from build; removes GuiTask. |
CONFIG_LV_USE_LOVYAN_GFX | Links LovyanGFX to LVGL. | Enables hardware-accelerated rendering via the LovyanGFX backend. |
CONFIG_FLXOS_CLI_ENABLED | Enables command-line interface. | Provides the brightness and display_test commands for manual control. |
Sources: main/CMakeLists.txt:18-63, main/main.cpp:32-44
Functional Capabilities
Brightness and Power Management
The DisplayManager manages display brightness through an observable property. This allows real-time updates from the UI or the CLI.
- Range: 0 to 255 (internally mapped).
- CLI Interface: Users can set brightness via the
brightness <0-100>command, which is then scaled to the 0-255 range for the hardware driver.
Sources: main/core/services/cli/CliService.cpp:468-485, main/core/system/display/DisplayManager.hpp
Display Testing and Maintenance
For debugging purposes, the system provides a low-level "Display Test" mode. This mode pauses the main GuiTask (LVGL rendering) and allows direct manipulation of the display buffer to draw specific patterns or hex-coded colors.
- Command:
display_test <color_hex> - Resume: The test mode can be exited to resume normal LVGL operation using
display_test off.
Sources: main/core/services/cli/CliService.cpp:488-510
Dynamic Orientation
The system supports dynamic display rotation, allowing the UI to adjust its layout based on the current physical orientation of the device. This is tracked as a planned and partially implemented feature in the roadmap for v1.0.0 Alpha.
Sources: ROADMAP.md:65-66, README.md
Integration with Services
The display system does not operate in isolation; it provides data to and receives commands from various services:
- System Info Service: Provides the current display resolution (X and Y) and color format to applications like the
SystemInfoApp. - CLI Service: Exposes display controls to the serial terminal for remote management.
- App Manager: Ensures that application windows are rendered within the constraints provided by the
DisplayManager.
Sources: main/core/apps/system_info/SystemInfoApp.cpp:115-117, main/core/services/cli/CliService.cpp:468-510
Conclusion
Display System Management in FlxOS provides a robust framework for handling embedded visual interfaces. By abstracting complex hardware drivers through LovyanGFX and providing a centralized management class in DisplayManager, the system enables high-performance graphics (60+ FPS) while maintaining the flexibility to run in headless modes for specialized industrial or networking applications.
Sources: README.md, ROADMAP.md:167-177