Getting Started

Getting Started with ksIotFrameworkLib

This guide will walk you through installing ksIotFrameworkLib and creating your first IoT application.

---

📋 Prerequisites

Before you begin, ensure you have:

• PlatformIO (recommended) or Arduino IDE installed
• Basic C++ knowledge
• An ESP32 or ESP8266 development board
• USB cable for programming your device

Why PlatformIO?

PlatformIO is highly recommended because it:

• Automatically manages all dependencies
• Provides better build system integration
• Offers advanced debugging features
• Handles platform-specific configurations easily

Note: All examples in this documentation use PlatformIO configuration.

---

🔧 Installation

Method 1: PlatformIO (Recommended)

1. Create a new PlatformIO project:

   pio project init --board esp32dev

2. Add the library to your platformio.ini:

   [env:esp32dev]
   platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip
   board = esp32dev
   framework = arduino
   lib_deps = 
       cziter15/ksIotFrameworkLib

3. For ESP8266, add this build flag:

   [env:esp8266]
   platform = espressif8266
   board = d1_mini
   framework = arduino
   build_flags = 
       -D PIO_FRAMEWORK_ARDUINO_ESPRESSIF_SDK305
   lib_deps = 
       cziter15/ksIotFrameworkLib

4. Install dependencies:

   pio lib install

Method 2: Arduino Library Manager

1. Open Arduino IDE
2. Go to Sketch → Include Library → Manage Libraries
3. Search for ksIotFrameworkLib
4. Click Install

Method 3: Manual Installation

1. Clone the repository:

   git clone https://github.com/cziter15/ksIotFrameworkLib.git

2. Copy to your Arduino libraries folder:

   • Windows: Documents/Arduino/libraries
   • macOS: ~/Documents/Arduino/libraries
   • Linux: ~/Arduino/libraries

---

🚀 Quick Start

Let's create a simple LED blink application to understand the framework basics.

Step 1: Create Project Structure

my-first-project/
├── include/
│   └── MyBlinkApp.h
├── src/
│   └── main.cpp
└── platformio.ini

Step 2: Define Your Application

Create include/MyBlinkApp.h:

#pragma once
#include <ksf/ksApplication.h>

class MyBlinkApp : public ksf::ksApplication
{
protected:
    bool init() override {
        // Initialize your components here
        // Return false to signal initialization failure
        return true;
    }

    bool loop() override {
        // Main application loop
        // Return false to stop the application
        return true;
    }
};

Step 3: Implement Main Entry Point

Create src/main.cpp:

#include <ksf/ksAppRotator.h>
#include "MyBlinkApp.h"

// Use the framework's macro to implement app rotation
KSF_IMPLEMENT_APP_ROTATOR(
    MyBlinkApp
)

Step 4: Build and Upload

# Build the project
pio run

# Upload to device
pio run --target upload

# Monitor serial output
pio device monitor

Step 5: Expected Output

You should see the framework initialize:

[ksIotFrameworkLib] Application rotator starting
[ksIotFrameworkLib] Attempting to run: MyBlinkApp
[ksIotFrameworkLib] Application initialized successfully

---

🎯 Next Steps

Add LED Blink Component

Now let's make it actually blink an LED. Modify MyBlinkApp.h:

#pragma once
#include <ksf/ksApplication.h>
#include <ksf/comp/ksLed.h>
#include <ksf/comp/ksSimpleTimer.h>

class MyBlinkApp : public ksf::ksApplication
{
private:
    ksf::comps::ksLed* led;
    ksf::ksSimpleTimer* timer;

protected:
    bool init() override {
        // Add LED component for built-in LED
        addComponent<ksf::comps::ksLed>(LED_BUILTIN);
        
        // Add timer for 500ms blink interval
        addComponent<ksf::ksSimpleTimer>(500);
        
        return true;
    }

    bool postInit() override {
        // Get component references
        led = findComponent<ksf::comps::ksLed>();
        timer = findComponent<ksf::ksSimpleTimer>();
        
        return led && timer;
    }

    bool loop() override {
        if (timer->elapsed()) {
            led->toggle();
            timer->reset();
        }
        return true;
    }
};

Now upload and watch your LED blink!

---

🌐 Create a Full IoT Application

Ready for something more advanced? Let's add WiFi and MQTT support.

MQTT-Controlled LED Example

1. Update platformio.ini:

   lib_deps = 
       cziter15/ksIotFrameworkLib

2. Create MQTT LED App:

   #pragma once
   #include <ksf/ksApplication.h>
   #include <ksf/comp/ksWifiConnector.h>
   #include <ksf/comp/ksMqttConnector.h>
   #include <ksf/comp/ksLed.h>
   
   class MqttLedApp : public ksf::ksApplication
   {
   protected:
       bool init() override {
           // Add WiFi connector
           addComponent<ksf::comps::ksWifiConnector>("MyDevice");
           
           // Add MQTT connector
           addComponent<ksf::comps::ksMqttConnector>();
           
           // Add LED control
           addComponent<ksf::comps::ksLed>(LED_BUILTIN);
           
           return true;
       }
   };

3. First Boot - Configuration Mode:

   • On first boot, the device will create an access point
   • Connect to MyDevice_Config WiFi network
   • Open browser to configure WiFi and MQTT settings
   • After configuration, device restarts and connects to your network

4. Control via MQTT:

   # Turn LED on
   mosquitto_pub -h broker -t "MyDevice/led/set" -m "ON"
   
   # Turn LED off
   mosquitto_pub -h broker -t "MyDevice/led/set" -m "OFF"

---

📚 Learn More

Now that you have a basic application running:

• 🏗️ Architecture — Understand how the framework works
• 🧩 Core Concepts — Applications, Components, App Rotator
• 📦 Components Reference — Explore all built-in components
• ⚙️ Configuration — Manage device settings
• 🌐 Device Portal — Web interface and OTA updates
• 💡 Examples — More practical examples

---

🆘 Troubleshooting

Device Not Connecting to WiFi

1. Check serial monitor for error messages
2. Verify WiFi credentials are correct
3. Try resetting to configuration mode (hold reset button)

MQTT Connection Issues

1. Verify MQTT broker is accessible
2. Check broker address and port settings
3. Ensure no firewall is blocking connection

PlatformIO Build Errors

1. Clean build: pio run -t clean
2. Update PlatformIO: pip install -U platformio
3. Check platform URL for ESP32 is correct

More Help

• 📖 Check Troubleshooting page
• 🐛 Report issues on GitHub
• 💬 Join community discussions

---

📖 Full Examples Repository

Complete working examples are available in the examples directory:

• led-blink — Basic LED control
• mqtt-led — MQTT-controlled LED with full IoT stack
• And more...

Clone and explore these examples to learn best practices!

---

🎉 Congratulations! You've created your first ksIotFrameworkLib application. Continue exploring to build powerful IoT solutions!