Components Reference

Components Reference

Complete reference for all built-in components in ksIotFrameworkLib.

---

📦 Component Categories

Network & Connectivity

• ksWifiConnector — WiFi connection management
• ksWifiConfigurator — WiFi provisioning and captive portal
• ksMqttConnector — MQTT client with auto-reconnect
• ksMqttConfigProvider — MQTT configuration management

Device Management

• ksDevicePortal — Web-based device portal
• ksDevStatMqttReporter — Device status reporting
• ksConfigProvider — Configuration storage and retrieval

User Interface

• ksLed — LED control and patterns
• ksResetButton — Hardware reset button handling

---

📶 Network Components

ksWifiConnector

Manages WiFi connection with automatic reconnection logic.

Location: src/ksf/comp/ksWifiConnector.h

Purpose:

• Connects to WiFi network
• Handles connection failures
• Automatic reconnection with exponential backoff
• Connection status reporting

Constructor:

ksWifiConnector(const char* deviceName, bool enableModemSleep = true)

Parameters:

• deviceName — Device hostname (DHCP hostname)
• enableModemSleep — Enable modem power saving (default: true)

Usage:

// Add to application
addComponent<ksWifiConnector>("MyIoTDevice", true);

// Check connection
auto wifi = findComponent<ksWifiConnector>();
if (wifi->isConnected()) {
    // Device is online
}

// Get WiFi info
String ip = wifi->getIp();
String ssid = wifi->getSsid();
int rssi = wifi->getRssi();

Key Methods:

• bool isConnected() — Check if connected to WiFi
• String getIp() — Get current IP address
• String getSsid() — Get connected SSID
• int getRssi() — Get signal strength

Configuration: Uses ksWifiConfigProvider for stored credentials.

---

ksWifiConfigurator

Provides WiFi provisioning through captive portal on first boot.

Location: src/ksf/comp/ksWifiConfigurator.h

Purpose:

• Creates access point for setup
• Provides captive portal web interface
• Saves WiFi credentials
• Notifies on configuration complete

Constructor:

ksWifiConfigurator(unsigned long apTimeout = 600000)

Parameters:

• apTimeout — AP mode timeout in milliseconds (default: 10 minutes)

Usage:

// Add to config application
addComponent<ksWifiConfigurator>();

// Device creates AP: "MyDevice_Config"
// User connects and configures WiFi
// On success, saves credentials and notifies

Behavior:

1. Creates AP with SSID: [DeviceName]_Config
2. Starts DNS server for captive portal
3. Serves configuration webpage
4. Validates WiFi credentials
5. Saves to configuration
6. Triggers application restart

---

ksMqttConnector

MQTT client with automatic connection management and message handling.

Location: src/ksf/comp/ksMqttConnector.h

Purpose:

• Connects to MQTT broker
• Automatic reconnection with backoff
• Message publishing and subscribing
• QoS support
• Last Will and Testament

Constructor:

ksMqttConnector()

Usage:

// Add to application
addComponent<ksMqttConnector>();

// Use in other components
auto mqtt = findComponent<ksMqttConnector>();

// Publish message
mqtt->publish("sensor/temp", "22.5");
mqtt->publish("status", "online", true);  // Retained

// Subscribe to topic
mqtt->subscribe("device/control");

// Set message callback
mqtt->onMessage([](const char* topic, const char* payload) {
    Serial.printf("Received: %s = %s\n", topic, payload);
});

// Check connection
if (mqtt->isConnected()) {
    // Safe to publish
}

Key Methods:

• bool isConnected() — Check broker connection
• void publish(topic, payload, retain = false) — Publish message
• void subscribe(topic) — Subscribe to topic
• void onMessage(callback) — Set message handler
• void setWill(topic, message) — Set LWT

Configuration: Uses ksMqttConfigProvider for broker settings.

---

ksMqttConfigProvider

Manages MQTT broker configuration parameters.

Location: src/ksf/comp/ksMqttConfigProvider.h

Purpose:

• Stores MQTT broker address
• Stores port and credentials
• Provides configuration to ksMqttConnector

Stored Parameters:

• Broker address
• Broker port (default: 1883)
• Username (optional)
• Password (optional)
• Client ID prefix

Usage: Usually configured through Device Portal or WiFi Configurator.

---

🎛️ Device Management Components

ksDevicePortal

Web-based device portal for configuration, monitoring, and OTA updates.

Location: src/ksf/comp/ksDevicePortal.h

Purpose:

• HTTP web server for device management
• WiFi and MQTT configuration interface
• OTA firmware update page
• Device status monitoring
• Web terminal for real-time logs

Constructor:

ksDevicePortal()

Usage:

// Add to application
addComponent<ksDevicePortal>();

// Access via browser
// http://[device-ip]

Features:

• Configuration web UI
• OTA firmware upload
• Real-time device status
• WebSocket terminal
• File system browser

Access:

• Find device IP via mDNS or serial output
• Navigate to http://[ip] in browser
• No authentication (local network only)

---

ksDevStatMqttReporter

Reports device status via MQTT periodically.

Location: src/ksf/comp/ksDevStatMqttReporter.h

Purpose:

• Periodic status publishing
• Health monitoring
• Integration with home automation systems

Constructor:

ksDevStatMqttReporter(unsigned long interval = 60000)

Parameters:

• interval — Report interval in milliseconds (default: 60 seconds)

Published Topics:

• [device]/status — JSON status with:
  • Uptime
  • WiFi signal strength
  • Free memory
  • IP address
  • MQTT connection status

Usage:

// Add to application
addComponent<ksDevStatMqttReporter>(30000);  // 30 seconds

// Automatically publishes:
// MyDevice/status = {"uptime":123456,"rssi":-45,"freeheap":180000}

---

ksConfigProvider

Base class for configuration management and storage.

Location: src/ksf/comp/ksConfigProvider.h

Purpose:

• Abstract configuration storage
• JSON-based configuration files
• Parameter getters and setters
• File system management

Usage: Usually extended by specific providers:

• ksWifiConfigProvider
• ksMqttConfigProvider
• Custom application config

Key Methods:

• bool save() — Persist configuration to file
• bool load() — Load configuration from file
• String getParam(key) — Get parameter value
• void setParam(key, value) — Set parameter value

---

🎨 User Interface Components

ksLed

Simplifies LED control with patterns and states.

Location: src/ksf/comp/ksLed.h

Purpose:

• LED on/off control
• Blink patterns
• Status indication
• PWM brightness control

Constructor:

ksLed(uint8_t pin, bool pwm = false)

Parameters:

• pin — GPIO pin number
• pwm — Enable PWM brightness (default: false)

Usage:

// Add LED component
addComponent<ksLed>(LED_BUILTIN);

// Use in application
auto led = findComponent<ksLed>();

// Basic control
led->on();
led->off();
led->toggle();

// Set pattern (16-bit bitmap)
led->pattern(0b10101010);  // Fast blink
led->pattern(0b11001100);  // Slow blink
led->pattern(0b11111111);  // Solid on

// PWM brightness (if enabled)
led->setBrightness(128);  // 0-255

Patterns: Pattern is 16-bit bitmap processed at ~10Hz:

• 0b10101010 — Fast toggle
• 0b11001100 — Medium toggle
• 0b11110000 — Slow toggle
• 0b11111111 — Always on
• 0b00000000 — Always off

---

ksResetButton

Implements hardware reset button for configuration mode.

Location: src/ksf/comp/ksResetButton.h

Purpose:

• Hardware button detection
• Debouncing
• Long-press detection
• Trigger configuration mode

Constructor:

ksResetButton(uint8_t pin, int activeLevel = LOW, unsigned long longPressTime = 5000)

Parameters:

• pin — GPIO pin number
• activeLevel — Pin active level (default: LOW)
• longPressTime — Long press threshold in ms (default: 5 seconds)

Usage:

// Add reset button
addComponent<ksResetButton>(4, LOW, 5000);

// Behavior:
// - Short press: Nothing
// - Long press (5s): Clears config, triggers app rotation

Action: When long press detected:

1. Clears WiFi credentials
2. Clears MQTT configuration
3. Returns false from loop()
4. Triggers app rotation to config app

---

🔧 Utility Components

ksSimpleTimer

Simple timer utility for non-blocking delays.

Location: src/ksf/misc/ksSimpleTimer.h

Usage:

auto timer = addComponent<ksSimpleTimer>(1000);  // 1 second

bool loop() override {
    if (timer->elapsed()) {
        // Do something every second
        timer->reset();
    }
    return true;
}

---

📖 Component Examples

Example 1: Basic IoT Device

class BasicIoT : public ksApplication
{
protected:
    bool init() override {
        // WiFi connection
        addComponent<ksWifiConnector>("MyDevice");
        
        // MQTT connectivity
        addComponent<ksMqttConnector>();
        
        // Status LED
        addComponent<ksLed>(LED_BUILTIN);
        
        // Device status
        addComponent<ksDevStatMqttReporter>();
        
        return true;
    }
    
    bool postInit() override {
        auto led = findComponent<ksLed>();
        if (led) {
            led->pattern(0b11001100);  // Running indicator
        }
        return true;
    }
};

Example 2: Configurable Device

class ConfigurableDevice : public ksApplication
{
protected:
    bool init() override {
        // Check if configured
        if (!hasWiFiConfig()) {
            return false;  // Go to config app
        }
        
        // Normal mode
        addComponent<ksWifiConnector>("Device");
        addComponent<ksMqttConnector>();
        addComponent<ksDevicePortal>();  // For reconfiguration
        addComponent<ksLed>(LED_BUILTIN);
        
        return true;
    }
};

class SetupAssistant : public ksApplication
{
protected:
    bool init() override {
        // Setup mode
        addComponent<ksWifiConfigurator>();
        addComponent<ksDevicePortal>();
        addComponent<ksLed>(LED_BUILTIN);
        
        return true;
    }
    
    bool postInit() override {
        auto led = findComponent<ksLed>();
        if (led) {
            led->pattern(0b10101010);  // Config mode indicator
        }
        return true;
    }
};

Example 3: Advanced Device

class AdvancedDevice : public ksApplication
{
protected:
    bool init() override {
        // WiFi with modem sleep enabled
        addComponent<ksWifiConnector>("AdvDevice", true);
        
        // MQTT connector
        addComponent<ksMqttConnector>();
        
        // Device portal
        addComponent<ksDevicePortal>();
        
        // Status reporting every 30 seconds
        addComponent<ksDevStatMqttReporter>(30000);
        
        // Status LED
        addComponent<ksLed>(LED_BUILTIN);
        
        // Reset button on GPIO 4
        addComponent<ksResetButton>(4, LOW, 5000);
        
        return true;
    }
    
    bool postInit() override {
        // Set up MQTT callbacks
        auto mqtt = findComponent<ksMqttConnector>();
        if (mqtt) {
            mqtt->onMessage([](auto topic, auto payload) {
                // Handle commands
            });
        }
        
        // Indicate running
        auto led = findComponent<ksLed>();
        if (led) {
            led->pattern(0b11001100);
        }
        
        return true;
    }
};

---

💡 Component Usage Tips

Order of Operations

Components are initialized in order added:

bool init() override {
    // Add WiFi first (needed by others)
    addComponent<ksWifiConnector>();
    
    // Then MQTT (needs WiFi)
    addComponent<ksMqttConnector>();
    
    // Then other components
    addComponent<ksDevicePortal>();
    
    return true;
}

Optional Components

Check if optional component exists:

bool postInit() override {
    auto portal = findComponent<ksDevicePortal>();
    if (portal) {
        // Device portal available
    }
    // Continue without it
    return true;
}

Component Interactions

Components work together automatically:

• ksMqttConnector uses ksWifiConnector for network
• ksDevicePortal configures ksWifiConnector and ksMqttConnector
• ksDevStatMqttReporter needs ksMqttConnector
• ksLed can indicate status of any component

---

📖 Related Topics

• Component — Component lifecycle and creation
• Application — Managing components
• Configuration — Component configuration details
• Getting-Started — Example usage