Resource Monitoring

Relevant source files

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

• main/core/tasks/resource_monitor/ResourceMonitorTask.cpp
• main/core/services/system_info/SystemInfoService.cpp
• main/core/apps/system_info/SystemInfoApp.cpp
• main/core/services/cli/CliService.cpp
• ROADMAP.md

Resource Monitoring in FlxOS is a multi-layered system designed to track hardware utilization, memory health, and task performance. It consists of a dedicated background task for low-level monitoring, a centralized service for data aggregation, and user-facing interfaces including a graphical System Info App and a Command Line Interface (CLI).

The system primary monitors CPU load, internal heap memory, external PSRAM, filesystem storage, and battery status. It serves as a critical stability component by providing real-time warnings during low-memory conditions and ensuring watchdog timers are serviced to prevent system hangs.
Sources: main/core/tasks/resource_monitor/ResourceMonitorTask.cpp:24-52, ROADMAP.md:36

Core Monitoring Architecture

The monitoring architecture follows a provider-consumer pattern where low-level drivers and FreeRTOS primitives provide raw data to the SystemInfoService, which then formats it for various consumers.

The diagram shows the flow of resource data from hardware/OS layers through the service layer to the UI components.
Sources: main/core/tasks/resource_monitor/ResourceMonitorTask.cpp:32-35, main/core/services/system_info/SystemInfoService.cpp:248-265, main/core/apps/system_info/SystemInfoApp.cpp:258-261

ResourceMonitorTask

The ResourceMonitorTask is a high-priority FreeRTOS task that runs in a continuous loop to sample critical system metrics. It is implemented as a singleton and inherits from a base Task class.

Monitoring Loop Logic

The task executes every 10 seconds and performs the following operations:

1. Heartbeat: Resets the watchdog timer with a 15-second timeout.
2. Memory Sampling: Queries esp_get_free_heap_size() and esp_get_minimum_free_heap_size().
3. Uptime Tracking: Calculates total system uptime in seconds using esp_timer_get_time().
4. Threshold Alerts: If free heap drops below 32,768 bytes, a warning is issued to the system log.
5. Periodic Logging: Every 60 seconds, it prints a summary of Heap, PSRAM, and Uptime to the console.

Sources: main/core/tasks/resource_monitor/ResourceMonitorTask.cpp:16-52

Latest Stats Structure

The task maintains a Stats structure that can be retrieved by other system components:

Field	Type	Description
freeHeap	uint32_t	Current available internal memory
minFreeHeap	uint32_t	Lowest recorded heap since boot
freePsram	uint32_t	Current available external SPI RAM
uptimeSeconds	uint32_t	Total seconds since system start

Sources: main/core/tasks/resource_monitor/ResourceMonitorTask.cpp:20-22

SystemInfoService

The SystemInfoService acts as the primary data aggregator. It provides specialized methods to retrieve formatted and raw data for different hardware subsystems.

CPU and Task Tracking

The service calculates CPU usage per task by measuring the change in runtime counters over a specific interval.

CPU usage is normalized such that 100% represents a single fully loaded core.
Sources: main/core/services/system_info/SystemInfoService.cpp:337-410

Memory and Storage Stats

The service distinguishes between different memory types and filesystem partitions:

• Heap Stats: Includes total, used, free, and the "Largest Free Block" to detect memory fragmentation.
• Storage Stats: Uses esp_vfs_fat_info to monitor the /system and /data partitions.
  Sources: main/core/services/system_info/SystemInfoService.cpp:248-285

System Info Application

The SystemInfoApp is a graphical interface built with LVGL that provides a real-time dashboard of resources.

UI Tab Structure

Tab	Components	Monitored Data
System	Labels, Progress Bars	Chip model, Cores, Frequency, CPU Load per core, Uptime
Memory	Progress Bars	Heap & PSRAM usage percentages
Network	Labels	WiFi SSID, IP Address, Signal Strength (RSSI)
Tasks	Table	Name, CPU%, State, Priority, Stack High Water Mark, Core Affinity

Sources: main/core/apps/system_info/SystemInfoApp.cpp:88-212

CLI Resource Commands

The system exposes resource monitoring via a serial console using the CliService. This allows for "headless" monitoring without a display.

• tasks: Lists all FreeRTOS tasks with stack and CPU usage (alias for top).
• free: Displays detailed heap and PSRAM statistics (alias for heap).
• df: Shows storage usage for all mounted partitions (alias for storage).
• sysinfo: Provides a high-level summary of chip details and memory.

Sources: main/core/services/cli/CliService.cpp:52-160, main/core/services/cli/CliService.cpp:495-520

Conclusion

Resource monitoring in FlxOS provides both automated safeguards (via ResourceMonitorTask) and interactive diagnostics (via SystemInfoApp and CliService). By centralizing data collection in the SystemInfoService, the system maintains a consistent view of performance across both GUI and headless modes.