Power Management

Relevant source files

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

• main/core/system/power/PowerManager.cpp
• main/core/services/system_info/SystemInfoService.cpp
• main/core/apps/system_info/SystemInfoApp.cpp
• main/CMakeLists.txt
• ROADMAP.md

Power Management in FlxOS is a core system responsible for monitoring and reporting battery status, charging states, and hardware-level power configurations. It acts as a bridge between low-level hardware metrics—retrieved via the ADC (Analog-to-Digital Converter) and system services—and the user interface.

The system is designed to be modular, supporting a "Headless Mode" where GUI bridges for power monitoring are excluded to save resources. Currently, the system focuses on battery level tracking, charging detection, and providing data to system applications like the System Info App.

Architecture and Components

The power management architecture relies on a singleton manager that aggregates data from system services and pushes updates to UI observers.

PowerManager

The PowerManager class is the central authority for power state within the System namespace. It maintains the current state of the battery and charging status using observable properties.

• Initialization: The init() method ensures the manager is only set up once, performing an initial refresh() of data.
• GUI Bridges: When not in headless mode, it initializes LvglObserverBridge instances for m_batteryLevel and m_isCharging, allowing the UI to react to power changes automatically.
• Data Refresh: The refresh() method polls SystemInfoService for the latest BatteryStats.

Sources: main/core/system/power/PowerManager.cpp:10-44, main/CMakeLists.txt:16

Data Flow Diagram

The following diagram illustrates how power data flows from the hardware/drivers through the service layer to the UI components.

Battery Monitoring Logic

The monitoring logic is primarily implemented within the SystemInfoService, which interacts with the ESP32 ADC peripherals.

ADC Calibration and Calculation

To provide an accurate percentage, the system reads raw values from a configured ADC channel. It supports a voltage divider factor and specific min/max voltage thresholds defined in the system configuration (Kconfig).

Step	Process	Description
1	Read ADC	Reads raw analog value from the configured channel.
2	Calibration	Uses adc_cali_raw_to_voltage or a fallback linear calculation.
3	Divider Scaling	Applies CONFIG_FLXOS_BATTERY_DIVIDER_FACTOR to get actual battery voltage.
4	Mapping	Maps the voltage between MIN and MAX constants to a 0-100 percentage.

Sources: main/core/services/system_info/SystemInfoService.cpp:45-78, main/core/services/system_info/SystemInfoService.cpp:188-216

Data Structures

The primary data exchange format for power information is the BatteryStats structure.

struct BatteryStats {
    int level;          // Battery percentage (0-100)
    bool isCharging;    // true if power source is connected
    bool isConfigured;  // true if battery hardware is enabled in Kconfig
};

Sources: main/core/services/system_info/SystemInfoService.cpp:188-190, main/core/system/power/PowerManager.cpp:30-31

Hardware Abstraction (HAL) Support

The power management system is conditionally compiled based on hardware capabilities. If battery support is disabled in the build configuration, the service returns fallback values.

• Battery Enabled: Uses adc_oneshot and adc_cali components to poll hardware.
• Battery Disabled: Returns a hardcoded 100% level and isConfigured = false.
• Headless Mode: Disables the PowerManager GUI bridges to reduce memory footprint.

Sources: main/core/services/system_info/SystemInfoService.cpp:39-43, main/core/services/system_info/SystemInfoService.cpp:214-216, main/core/system/power/PowerManager.cpp:19-24

UI Integration

The System Info Application displays real-time power metrics in its "System" tab.

UI Update Sequence

Roadmap and Future Enhancements

As per the project roadmap, Power Management is currently categorized as a P1 Priority (High) with Moderate Complexity.

• Sleep Modes: Planned implementation for deep sleep and light sleep management.
• Battery Optimization: Future logic for dimming the display or reducing CPU frequency when battery is low.
• Battery HAL: Integration with specific PMIC (Power Management IC) drivers beyond simple ADC monitoring.

Sources: ROADMAP.md:1.7, ROADMAP.md:6.8

Summary

Power Management in FlxOS provides a centralized mechanism for monitoring battery health and charging status. By utilizing a service-based architecture, it decouples hardware-specific ADC logic from the application layer, ensuring the UI remains responsive and the system can scale to different hardware configurations including headless and battery-less builds.