From 25e19b4f3995f45063acee8f37df629a0544fd2b Mon Sep 17 00:00:00 2001
From: Patrick Balsiger <frupii@gmail.com>
Date: Fri, 15 Aug 2025 21:14:12 +0200
Subject: [PATCH] rework readme

---
 README.md | 164 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 151 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 90601c9..99c59cd 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,158 @@
 # Sprocket-Core
-A lightweight Arduino framework for event driven programming.  
-  
-## Concepts
-... topic based event channel / pubsub-pattern  
-... plugin system
 
+A lightweight Arduino framework for event-driven programming on ESP8266 devices, featuring a plugin architecture and task scheduling capabilities.
 
-## Sprocket Lifecycle
-TODO
+## Overview
+
+Sprocket-Core provides a modular foundation for building IoT applications with:
+- **Event-driven architecture** using a topic-based publish/subscribe pattern
+- **Plugin system** for extensible functionality
+- **Task scheduling** with priority support
+- **Network abstraction** layer for communication
+- **JSON-based messaging** system
+
+## Core Concepts
+
+### Event Channel
+The framework implements a publish/subscribe event system where components can:
+- Subscribe to topics with callback handlers
+- Publish messages to specific topics
+- Handle events asynchronously
+
+### Plugin Architecture
+Plugins extend the core functionality and can:
+- Subscribe to and publish events
+- Integrate with the task scheduler
+- Access network capabilities
+- Be dynamically activated/deactivated
+
+### Task Scheduler
+Built on TaskScheduler library with support for:
+- Priority-based task execution
+- Sleep-on-idle power management
+- Standard function callbacks
+- Layered scheduling priorities
+
+### Network Layer
+Abstract network interface supporting:
+- Connection management
+- Message broadcasting
+- Point-to-point communication
+- Scheduler integration
+
+## Architecture
+
+```
+Sprocket (EventChannel)
+├── TaskScheduler
+├── Network
+├── Plugins[]
+└── Configuration
+```
+
+## Key Components
+
+- **`Sprocket`**: Main framework class inheriting from EventChannel
+- **`EventChannel`**: Core pub/sub messaging system
+- **`Plugin`**: Base class for all framework extensions
+- **`Network`**: Abstract network communication layer
+- **`SprocketMessage`**: JSON-structured message format
+- **`TaskScheduler`**: Task management and execution
+
+## Usage Example
+
+```cpp
+#include <Sprocket.h>
+
+class MyApp : public Sprocket {
+public:
+    Task periodicTask;
+    
+    MyApp(SprocketConfig cfg) : Sprocket(cfg) {}
+    
+    Sprocket* activate(Scheduler* scheduler) {
+        // Set up periodic task
+        periodicTask.set(TASK_SECOND, TASK_FOREVER, [](){
+            Serial.println("Periodic task executed");
+        });
+        
+        scheduler->addTask(periodicTask);
+        periodicTask.enable();
+        
+        return this;
+    }
+};
+
+// Configuration
+SprocketConfig config = { 3000, 115200 }; // startup delay, baud rate
+MyApp app(config);
+
+void setup() {
+    app.activate();
+}
+
+void loop() {
+    app.loop();
+    yield();
+}
+```
+
+## Message Format
+
+Messages use a structured JSON format:
+```json
+{
+    "domain": "app",
+    "from": "device1",
+    "to": "device2",
+    "payload": "message content",
+    "topic": "sensor/data",
+    "type": 1,
+    "broadcast": 0
+}
+```
+
+## Plugin Development
+
+Create custom plugins by extending the Plugin class:
+```cpp
+class MyPlugin : public Plugin {
+public:
+    void activate(Scheduler* scheduler) override {
+        // Plugin initialization
+        subscribe("my/topic", [](String msg) {
+            // Handle incoming messages
+        });
+    }
+    
+    void onMessage(SprocketMessage msg) override {
+        // Process framework messages
+    }
+};
+```
+
+## Dependencies
+
+- Arduino framework
+- TaskScheduler library
+- ArduinoJson library
+- ESP8266 platform support
+
+## Platform Support
+
+Currently supports ESP8266 devices with Arduino framework.
+
+## Useful Commands
 
-# Useful commands
 ```sh
-# erase flash  
+# Erase flash memory
 esptool --port /dev/ttyUSB0 erase_flash
-  
-# OTA
-~/.platformio/packages/tool-espotapy/espota.py -i <espIP> -p 8266 -a <authPW> -f .pioenvs/ota/firmware.bin 
 
-```
\ No newline at end of file
+# Over-the-air (OTA) update
+~/.platformio/packages/tool-espotapy/espota.py -i <espIP> -p 8266 -a <authPW> -f .pioenvs/ota/firmware.bin
+```
+
+## License
+
+See LICENSE file for details.
+