CLI Service
Relevant source files
The following files were used as context for generating this wiki page:
The CLI Service is a core background system service in FlxOS that provides a Command Line Interface (CLI) for system management, debugging, and configuration. It is built upon the esp_console component of the ESP-IDF framework and operates through a Read-Eval-Print Loop (REPL) accessible via UART or USB Serial JTAG.
The service is designed to be environment-agnostic, functioning in both standard GUI mode and Headless Mode. It acts as a bridge between the user and various system managers, including the SystemInfoService, WiFiManager, ConnectivityManager, and FileSystemService.
Sources: main/core/services/cli/CliService.cpp:527-561, main/main.cpp:24-49, README.md:27-38
Architecture and Initialization
The CLI Service follows a singleton pattern, ensuring a centralized point of command registration and execution. During the system boot sequence in app_main, the service is initialized if the CONFIG_FLXOS_CLI_ENABLED flag is set.
The initialization process configures the console hardware (UART or USB Serial), registers the base help command, and then invokes a batch registration of custom FlxOS commands categorized by functionality (System, Networking, Filesystem, and System Control).
Initialization Flow
The diagram shows the logic path from the application entry point to an active command line session.
Sources: main/core/services/cli/CliService.cpp:527-561, main/main.cpp:24-30
Command Categorization
Commands are registered using a helper macro REGISTER_CLI_CMD which maps command strings to internal handler functions.
| Category | Commands | Description |
|---|---|---|
| System Info | sysinfo, heap, uptime, tasks, psram, version, chip | Monitors hardware stats, memory usage, and task scheduling. |
| Networking | wifi, hotspot | Manages AP scanning, station connections, and SoftAP settings. |
| Filesystem | ls, cd, pwd, mkdir, rm, cat, df | Standard POSIX-like utilities for interacting with internal flash/SD storage. |
| Control | brightness, display_test, time, loglevel, reboot | Direct hardware control and system-level parameters. |
Sources: main/core/services/cli/CliService.cpp:484-525
Functional Modules
Networking Management
The CLI provides deep integration with the connectivity stack. The wifi command supports sub-commands for lifecycle management (on, off), discovery (scan), and connectivity (connect, disconnect). The hotspot command allows users to toggle the SoftAP and view NAT status.
The sequence illustrates the asynchronous nature of a WiFi scan initiated via the CLI.
Sources: main/core/services/cli/CliService.cpp:180-234
Filesystem Operations
The service maintains a "Current Working Directory" (CWD) state to support relative path navigation. A helper function resolvePath is used to normalize input paths, handling symbols like . and .. to prevent directory traversal errors and ensure compatibility with the FileSystemService.
Key filesystem functions include:
cmdLs: Lists directory contents with type (DIR/FILE) and size.cmdCat: Opens and streams file contents to the terminal output.cmdMkdir/cmdRm: Modifies the partition structure via the VFS layer.
Sources: main/core/services/cli/CliService.cpp:15-50, main/core/services/cli/CliService.cpp:322-414
Headless Operation
The CLI Service is critical for "Headless Mode," a configuration where GUI components like LVGL and LovyanGFX are excluded from the build to save resources. In this mode, the CLI remains the primary interface for system interaction.
Sources: main/CMakeLists.txt:46-55, main/main.cpp:40-49
Technical Implementation Details
Implementation Snippet: Command Registration
The service uses a macro to wrap the esp_console_cmd_register logic, simplifying the addition of new commands.
// main/core/services/cli/CliService.cpp:473-482
#define REGISTER_CLI_CMD(name, help_text, handler) \
{ \
const esp_console_cmd_t cmd = { \
.command = (name), \
.help = (help_text), \
.hint = nullptr, \
.func = (handler), \
.argtable = nullptr, \
.func_w_context = nullptr, \
.context = nullptr \
}; \
ESP_ERROR_CHECK(esp_console_cmd_register(&cmd)); \
}
Sources: main/core/services/cli/CliService.cpp:473-482
System Diagnostics
Through the SystemInfoService, the CLI can output detailed task statistics, including Stack High Water Mark, CPU usage percentage, and core affinity for every running FreeRTOS task.
Sources: main/core/services/cli/CliService.cpp:106-121
Conclusion
The CLI Service provides an essential abstraction for interacting with the FlxOS kernel and hardware. By leveraging a modular command registration system and the standard ESP-IDF console component, it offers a robust toolset for both development debugging and production-level headless system management.
Sources: main/core/services/cli/CliService.cpp:559-561, main/core/README.md:1-12