docs: add comprehensive README with MQTT plugin documentation

README.md

@@ -0,0 +1,115 @@
+# Sprocket MQTT Plugin
+
+A message queuing plugin for the Sprocket framework that provides seamless integration between local Sprocket events and MQTT message brokers.
+
+## Overview
+
+The MQTT plugin enables bidirectional communication between Sprocket devices and MQTT message brokers, allowing for distributed IoT applications and cloud integration.
+
+## Features
+
+- **Bidirectional Communication**: Upstream (local → MQTT) and downstream (MQTT → local) message routing
+- **Automatic Topic Mapping**: Seamless integration between local Sprocket topics and MQTT topics
+- **Configurable Broker Settings**: Support for authentication and custom topic roots
+- **Task-Based Operation**: Integrated with Sprocket's task scheduler for reliable operation
+- **Connection Management**: Automatic reconnection with configurable retry limits
+- **JSON Configuration**: Easy setup through JSON configuration files
+
+## Configuration
+
+```cpp
+struct MqttConfig {
+    const char *clientName;    // Unique client identifier
+    const char *brokerHost;    // MQTT broker hostname/IP
+    int brokerPort;            // MQTT broker port (usually 1883)
+    const char *topicRoot;     // Topic prefix for routing
+    const char *user;          // MQTT username (optional)
+    const char *pass;          // MQTT password (optional)
+};
+```
+
+## Message Flow
+
+### Upstream (Local → MQTT)
+- Local Sprocket events are automatically published to MQTT broker
+- Topics are prefixed with the configured `topicRoot`
+- Enables cloud monitoring and logging of device events
+
+### Downstream (MQTT → Local)
+- MQTT messages are received and routed to local Sprocket topics
+- Topic prefixes are stripped for local processing
+- Allows remote control and configuration of devices
+
+## Usage Example
+
+```cpp
+#include <MqttPlugin.h>
+#include <MqttConfig.h>
+
+// Configure MQTT connection
+MqttConfig mqttConfig = {
+    .clientName = "myDevice",
+    .brokerHost = "mqtt.example.com",
+    .brokerPort = 1883,
+    .topicRoot = "home/device1",
+    .user = "username",
+    .pass = "password"
+};
+
+// Create plugin with bidirectional binding
+MqttPlugin mqttPlugin(mqttConfig, true, true);
+
+// Activate plugin
+mqttPlugin.activate(scheduler);
+```
+
+## Configuration File
+
+The plugin can also be configured via JSON files:
+
+```json
+{
+    "mqttClientName": "myDevice",
+    "mqttBrokerHost": "mqtt.example.com",
+    "mqttBrokerPort": 1883,
+    "mqttRootTopic": "home/device1",
+    "mqttUser": "username",
+    "mqttPass": "password"
+}
+```
+
+## Installation
+
+1. Include the MQTT plugin in your Sprocket project
+2. Configure MQTT broker settings
+3. Initialize the plugin with your configuration
+4. Activate the plugin through the Sprocket scheduler
+
+## Dependencies
+
+- Sprocket-Core framework
+- Arduino framework
+- PubSubClient library
+- WiFiClient (ESP8266/ESP32)
+- TaskScheduler library
+
+## Platform Support
+
+- ESP8266
+- ESP32
+
+## Examples
+
+See the `examples/` directory for complete usage examples:
+- `basic/` - Basic MQTT setup and communication
+- `chat/` - Multi-device chat application
+
+## Architecture
+
+The plugin creates a bridge between:
+- **Local Event Channel**: Sprocket's internal pub/sub system
+- **MQTT Broker**: External message queue for distributed communication
+
+## License
+
+See LICENSE file for details.