config-nvs

name: config-nvs description: "NVS/Preferences configuration storage for the pool-controller — ConfigManager API, key naming, NVS vs LittleFS trade-offs, OTA-safe persistence, and migration. 🇩🇪 Deutsche Trigger: Konfiguration, NVS, Preferences, ConfigManager, Konfiguration speichern, Einstellungen persistieren, OTA-sicher, Factory Reset, Werksreset." keywords: - configuration - konfiguration - nvs - preferences - configmanager - konfiguration speichern - einstellungen - settings - persistenz - persistence - ota-sicher - ota safe - factory reset - werksreset - wifi credentials - mqtt config - ntp config

NVS Configuration Storage — Pool Controller

The pool-controller stores all configuration data in ESP32 NVS (Non-Volatile Storage) via the Arduino Preferences library. This replaces the earlier LittleFS JSON-based /config.json approach.

Why NVS over LittleFS/JSON?

Architecture

ConfigManager (static class)
│
├── begin()   → opens NVS namespace "config", calls load()
├── load()    → reads all keys from NVS into memory structs
├── save()    → writes all memory structs to NVS atomically
└── reset()   → clears entire NVS namespace, resets to defaults
│
├── getWiFi()      → WiFiConfig&   { ssid, password }
├── getMqtt()      → MqttConfig&   { host, port, username, password, useTls }
├── getNtp()       → NtpConfig&    { server, timezone }
├── getSettings()  → ControllerSettings& { loopInterval, tempMaxPool, … }
│
├── setAdminPassword() / verifyAdminPassword()
└── isConfigured() / setConfigured()

⚠️ Save pattern: After modifying any field via the getters above, call ConfigManager::save() explicitly:

ConfigManager::getSettings().opMode = "timer";
ConfigManager::save();

NVS Key Map

All config values live in a single NVS namespace "config":

🔍 Code Search: the exact key names are defined as constexpr at the top of src/ConfigManager.cpp.

OTA Safety

NVS data survives all firmware update methods automatically:

• OTA (Over-the-Air): ✅ NVS partition is never touched by OTA
• USB serial flash: ✅ Safe as long as Erase All Flash Before Sketch Upload is Disabled (default in PlatformIO)
• PlatformIO pio run --target erase: ❌ Will wipe NVS — use with caution

The old OTA backup/restore logic (backupConfig() / restoreConfig()) and the /config.json.ota file have been removed. They are no longer needed.

Boot Version Tracking

ConfigManager::logOtaTransition() uses a separate NVS namespace "ota-version" with a single key "fw_version" to detect version transitions across OTA updates. It logs:

• First boot ever — no previous version found
• OTA update detected — version changed (logs old → new)
• Normal boot — same version as before

// Called once in PoolControllerContext::setup() after ConfigManager::begin()
ConfigManager::logOtaTransition();

Factory Reset

ConfigManager::reset() clears the entire "config" NVS namespace and restores factory defaults:

ConfigManager::reset();
ConfigManager::save();  // persist the cleared state

The WebPortal::apiFactoryReset() calls this and reboots the ESP32.

Adding a New Config Field

1. Add the field to the appropriate struct in ConfigManager.hpp
2. Add a constexpr key name at the top of ConfigManager.cpp
3. Add a prefs.getTYPE(key, default) call in load()
4. Add a prefs.putTYPE(key, value) call in save()
5. Add a default initialization in the struct definition (for reset())

Example — adding a new heaterTimeout setting:

// In ConfigManager.hpp:
struct ControllerSettings {
  // ... existing fields ...
  int heaterTimeout = 30;  // minutes
};

// In ConfigManager.cpp — key:
static constexpr const char *kSetHeaterTimeout = "set_heat_to";

// In ConfigManager::load():
settings_.heaterTimeout = prefs.getInt(kSetHeaterTimeout, 30);

// In ConfigManager::save():
prefs.putInt(kSetHeaterTimeout, settings_.heaterTimeout);

Related Files