Hardware Support & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
FlxOS is designed as a high-performance operating environment for ESP32-series microcontrollers, leveraging a robust Hardware Abstraction Layer (HAL) to support a wide array of displays, touch controllers, and peripherals. The system is built on the ESP-IDF v5.5 framework and utilizes LovyanGFX for hardware-accelerated graphics rendering.
The configuration of FlxOS is modular, allowing for both standard desktop-like GUI environments and "Headless" modes for background service processing. This flexibility enables FlxOS to run on various hardware targets including the standard ESP32 and the more powerful ESP32-S3.
Sources: README.md:12-25, main/CMakeLists.txt:47-58
Target Hardware & Platform Support
FlxOS officially supports multiple ESP32 variants. The architecture separates core system logic from hardware-specific implementations via the HAL.
Supported Microcontrollers
The project is optimized for the following Espressif targets:
- ESP32: Standard dual-core microcontroller.
- ESP32-S3: Optimized for AI and advanced graphics, featuring support for larger PSRAM and flash configurations.
Memory and Storage Configuration
FlxOS utilizes specific partition schemes based on the available flash size of the target hardware to manage system data and user files.
| Target | Flash Size | Partition File |
|---|---|---|
| ESP32 | 4MB | partitions_4mb.csv |
| ESP32 | 8MB | partitions_8mb.csv |
| ESP32-S3 | 16MB | partitions_16mb.csv |
Sources: README.md:19-25, README.md:80-84
Hardware Abstraction Layer (HAL) Architecture
The HAL is divided into specialized modules for display, input, and general-purpose I/O. This decoupling ensures that the core SystemManager can initialize hardware without being tightly coupled to specific driver implementations.
The diagram above illustrates how the System Manager interacts with various hardware components through the HAL.
Sources: ROADMAP.md:105-115, README.md:43-55
Display & Graphics
FlxOS uses LovyanGFX as the primary driver library, supporting over 30 different display controllers. This is integrated with LVGL 9 to provide hardware acceleration.
- Key Features: Hardware-accelerated rendering, 60+ FPS animations, and dynamic display rotation.
- Supported Drivers: Includes common controllers like ILI9341, ST7735, ST7789, and ST7796.
Sources: README.md:31-33, ROADMAP.md:105-107, LVGL_Features.md:65-71
Connectivity Modules
The hardware support extends to the ESP32's integrated wireless capabilities, managed through the ConnectivityManager.
| Module | Features Supported |
|---|---|
| Wi-Fi | Station Mode (Connecting to APs), Scanning, and SoftAP (Hotspot) with NAT support. |
| Bluetooth | Enable/Disable toggling and basic device pairing. |
| Storage | Internal Flash with Wear-leveling and SD Card support via SPI/SDMMC. |
Sources: ROADMAP.md:52-60, ROADMAP.md:88-92, main/core/services/cli/CliService.cpp:188-210
System Operating Modes
FlxOS can be configured in different modes depending on the hardware capabilities and project requirements.
Headless Mode
When CONFIG_FLXOS_HEADLESS_MODE is enabled, the system excludes GUI-related components such as LVGL and LovyanGFX. This is useful for devices acting purely as IoT gateways or servers.
This flow demonstrates the conditional compilation logic based on the headless mode configuration.
Sources: main/CMakeLists.txt:23-44, CMakeLists.txt:13-23
CLI Management
For hardware debugging and low-level configuration, FlxOS provides a Command Line Interface (CLI) service. This service allows direct interaction with hardware via serial consoles.
// Command registration helper for CLI hardware tools
#define REGISTER_CLI_CMD(name, help_text, handler) \
{ \
const esp_console_cmd_t cmd = { \
.command = (name), \
.help = (help_text), \
.func = (handler), \
}; \
esp_console_cmd_register(&cmd); \
}
Sources: main/core/services/cli/CliService.cpp:450-462
Hardware Inspection Commands
The CLI includes specific commands to query hardware state:
chip: Displays chip model, revision, cores, and CPU frequency.psram: Shows total, free, and used PSRAM statistics.brightness: Sets or displays the current display backlight levels (0-100%).display_test: Triggers a low-level driver test to bypass the UI stack and draw direct color patterns.
Sources: main/core/services/cli/CliService.cpp:138-160, main/core/services/cli/CliService.cpp:387-410
Build & Firmware Configuration
The build system utilizes CMake to manage component dependencies and hardware-specific compilation flags.
- LovyanGFX Integration: Conditionally linked based on
CONFIG_LV_USE_LOVYAN_GFX. - PSRAM Support: Enabled via the
esp_psramcomponent requirement in the main CMake file. - Static Assets: Flash images for system and user data are generated and flashed to specific partitions during the build process.
Sources: main/CMakeLists.txt:59-67, main/CMakeLists.txt:71-74
Conclusion
FlxOS provides a robust framework for ESP32 hardware, balancing high-level UI requirements with low-level system management. By utilizing LovyanGFX for display abstraction and providing specialized modes like Headless and CLI-driven management, the system remains adaptable to various embedded hardware configurations from simple controllers to complex HMI devices.