MycilaConfig

Latest Release PlatformIO Registry

License: MIT Contributor Covenant

Build GitHub latest commit Gitpod Ready-to-Code

A simple, efficient configuration library for ESP32 (Arduino framework) built on top of Preferences (NVS). Provides defaults, caching, typed getters, validators, change/restore callbacks, backup/restore, and optional JSON export with password masking.

Features

Installation

PlatformIO

Add to your platformio.ini:

lib_deps =
  mathieucarbou/MycilaConfig

Optional: JSON Support

To enable toJson() method with ArduinoJson:

build_flags =
  -D MYCILA_JSON_SUPPORT
lib_deps =
  mathieucarbou/MycilaConfig
  bblanchon/ArduinoJson

Quick Start

#include <MycilaConfig.h>

Mycila::Config config;

void setup() {
  Serial.begin(115200);
  
  // Initialize the config system with NVS namespace
  config.begin("CONFIG");

  // Declare configuration keys with optional default values
  // Key names must be ≤ 15 characters
  config.configure("debug_enable", MYCILA_CONFIG_VALUE_FALSE);
  config.configure("wifi_ssid");
  config.configure("wifi_pwd");
  config.configure("port", "80");

  // Listen to configuration changes
  config.listen([](const char* key, const std::string& newValue) {
    Serial.printf("Config changed: %s = %s\n", key, newValue.c_str());
  });

  // Listen to configuration restore events
  config.listen([]() {
    Serial.println("Configuration restored!");
  });

  // Set a global validator (optional)
  config.setValidator([](const char* key, const std::string& value) {
    // Example: limit all values to 64 characters
    return value.size() <= 64;
  });

  // Set a per-key validator (optional)
  config.setValidator("port", [](const char* key, const std::string& value) {
    int port = std::stoi(value);
    return port > 0 && port < 65536;
  });

  // Set configuration values
  auto result = config.set("wifi_ssid", "MyNetwork");
  if (result) {
    Serial.println("WiFi SSID saved successfully");
  } else {
    // Check detailed result
    switch ((Mycila::Config::Result)result) {
      case Mycila::Config::Result::INVALID_VALUE:
        Serial.println("Invalid value rejected by validator");
        break;
      case Mycila::Config::Result::UNKNOWN_KEY:
        Serial.println("Key not configured");
        break;
      default:
        break;
    }
  }

  // Get configuration values
  Serial.printf("SSID: %s\n", config.get("wifi_ssid"));
  bool debug = config.getBool("debug_enable");
  int port = config.getInt("port");

  // Check if value is empty or equals something
  if (config.isEmpty("wifi_pwd")) {
    Serial.println("Password not set");
  }
  if (config.isEqual("debug_enable", MYCILA_CONFIG_VALUE_TRUE)) {
    Serial.println("Debug mode enabled");
  }
}

void loop() {}

API Reference

Class: Mycila::Config

Setup and Storage

Reading Values

Writing Values

SetResult and Result Enum

set() returns a SetResult object that:

Result codes:

Example:

auto res = config.set("key", "value");
if (!res) {
  switch ((Mycila::Config::Result)res) {
    case Mycila::Config::Result::INVALID_VALUE:
      Serial.println("Value rejected by validator");
      break;
    case Mycila::Config::Result::UNKNOWN_KEY:
      Serial.println("Key not configured");
      break;
    default:
      break;
  }
}

// You can also return Result directly from functions returning SetResult:
// return Mycila::Config::Result::UNKNOWN_KEY;

Callbacks and Validators

Backup and Restore

Restore order: Non-_enable keys are applied first, then _enable keys, ensuring feature toggles are activated after their dependencies.

Utilities

JSON Export and Password Masking

When MYCILA_JSON_SUPPORT is defined, you can export configuration to JSON:

#include <ArduinoJson.h>

JsonDocument doc;
config.toJson(doc.to<JsonObject>());
serializeJson(doc, Serial);

Keys ending with _pwd are automatically masked in the JSON output (unless you define MYCILA_CONFIG_SHOW_PASSWORD).

Customize the mask:

#define MYCILA_CONFIG_PASSWORD_MASK "****"  // default is "********"

Backup and Restore Example

// Backup to StreamString
StreamString backup;
backup.reserve(1024);
config.backup(backup);
Serial.println(backup);

// Restore from text
const char* savedConfig = 
  "wifi_ssid=MyNetwork\n"
  "wifi_pwd=secret123\n"
  "debug_enable=true\n";
config.restore(savedConfig);

// Restore from map
std::map<const char*, std::string> settings = {
  {"wifi_ssid", "NewNetwork"},
  {"port", "8080"}
};
config.restore(settings);

Key Naming Conventions

Examples

Basic Configuration

See examples/Config/Config.ino for a complete example demonstrating:

JSON Export

See examples/ConfigJson/ConfigJson.ino for:

License

MIT License - see LICENSE file for details.