Settings Manager
Relevant source files
The following files were used as context for generating this wiki page:
The Settings Manager is a core system component in FlxOS responsible for the centralized management, persistence, and synchronization of system-wide configurations. It provides a unified interface for registering settings as observable objects, allowing different system modules and applications to react to configuration changes in real-time.
The manager operates as a singleton and utilizes a JSON-based storage backend on the flash filesystem. It supports two primary data types: integers (used for toggles, enums, and numerical values) and strings. By integrating with an Observable pattern, it ensures that any update to a setting is automatically queued for persistent storage without requiring manual save calls from the application layer.
Sources: SettingsManager.cpp:15-18, SettingsManager.hpp:14-20, ROADMAP.md:129-130
Architecture and Core Logic
The SettingsManager is designed around a registry of Setting objects. Each setting is mapped to a unique string key and linked to an Observable instance. The system follows a "register-and-sync" flow: when a module registers a setting, the manager attempts to restore its value from a cached JSON object and establishes a subscription to monitor future changes.
Data Structures
The system defines the following internal structures to manage settings:
| Structure | Type | Description |
|---|---|---|
Setting | struct | Contains the setting type (INT or STRING) and a pointer to the associated Observable object. |
Setting::Type | enum | Defines supported data formats: INT (32-bit integer) and STRING. |
m_registeredSettings | std::map | A registry mapping string keys to Setting structures. |
m_json_cache | void* | A pointer to a cJSON object containing the parsed settings file for fast access. |
Sources: SettingsManager.hpp:33-40, SettingsManager.cpp:40-42
Initialization Flow
Upon initialization, the SettingsManager sets up an asynchronous save timer and loads existing configurations from the internal flash storage.
Sources: SettingsManager.cpp:21-38
Settings Persistence
Persistence is handled through a deferred writing mechanism to optimize flash longevity and performance. Instead of writing to the flash every time a value changes, the system uses a triggerSave mechanism.
Deferred Saving Mechanism
When an observed setting changes, the Observable callback invokes triggerSave(). This method starts (or resets) an esp_timer with a 2-second delay. This ensures that rapid successive changes (e.g., sliding a brightness bar) only result in a single write operation once the user stops interacting.
The saving process uses a temporary file (/data/settings.tmp) to ensure data integrity. The temporary file is synced to disk, the old settings file is unlinked, and the temporary file is renamed to the final destination.
Sources: SettingsManager.cpp:11-12, SettingsManager.cpp:66-71, SettingsManager.cpp:103-120
File Paths
| Purpose | Path |
|---|---|
| Persistent Storage | /data/settings.json |
| Atomic Write Buffer | /data/settings.tmp |
Sources: SettingsManager.cpp:11-12
Integration and Usage
The SettingsManager is used extensively by other managers and applications to maintain state across reboots.
Example: Theme and Display Management
The ThemeManager registers several keys to handle UI appearance and desktop behavior.
Registered System Settings
Based on implementation files, the following keys are managed by the system:
| Key | Module | Purpose |
|---|---|---|
theme | ThemeManager | Current system theme index |
glass_enabled | ThemeManager | Toggle for UI glass/blur effects |
transp_enabled | ThemeManager | Global transparency toggle |
wp_enabled | ThemeManager | Wallpaper visibility toggle |
wp_path | ThemeManager | File path for the desktop wallpaper |
hotspot_ssid | Connectivity | SSID for SoftAP mode |
hotspot_pw | Connectivity | Password for SoftAP mode |
Sources: ThemeManager.cpp:18-24, HotspotSettings.cpp:328-333, DisplaySettings.hpp:42-55
API Reference
Key Methods
| Method | Description |
|---|---|
init() | Initializes the manager, creates the save timer, and loads settings from flash. |
registerSetting(key, observable) | Links a key to an Observable<int32_t> or StringObservable. Synchronizes the observable with existing disk values. |
saveSettings() | Iterates through all registered observables, builds a JSON object, and writes it to disk. |
loadSettings() | Reads the configuration file from disk into a memory cache. |
triggerSave() | Schedules an asynchronous save operation using the esp_timer. |
Sources: SettingsManager.hpp:24-30, SettingsManager.cpp:21-40
Code Snippet: Registering a Setting
// Example from ThemeManager.cpp
void ThemeManager::init() {
// Registers a setting and links it to an observable
SettingsManager::getInstance().registerSetting("theme", m_theme_subject);
// Any changes to m_theme_subject.set() will now trigger
// an automatic save to /data/settings.json after 2 seconds.
}
Sources: ThemeManager.cpp:17-19, SettingsManager.cpp:44-47
Summary
The Settings Manager provides a robust foundation for configuration management in FlxOS. By leveraging the Observer pattern and JSON serialization, it decouples the logic of "when to save" from the applications, ensuring that system state is preserved efficiently and reliably across power cycles. Its integration with the internal flash filesystem makes it an essential component for user-facing features like theme customization, network configuration, and display preferences.