System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
FlxOS is a high-performance embedded operating environment designed for ESP32 and ESP32-S3 microcontrollers. It leverages a modular architecture to provide a modern, desktop-like experience on resource-constrained hardware. The system is built upon the ESP-IDF v5.5 framework, utilizing FreeRTOS for multitasking and LVGL 9 with LovyanGFX for hardware-accelerated graphics.
Sources: README.md:16-22, README.md:32-40
Core Layered Architecture
The FlxOS architecture is divided into several distinct layers that separate hardware abstraction, system services, and the user interface. This decoupling allows for features like "Headless Mode," where the OS can run without a display or GUI hardware.
High-Level Components
| Layer | Responsibility | Key Components |
|---|---|---|
| Applications | User-facing tools and utilities | Settings, Files, System Info |
| UI Framework | Window management and layout | Window Manager, Desktop, Themes |
| Core Services | System-wide background logic | File System, CLI, System Info |
| System Managers | Hardware and resource management | Display, Power, Time, Focus |
| Connectivity | Network and communication stack | WiFi, Bluetooth, Hotspot |
| HAL | Platform-specific abstractions | Display HAL, OS Abstractions |
Sources: main/core/README.md:5-11, main/CMakeLists.txt:1-55, README.md:43-57
Component Relationship Diagram
The following diagram illustrates how the core modules interact within the FlxOS ecosystem.
The diagram shows the hierarchical dependency from high-level applications down to the hardware abstraction layer.
Sources: README.md:43-57, main/CMakeLists.txt:1-40, main/core/README.md:5-11
System Boot and Initialization
The system entry point is located in main.cpp, which initializes the SystemManager. The SystemManager is responsible for hardware initialization, mounting storage partitions, and starting core background tasks.
Initialization Sequence
- Hardware Init: Setting up basic MCU peripherals.
- Storage Mounting: Initializing internal Flash (FAT) and SD card support.
- Service Startup: Starting the
SystemInfoServiceand, if enabled, theCliService. - Task Scheduling: Launching the
GuiTaskandResourceMonitorTask.
This sequence highlights the transition from power-on to the active UI state.
Sources: main/main.cpp, main/core/system/system_core/SystemManager.cpp, ROADMAP.md:37-45
Modular Application Framework
FlxOS employs a modular app architecture controlled by an AppManager. Applications are managed through a standardized lifecycle (Start, Stop, Resume, Pause). This allows the system to handle multiple windows and dynamic layouts efficiently.
Key Lifecycle Tasks
- App Lifecycle Management: Handled by
AppManager. - Window Management: Supports multi-window environments and dynamic orientation changes.
- Resource Monitoring: Continuous tracking of CPU and Memory usage via
ResourceMonitorTask.
Sources: ROADMAP.md:37-45, main/CMakeLists.txt:24-40, README.md:32-40
Build Configuration and Headless Mode
The system's modularity is enforced at compile-time via CMake. By toggling CONFIG_FLXOS_HEADLESS_MODE, developers can exclude heavy components like LVGL and LovyanGFX to run FlxOS as a background controller without a display.
Build Logic Table
| Configuration | Source Inclusion | Component Requirements |
|---|---|---|
| Standard Mode | All UI, Apps, and Theme sources | LovyanGFX, lvgl, dhcpserver |
| Headless Mode | Only Connectivity and Core Services | dhcpserver |
Sources: main/CMakeLists.txt:1-60, CMakeLists.txt:10-23
Connectivity and Networking
The networking stack is integrated into the core architecture, providing:
- WiFi Station Mode: Connecting to existing networks.
- WiFi Hotspot (SoftAP): Creating local networks with NAT and NVS persistence.
- Bluetooth: Basic control and device management.
Sources: ROADMAP.md:52-62, main/CMakeLists.txt:3-8
Conclusion
The FlxOS architecture prioritizes modularity and hardware efficiency. By utilizing a robust service-based backend and a hardware-accelerated UI frontend, it provides a scalable foundation for ESP32-based applications ranging from headless IoT controllers to complex HMI devices.
Sources: README.md:16-22, ROADMAP.md:37-47