Debugging & Logging
Relevant source files
The following files were used as context for generating this wiki page:
Debugging and logging in FlxOS comprise a multi-layered system designed to provide real-time hardware insights, runtime software monitoring, and automated code quality verification. The system integrates standard ESP-IDF logging macros with a custom CliService for interactive debugging and a suite of automated analysis scripts to maintain project integrity.
The primary objective of this subsystem is to allow developers to monitor system state (such as heap memory, task distribution, and connectivity status) while providing tools to identify and resolve issues during development and deployment phases.
Runtime Logging Architecture
FlxOS utilizes a centralized logging utility, primarily referenced through the Log namespace, to output system status and events. The entry point of the application uses these utilities to signal major lifecycle milestones, such as hardware initialization and service startup.
Logging Flow
The logging system distinguishes between standard GUI mode and Headless Mode. In GUI mode, logs are often paired with system notifications, whereas in Headless mode, logging serves as the primary feedback mechanism via the serial console.
Log Levels and Tags
Logging is categorized by tags (e.g., "Main", "CLI") and can be dynamically adjusted via the Command Line Interface (CLI). This allows developers to isolate messages from specific subsystems without overwhelming the console output.
| Feature | Description |
|---|---|
| Tagging | Alphanumeric identifiers used to filter log sources. |
| LogLevel Command | CLI command to set ESP log levels (none, error, warn, info, debug, verbose). |
| Static Tags | Defined within modules using static constexpr std::string_view TAG. |
Sources: main/main.cpp:16, main/core/services/cli/CliService.cpp:484-508
Interactive Debugging (CliService)
The CliService provides a Read-Eval-Print Loop (REPL) that allows developers to query system internals at runtime. It is essential for monitoring resource-constrained environments like the ESP32.
System Inspection Commands
The CLI includes specific commands to inspect memory, tasks, and hardware status.
sysinfo: Displays chip model, revision, CPU frequency, and PSRAM size.heap/free: Monitors free, minimum free (all-time low), and total heap memory.tasks/top: Lists all FreeRTOS tasks, including their state, stack high-water mark, priority, and CPU usage percentage.psram: Provides detailed statistics on external RAM usage.
Sources: main/core/services/cli/CliService.cpp:92-111, main/core/services/cli/CliService.cpp:128-140, main/core/services/cli/CliService.cpp:160-172
Interactive Debugging Sequence
The following diagram illustrates how the CliService processes a diagnostic command from the user.
Automated Quality & Static Analysis
Beyond runtime debugging, FlxOS employs a set of automated tools to detect potential bugs and maintain documentation coverage. These tools generate reports stored in the /reports directory.
Code Quality Suite
A master script, code_quality.sh, orchestrates several checks:
- Format Check: Ensures code follows project style guidelines.
- Complexity Analysis: Calculates nesting depth and cyclomatic complexity to identify difficult-to-maintain code.
- Include Analysis: Detects circular dependencies and include order violations.
- Naming Check: Enforces naming conventions (PascalCase for classes, camelCase for functions).
Sources: scripts/code_quality.sh:44-93, scripts/check_naming.py:1-10
Clang-Tidy Integration
The run_clang_tidy.sh script provides static analysis to find programming errors, bug-prone patterns, and performance issues. It supports a --fix mode to automatically apply safe corrections.
Sources: scripts/run_clang_tidy.sh:47-98
Documentation and TODO Tracking
The check_docs.py utility acts as a debugger for project metadata. It scans the main/ directory to track technical debt and documentation gaps.
| Check Type | Target | Metric |
|---|---|---|
| File Headers | .cpp, .hpp, .c, .h | Presence of block/line comment headers. |
| Function Docs | Public functions in headers | Presence of Doxygen-style (/// or /**) comments. |
| Debt Tracking | All source files | Count of TODO, FIXME, and HACK comments. |
| Readme Status | Major directories | Presence of README.md for module-level documentation. |
Sources: scripts/check_docs.py:22-30, scripts/check_docs.py:32-44, scripts/check_docs.py:46-86
Summary
Debugging and Logging in FlxOS is a comprehensive ecosystem that bridges the gap between low-level hardware diagnostics and high-level code quality. By combining real-time serial logging and an interactive CLI with aggressive static analysis and documentation tracking, the system ensures that developers can effectively monitor the ESP32's resources and maintain a robust codebase. The CliService serves as the primary window into the live system, while the suite of Python and Bash scripts ensures long-term maintainability.