docs: add comprehensive README with NeoPixel plugin documentation

README.md

@@ -0,0 +1,128 @@
+# Sprocket NeoPixel Plugin
+
+A comprehensive LED control plugin for the Sprocket framework, providing advanced NeoPixel strip management with pattern animations and real-time control.
+
+## Overview
+
+The NeoPixel plugin enables sophisticated control of WS2812B/NeoPixel LED strips through the Sprocket framework, featuring pattern-based animations, color management, and event-driven control.
+
+## Features
+
+- **Pattern-Based Animations**: Pre-built animation patterns with customizable parameters
+- **Real-Time Control**: Dynamic color and pattern changes through Sprocket events
+- **Configurable Strips**: Support for various strip lengths and pin configurations
+- **Brightness Control**: Adjustable brightness levels and update intervals
+- **Event Integration**: Seamless integration with Sprocket's event system
+- **JSON Configuration**: Easy setup through configuration files
+
+## Configuration
+
+```cpp
+struct NeoPixelConfig {
+    int pin = 4;              // GPIO pin for data line
+    int length = 8;           // Number of LEDs in strip
+    int brightness = 100;     // Brightness (0-255)
+    int updateInterval = 100; // Animation update rate (ms)
+    int defaultColor = 100;   // Default color value
+};
+```
+
+## Supported Patterns
+
+- **Color Wheel**: Rotating color patterns
+- **Custom Patterns**: User-defined animation sequences
+- **State-Based Control**: Dynamic pattern switching
+- **Brightness Control**: Real-time brightness adjustment
+
+## Usage Example
+
+```cpp
+#include <PixelPlugin.h>
+#include <NeoPixelConfig.h>
+
+// Basic configuration
+PixelConfig config = {
+    .pin = 4,
+    .length = 16,
+    .brightness = 128,
+    .updateInterval = 50
+};
+
+// Create plugin
+PixelPlugin pixelPlugin(config);
+
+// Activate plugin
+pixelPlugin.activate(scheduler);
+
+// Control via Sprocket events
+// Set color: publish to "pixel/color" with color value
+// Set pattern: publish to "pixel/pattern" with pattern name
+// Set brightness: publish to "pixel/brightness" with value
+```
+
+## Event Topics
+
+The plugin responds to various Sprocket events:
+
+- `pixel/color` - Set specific color
+- `pixel/pattern` - Change animation pattern
+- `pixel/brightness` - Adjust brightness
+- `pixel/animation` - Control animation state
+- `pixel/steps` - Set animation steps
+
+## Configuration File
+
+Configure the plugin via JSON files:
+
+```json
+{
+    "pin": 4,
+    "length": 16,
+    "brightness": 128,
+    "updateInterval": 50,
+    "defaultColor": 100
+}
+```
+
+## Installation
+
+1. Include the NeoPixel plugin in your Sprocket project
+2. Connect WS2812B strip to configured GPIO pin
+3. Configure strip parameters (length, brightness, etc.)
+4. Initialize and activate the plugin
+5. Control via Sprocket events
+
+## Dependencies
+
+- Sprocket-Core framework
+- Arduino framework
+- NeoPixel library
+- TaskScheduler library
+- ArduinoJson library
+
+## Platform Support
+
+- ESP8266
+- ESP32
+
+## Examples
+
+See the `examples/` directory for complete usage examples:
+- `basic/` - Basic NeoPixel setup and control
+
+## Hardware Requirements
+
+- WS2812B/NeoPixel compatible LED strip
+- Adequate power supply for LED strip
+- GPIO pin for data line connection
+
+## Power Considerations
+
+- LED strips can draw significant current
+- Ensure adequate power supply capacity
+- Consider using external power for longer strips
+- Monitor voltage levels during operation
+
+## License
+
+See LICENSE file for details.