Configuration

Configuration

Understanding how configuration and settings management works in ksIotFrameworkLib.

---

📖 Overview

The framework provides a flexible configuration system that handles:

• WiFi credentials storage
• MQTT broker settings
• Application-specific parameters
• Persistent configuration across reboots

Configuration is stored in the device's file system (SPIFFS/LittleFS) and managed through provider components.

---

🗂️ Configuration Storage

File System

Configuration files are stored in the device's flash memory:

/ (LittleFS/SPIFFS root)
├── config.json           # Main configuration file
└── (application files)

Configuration File Format

JSON format provides human-readable and editable configuration:

{
  "wifi": {
    "ssid": "MyNetwork",
    "password": "wifi_password"
  },
  "mqtt": {
    "broker": "192.168.1.100",
    "port": 1883,
    "username": "",
    "password": "",
    "client_id": "MyDevice"
  }
}

---

📦 Configuration Providers

ksConfigProvider

Base class for all configuration management.

Location: src/ksf/comp/ksConfigProvider.h

Key Methods:

// Load configuration from file
bool load()

// Save configuration to file
bool save()

// Get parameter value
String getParam(const char* key)

// Set parameter value
void setParam(const char* key, const char* value)

// Check if parameter exists
bool hasParam(const char* key)

Usage Pattern:

class MyApp : public ksApplication {
protected:
    bool init() override {
        // Create config provider
        addComponent<ksConfigProvider>();
        return true;
    }
    
    bool postInit() override {
        auto config = findComponent<ksConfigProvider>();
        
        // Load existing config
        if (config->load()) {
            String value = config->getParam("mySetting");
        }
        
        return true;
    }
};

---

🌐 WiFi Configuration

ksWifiConfigProvider

Manages WiFi network credentials.

Stored Parameters:

• ssid — WiFi network name
• password — WiFi network password
• static_ip — (optional) Static IP address
• static_gateway — (optional) Gateway address
• static_subnet — (optional) Subnet mask

Configuration Methods:

Method 1: Via WiFi Configurator (Recommended)

// In config application
addComponent<ksWifiConfigurator>();

// Device creates AP
// User configures via web interface
// Credentials saved automatically

Method 2: Programmatically

auto wifiConfig = findComponent<ksWifiConfigProvider>();

wifiConfig->setParam("ssid", "MyNetwork");
wifiConfig->setParam("password", "SecurePassword");
wifiConfig->save();

Method 3: Via Device Portal

1. Access Device Portal: http://device-ip
2. Navigate to WiFi settings
3. Enter credentials
4. Click Save

Loading WiFi Configuration

class MainApp : public ksApplication {
protected:
    bool init() override {
        auto wifiConfig = findComponent<ksWifiConfigProvider>();
        
        // Check if configured
        if (!wifiConfig->hasParam("ssid")) {
            return false;  // Go to config app
        }
        
        // Load credentials
        wifiConfig->load();
        
        // Add WiFi connector
        addComponent<ksWifiConnector>("MyDevice");
        return true;
    }
};

---

📡 MQTT Configuration

ksMqttConfigProvider

Manages MQTT broker connection settings.

Stored Parameters:

• broker — MQTT broker address/IP
• port — Broker port (default: 1883)
• username — (optional) Authentication username
• password — (optional) Authentication password
• client_id — MQTT client identifier

Configuration Methods:

Method 1: Via Device Portal (Recommended)

1. Access Device Portal
2. Navigate to MQTT settings
3. Enter broker details
4. Click Save
5. Device reconnects with new settings

Method 2: Programmatically

auto mqttConfig = findComponent<ksMqttConfigProvider>();

mqttConfig->setParam("broker", "192.168.1.100");
mqttConfig->setParam("port", "1883");
mqttConfig->setParam("username", "device_user");
mqttConfig->setParam("password", "device_pass");
mqttConfig->save();

Method 3: Application-Specific

bool init() override {
    // Set default MQTT config
    auto mqttConfig = addComponent<ksMqttConfigProvider>();
    
    if (!mqttConfig->hasParam("broker")) {
        mqttConfig->setParam("broker", "homeassistant.local");
        mqttConfig->setParam("port", "1883");
        mqttConfig->save();
    }
    
    return true;
}

Loading MQTT Configuration

bool postInit() override {
    auto mqttConfig = findComponent<ksMqttConfigProvider>();
    
    if (mqttConfig->hasParam("broker")) {
        mqttConfig->load();
        
        // MQTT connector will use this config
        addComponent<ksMqttConnector>();
    }
    
    return true;
}

---

🔧 Application Configuration

Custom Configuration Provider

Create application-specific configuration:

class MyAppConfig : public ksConfigProvider
{
public:
    // Application settings
    String getSensorInterval() {
        return getParam("sensor_interval");
    }
    
    void setSensorInterval(const String& interval) {
        setParam("sensor_interval", interval.c_str());
    }
    
    bool getDebugMode() {
        return getParam("debug_mode") == "true";
    }
    
    void setDebugMode(bool enabled) {
        setParam("debug_mode", enabled ? "true" : "false");
    }
    
    // Load with defaults
    bool loadWithDefaults() {
        if (!load()) {
            // Set defaults
            setSensorInterval("5000");
            setDebugMode(false);
            save();
        }
        return true;
    }
};

Usage:

bool init() override {
    auto config = addComponent<MyAppConfig>();
    config->loadWithDefaults();
    return true;
}

bool loop() override {
    auto config = findComponent<MyAppConfig>();
    unsigned long interval = config->getSensorInterval().toInt();
    
    if (millis() - lastRead > interval) {
        readSensor();
        lastRead = millis();
    }
    return true;
}

---

💡 Configuration Patterns

Pattern 1: Required Configuration

class ConfigurableApp : public ksApplication
{
protected:
    bool init() override {
        auto wifiConfig = findComponent<ksWifiConfigProvider>();
        
        // Require WiFi config
        if (!wifiConfig || !wifiConfig->hasParam("ssid")) {
            return false;  // Go to setup
        }
        
        wifiConfig->load();
        addComponent<ksWifiConnector>("MyDevice");
        return true;
    }
};

Pattern 2: Optional Configuration with Defaults

class MyApp : public ksApplication
{
protected:
    bool init() override {
        auto config = addComponent<MyAppConfig>();
        
        // Load or create defaults
        if (!config->load()) {
            config->setParam("interval", "5000");
            config->setParam("enabled", "true");
            config->save();
        }
        
        return true;
    }
};

Pattern 3: Runtime Configuration Updates

bool loop() override {
    auto mqtt = findComponent<ksMqttConnector>();
    
    mqtt->onMessage([this](auto topic, auto payload) {
        if (strcmp(topic, "device/config") == 0) {
            // Update configuration
            auto config = findComponent<MyAppConfig>();
            config->setParam("interval", payload);
            config->save();
        }
    });
    
    return true;
}

---

🔐 Configuration Security

Sensitive Data

What's Stored:

• WiFi passwords
• MQTT credentials
• API keys

Protection:

• File system on device (not in code)
• Never logged or transmitted
• Accessible only via local network

Best Practices:

// ❌ Bad - Hardcoded credentials
String ssid = "MyNetwork";
String password = "password123";

// ✅ Good - From configuration
auto config = findComponent<ksWifiConfigProvider>();
String ssid = config->getParam("ssid");
String password = config->getParam("password");

---

🔄 Configuration Lifecycle

First Boot
    │
    ▼
No Config File
    │
    ├─► WiFi Configurator (AP mode)
    │   └─► User configures WiFi
    │
    ├─► Device Portal
    │   └─► User configures MQTT
    │
    ▼
Config Saved
    │
    ▼
Device Reboots
    │
    ▼
Config Loaded
    │
    ├─► ksWifiConnector uses WiFi config
    └─► ksMqttConnector uses MQTT config
    │
    ▼
Normal Operation

---

🛠️ Configuration Tools

Method 1: Device Portal

Web-based configuration interface:

http://device-ip
  ├─► WiFi Configuration
  ├─► MQTT Configuration
  └─► Application Settings

Method 2: Serial Monitor

View configuration via serial output:

[ksWifiConfig] Loaded: SSID=MyNetwork
[ksMqttConfig] Loaded: Broker=192.168.1.100

Method 3: mDNS Discovery

Find device on network:

# On Linux/Mac
avahi-browse _http._tcp

# On Windows
# Device shows as "MyDevice.local"

---

📖 Configuration Examples

Example 1: Full IoT Device Configuration

class IoTDevice : public ksApplication
{
protected:
    bool init() override {
        auto wifiConfig = addComponent<ksWifiConfigProvider>();
        auto mqttConfig = addComponent<ksMqttConfigProvider>();
        
        // Check configuration
        if (!wifiConfig->hasParam("ssid") || 
            !mqttConfig->hasParam("broker")) {
            return false;  // Go to config app
        }
        
        // Load configuration
        wifiConfig->load();
        mqttConfig->load();
        
        // Add components with config
        addComponent<ksWifiConnector>("IoTDevice");
        addComponent<ksMqttConnector>();
        addComponent<ksDevicePortal>();
        addComponent<ksLed>(LED_BUILTIN);
        
        return true;
    }
};

class ConfigApp : public ksApplication
{
protected:
    bool init() override {
        // Configuration mode
        addComponent<ksWifiConfigurator>();
        addComponent<ksDevicePortal>();
        addComponent<ksLed>(LED_BUILTIN);
        return true;
    }
    
    bool loop() override {
        auto wifiConfig = findComponent<ksWifiConfigProvider>();
        
        // Check if configuration complete
        if (wifiConfig->hasParam("ssid")) {
            return false;  // Back to main app
        }
        return true;
    }
};

Example 2: Application with Custom Config

class SensorApp : public ksApplication
{
protected:
    bool init() override {
        auto appConfig = addComponent<SensorAppConfig>();
        
        // Load or create defaults
        if (!appConfig->load()) {
            appConfig->setParam("interval", "10000");
            appConfig->setParam("enabled", "true");
            appConfig->save();
        }
        
        addComponent<ksWifiConnector>("Sensor");
        addComponent<ksMqttConnector>();
        addComponent<ksDevStatMqttReporter>();
        
        return true;
    }
};

---

⚠️ Common Mistakes

Don't: Hardcode Configuration

// ❌ Bad
addComponent<ksMqttConnector>();
mqtt->connect("192.168.1.100", 1883);

Don't: Forget to Save

// ❌ Bad
config->setParam("value", "123");
// Forgot: config->save();

Don't: Ignore Load Result

// ❌ Bad
config->load();  // Ignore result
String value = config->getParam("missing");  // Undefined

---

📖 Related Topics

• Components-Reference — Configuration provider components
• Device-Portal — Web-based configuration interface
• App-Rotator — Config application pattern