Installation & Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CMakeLists.txt
• main/CMakeLists.txt
• main/main.cpp
• ROADMAP.md

FlxOS is a modern desktop environment designed for ESP32 microcontrollers, leveraging the ESP-IDF framework, LVGL 9, and LovyanGFX. The installation process involves setting up a specific toolchain, configuring hardware targets, and utilizing the ESP-IDF build system (idf.py) to compile and flash the firmware.

The system supports multiple ESP32 variants and can be configured to run in different modes, including a standard GUI mode or a headless mode for devices without displays.

Sources: README.md:14-19, README.md:38-42, CMakeLists.txt:10-22

Prerequisites

Before beginning the installation, ensure the host environment meets the following software requirements:

Requirement	Version	Description
ESP-IDF	v5.5+	Core development framework from Espressif
CMake	3.16+	Minimum version for build orchestration
Ninja	Latest	Recommended build system for ESP-IDF
Python	3.8+	Required for ESP-IDF scripts and project utilities

Sources: README.md:52-57, CMakeLists.txt:4

Environment Setup & Cloning

The project relies on Git submodules for external components like LVGL and LovyanGFX. It is critical to clone recursively to ensure all dependencies are present.

# Clone the repository with submodules
git clone --recursive https://github.com/flxos-labs/flxos.git
cd flxos

# Export the ESP-IDF environment variables
. $HOME/esp/esp-idf/export.sh

Sources: README.md:60-66

Target Configuration

FlxOS supports various ESP32 chips. Users must set the target before building to ensure the correct hardware abstraction layer (HAL) and compiler settings are applied.

# Set target for ESP32-S3 (Example)
idf.py set-target esp32s3

# Set target for standard ESP32
idf.py set-target esp32

Partitioning & Flash Sizes

The project provides pre-configured partition files optimized for different flash sizes:

Target Variant	Flash Size	Partition File
ESP32	4MB	partitions_4mb.csv
ESP32	8MB	partitions_8mb.csv
ESP32-S3	16MB	partitions_16mb.csv

Sources: README.md:68-75, README.md:77-83

Build & Deployment Process

The deployment process follows the standard ESP-IDF workflow. The following diagram illustrates the lifecycle from configuration to monitoring.

Headless Mode Configuration

FlxOS can be built without GUI components by enabling CONFIG_FLXOS_HEADLESS_MODE. When enabled, the build system automatically excludes lvgl and LovyanGFX components to save flash space and RAM.

# logic in CMakeLists.txt
if(LINE MATCHES "^CONFIG_FLXOS_HEADLESS_MODE=y")
    message(STATUS "FlxOS: Headless mode enabled - excluding lvgl and LovyanGFX components")
    set(EXCLUDE_COMPONENTS lvgl LovyanGFX)
endif()

Sources: CMakeLists.txt:10-22, main/CMakeLists.txt:20-25

Initial Execution

Upon the first boot, the system follows a specific initialization sequence handled in app_main.

Build Commands Reference

Command	Description
idf.py build	Compiles the source code and links dependencies.
idf.py fullclean	Removes all build artifacts for a fresh start.
idf.py menuconfig	Opens the TUI for system-level configuration.
idf.py flash monitor	Flashes the binary and opens the serial terminal.

Sources: README.md:85-110

Summary

Setting up FlxOS requires a functional ESP-IDF v5.5 environment. The build system is highly modular, allowing developers to target various ESP32 chips and toggle between GUI and Headless modes via menuconfig. Successful installation results in the system initializing core hardware, mounting filesystems (FAT/SD Card), and launching the AppManager or CliService depending on the configuration.

Sources: README.md:14-19, main/main.cpp:20-30, main/CMakeLists.txt:58-62