Architecture

Architecture Overview

This section explains the high-level architecture and design principles of ksIotFrameworkLib.

---

🎯 Design Philosophy

ksIotFrameworkLib is built on three core principles:

1. Composition Over Inheritance

Build applications by composing reusable components rather than creating deep inheritance hierarchies. Each component encapsulates a specific piece of functionality and can be easily combined with others.

2. Separation of Concerns

The framework separates:

• Hardware interaction from business logic
• Configuration from runtime behavior
• Network management from application logic

3. Failover Support

Applications can gracefully fall back to alternative modes (like configuration assistant) when normal operation fails.

---

🏗️ High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Arduino Framework                        │
│            (ESP32/ESP8266 Core + C++ Runtime)               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Application Rotator                       │
│         - Manages application lifecycle                     │
│         - Handles failover between apps                     │
│         - Implements setup() and loop() for Arduino         │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌──────────────────────┐         ┌──────────────────────┐
│  Main Application    │         │  Config Application  │
│  (Device Logic)      │         │  (Setup Assistant)   │
└──────────────────────┘         └──────────────────────┘
              │                               │
              └───────────────┬───────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Component Manager                        │
│              - Component lifecycle management               │
│              - Dependency resolution                        │
│              - State transitions                            │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│  ksWifiConnector│ │ ksMqttConnector │ │  ksDevicePortal │
└─────────────────┘ └─────────────────┘ └─────────────────┘
        │                    │                    │
        ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────────┐
│                   Hardware & Network                        │
│           (WiFi, MQTT, WebSockets, Files, GPIO)             │
└─────────────────────────────────────────────────────────────┘

---

📐 Framework Structure

Directory Organization

ksIotFrameworkLib/
├── src/ksf/
│   ├── Core Framework
│   │   ├── ksApplication.h/cpp       # Base application class
│   │   ├── ksComponent.h/cpp         # Base component class
│   │   ├── ksAppRotator.h            # Application rotator
│   │   ├── ksRtti.h                  # Custom RTTI system
│   │   └── ksConstants.h/cpp         # Framework constants
│   │
│   ├── Components (ksf/comp/)
│   │   ├── ksWifiConnector.h/cpp     # WiFi connection management
│   │   ├── ksWifiConfigurator.h/cpp  # WiFi provisioning
│   │   ├── ksMqttConnector.h/cpp     # MQTT client
│   │   ├── ksMqttConfigProvider.h    # MQTT configuration
│   │   ├── ksDevicePortal.h/cpp      # Web portal
│   │   ├── ksDevStatMqttReporter.h   # Device status
│   │   ├── ksLed.h/cpp               # LED control
│   │   ├── ksResetButton.h/cpp       # Reset button
│   │   └── ksConfigProvider.h        # Config base class
│   │
│   ├── Event System (ksf/evt/)
│   │   ├── ksEvent.h                 # Event implementation
│   │   ├── ksEventHandle.h           # Event handle management
│   │   └── ksEventInterface.h        # Event interface
│   │
│   ├── Utilities (ksf/misc/)
│   │   ├── ksConfig.h                # Configuration files
│   │   ├── ksSimpleTimer.h           # Timer utility
│   │   ├── ksCertUtils.h             # Certificate utilities
│   │   └── ksWSServer.h              # WebSocket server
│   │
│   └── Resources (ksf/res/)
│       └── otaWebpage                # OTA update HTML
│
└── ksIotFrameworkLib.h               # Main include header

---

🔄 Application Lifecycle

1. Arduino Bootstrap

void setup() {
    // Implemented by ksAppRotator
    // Creates first application
}

void loop() {
    // Implemented by ksAppRotator
    // Manages application switching
}

2. Application Instantiation

// App rotator creates application instance
MyApp* app = new MyApp();

3. Component Initialization

app->init() {
    // Add components
    addComponent<ksWifiConnector>();
    addComponent<ksMqttConnector>();
    // ... more components
}

4. Component Post-Init

app->postInit() {
    // Components can find dependencies
    auto mqtt = findComponent<ksMqttConnector>();
    auto led = findComponent<ksLed>();
}

5. Application Loop

app->loop() {
    // Each component's loop() is called
    for (component : components) {
        component->loop();
    }
}

6. Failover (if needed)

// If any component returns false:
delete app;
app = new ConfigApp(); // Switch to config

---

🧩 Component Architecture

Component Lifecycle

┌──────────┐
│   Created │  addComponent<T>()
└─────┬────┘
      │
      ▼
┌──────────┐
│    Init   │  init() called by app
└─────┬────┘
      │
      ▼
┌──────────┐
│ PostInit │  postInit() - find dependencies
└─────┬────┘
      │
      ▼
┌──────────┐
│  Active  │  loop() called repeatedly
└─────┬────┘
      │
      ▼ false
┌──────────┐
│ ToRemove │  marked for deletion
└─────┬────┘
      │
      ▼
┌──────────┐
│  Deleted │  memory freed
└──────────┘

Component Communication

Method 1: Direct Reference (postInit)

bool postInit() {
    auto mqtt = findComponent<ksMqttConnector>();
    if (mqtt) {
        // Use mqtt directly
    }
}

Method 2: Event System

// Publish
event->publish("button_pressed", data);

// Subscribe
event->subscribe("button_pressed", callback);

Method 3: Shared State via Application

// Store shared data in application
app->setData("sensor", value);

// Retrieve from other component
auto value = app->getData("sensor");

---

🔁 Application Rotator Pattern

The rotator enables robust multi-application scenarios:

Typical Applications

1. Main Application

   • Normal device operation
   • Reads sensors, controls actuators
   • Communicates via MQTT

2. Configuration Application

   • Activates on first boot or error
   • Provides captive portal for setup
   • Saves configuration to storage

Switching Logic

// In main application
bool init() {
    if (!hasWifiCredentials()) {
        return false;  // Trigger switch to config
    }
    return true;
}

Benefits

• Resilience: Device never gets stuck
• UX: Easy setup without reflashing
• Safety: Always recoverable to config mode

---

🎨 Memory Management

Smart Pointers

Components use smart pointers for automatic memory management:

using ComponentPtr = std::shared_ptr<ksComponent>;

// Automatically cleaned when:
// - Application is destroyed
// - Component is removed

Ownership Rules

1. Application owns components

   • Components are destroyed with application

2. Components own their resources

   • Cleanup in destructor or onRemove()

3. No manual delete needed

   • Framework handles all memory

Best Practices

// ✅ Good - Let framework manage memory
addComponent<ksLed>(LED_PIN);

// ❌ Bad - Manual memory management
ksLed* led = new ksLed(LED_PIN);  // Don't do this

---

🔀 Threading Model

Single-Threaded Execution

The framework is single-threaded by design:

void loop() {
    for (component : components) {
        component->loop();  // Sequential execution
    }
}

Implications

• No mutexes needed - Only one thread
• Predictable timing - Sequential execution
• Watchdog friendly - Always returns from loop
• Simpler debugging - No race conditions

Async Operations

For async tasks (network, MQTT):

// Component handles non-blocking I/O
bool loop() {
    mqtt->loop();  // Process available data
    wifi->loop();  // Check connection
    return true;   // Always return quickly
}

---

🔌 Extensibility Points

1. Custom Components

class MySensor : public ksComponent {
    KSF_RTTI_DECLARATIONS(MySensor, ksComponent)
    
    bool init() override {
        // Setup sensor
        return true;
    }
    
    bool loop() override {
        // Read sensor
        return true;
    }
};

2. Custom Applications

class MyApp : public ksApplication {
    bool init() override {
        addComponent<MySensor>();
        addComponent<ksMqttConnector>();
        return true;
    }
};

3. Event Handlers

event->subscribe("custom_event", [](auto data) {
    // Handle event
});

4. Configuration Providers

class MyConfigProvider : public ksConfigProvider {
    // Custom storage backend
};

---

📊 Performance Characteristics

Memory Footprint

• Base framework: ~10KB flash
• Typical app: +20-50KB for components
• RAM usage: ~30-50KB (varies by components)

CPU Usage

• Idle: Minimal (main loop overhead)
• WiFi: Active during connection/data
• MQTT: Event-driven, low overhead
• Web portal: Only when accessed

Power Consumption

• Active: ~100mA (ESP32)
• Modem sleep: ~20mA (when idle)
• Deep sleep: ~10µA (application controlled)

---

🎯 Design Trade-offs

What the Framework Does

✅ Manages WiFi connections
✅ Handles MQTT communication
✅ Provides web interface
✅ Manages configuration
✅ Handles OTA updates

What You Provide

• Application logic - Your specific device behavior
• Custom components - Specialized functionality
• Business rules - When/how to act
• Hardware integration - Sensor/actuator specifics

---

📖 Next Steps

Now that you understand the architecture:

• 🧩 Core Concepts — Deep dive into Applications and Components
• 📦 Components Reference — All built-in components
• 🎓 Examples — See architecture in action