Home

Welcome to ksIotFrameworkLib

ksIotFrameworkLib is a composition-oriented Internet of Things framework for Arduino ESP32/ESP8266 that provides a simple and extendable architecture, handles device setup (WiFi setup, MQTT and application-specific configuration), network connectivity, MQTT telemetry protocol, and more...

Use the sidebar to explore the framework documentation.

---

🌟 Overview

ksIotFrameworkLib is a modern Arduino library for ESP32 and ESP8266, built to support scalable and maintainable IoT applications. It eliminates the need to reinvent connectivity, configuration, and device management layers for every project.

What It Does For You

• 📶 WiFi provisioning via an automatic Access Point setup on first boot - making onboarding smooth and user-friendly
• 🌐 Robust MQTT connectivity with built-in reconnect logic - enabling effortless telemetry and remote control
• 🧩 Composition-oriented architecture - encouraging clean separation of concerns and reuse of modular components
• 🌐 Device Portal - A built-in HTTP/websocket portal for device setup, monitoring, OTA firmware updates, and terminal access
• ⚡ OTA updates - Over-the-air firmware updates through the web interface
• 📊 Status monitoring - Built-in device status reporting and health monitoring
• 🎛️ Web terminal - Interactive terminal for real-time logs and custom commands
• 🔋 Power management - Modem sleep support for reduced power consumption

Typical Use Cases

• Smart home solutions - sensors, controllers, monitoring, and alarming
• Telemetry systems - sending sensor data and device statuses
• Remote control applications - switching devices, executing commands
• IoT gateways - connecting and managing multiple IoT devices
• Home Assistant integration - MQTT-based smart home automation

Real-World Proven

Devices running on ksIotFrameworkLib have been tested in production for months without interruption, demonstrating the framework's stability and reliability. One example use case includes remote control of a heating boiler fully integrated with Home Assistant via MQTT.

---

🚀 Quick Links

For New Users

• 📘 Getting Started - Installation and your first project
• 🏗️ Architecture Overview - Understanding the framework structure
• 🧩 Core Concepts - Applications, Components, and App Rotator

Documentation

• 📦 Components Reference - All built-in components documented
• ⚙️ Configuration - Managing device configuration
• 🌐 Device Portal - Web interface and OTA updates
• 🔬 Advanced Topics - Custom RTTI, events, power saving
• 💡 Examples - Practical implementation examples

External Resources

• 📚 Doxygen Documentation - Full API reference
• 💻 GitHub Repository - Source code and issues
• 📦 PlatformIO Registry - Library registry

---

🎯 Key Features

Composition-Oriented Architecture

Build your application from reusable components. The framework provides:

• Base component class with lifecycle management
• Automatic component initialization and cleanup
• Component discovery and dependency injection
• Custom RTTI for type-safe component casting

Application Rotation

Run multiple applications on one device with automatic failover:

• Main application for device logic
• Configuration assistant for setup
• Seamless switching on errors or user action

Built-in Components

The framework includes ready-to-use components for:

• ksWifiConnector - WiFi connection management
• ksMqttConnector - MQTT client with auto-reconnect
• ksWifiConfigurator - WiFi provisioning via captive portal
• ksMqttConfigProvider - MQTT configuration management
• ksDevicePortal - Web interface for device management
• ksDevStatMqttReporter - Device status via MQTT
• ksLed - Simplified LED control
• ksResetButton - Hardware reset button handling
• ksConfigProvider - Configuration storage and retrieval

Event System

Publish-subscribe event mechanism for loose coupling between components.

---

📋 Requirements

Hardware

• ESP32 - Recommended for new projects
• ESP8266 - Supported (SDK 305 or later)

Software

• Arduino Framework - ESP32 Arduino Core 3.0+ or ESP8266 Core 3.0+
• PlatformIO - Highly recommended (auto-manages dependencies)
• C++20 - Required (uses gnu++2a standard)

Dependencies

• PubSubClient - MQTT client library -arduinoWebSockets - WebSocket support

Note: PlatformIO automatically fetches all dependencies.

---

💡 Project Example

One real-world implementation using this framework:

KS Zigbee Gateway

An all-in-one, custom-built Zigbee gateway designed to integrate with Home Assistant via ZHA. The project blends connectivity, audio alerts, and environmental sensing into a single ESP32-powered device running on ksIotFrameworkLib.

---

🤝 Contributing

Contributions are welcome! Please see the CONTRIBUTING.md in the main repository for guidelines.

📄 License

This project is licensed under the MIT - Non-AI License - see the LICENSE file for details.

ℹ️ About the Non-AI License: This license grants you the same generous permissions as the standard MIT License (allowing you to use, copy, modify, distribute, and sell the software for your projects), but with one specific restriction: the source code and documentation may not be used to train Artificial Intelligence (AI) or Machine Learning (ML) models. This helps protect the project's intellectual property from unauthorized scraping and usage by AI generators.