From 99e45ad2e5404d894dbedc772dccd1c5244e0341 Mon Sep 17 00:00:00 2001
From: Patrick Balsiger <frupii@gmail.com>
Date: Fri, 15 Aug 2025 21:32:38 +0200
Subject: [PATCH] docs: add comprehensive README with IRC plugin documentation

---
 README.md | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 140 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a43cae3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,140 @@
+# Sprocket IRC Plugin
+
+An Internet Relay Chat (IRC) integration plugin for the Sprocket framework, enabling devices to communicate through IRC channels and respond to chat commands.
+
+## Overview
+
+The IRC plugin connects Sprocket devices to IRC networks, allowing them to participate in chat channels, respond to commands, and send status updates through a familiar chat interface.
+
+## Features
+
+- **IRC Network Integration**: Connect to any IRC server and channel
+- **Command Processing**: Respond to IRC messages and commands
+- **Automatic Reconnection**: Built-in connection management and recovery
+- **Task-Based Operation**: Integrated with Sprocket's task scheduler
+- **JSON Configuration**: Easy setup through configuration files
+- **Event Integration**: Bridge between IRC chat and Sprocket events
+
+## Configuration
+
+```cpp
+struct IrcConfig {
+    const char *server;     // IRC server hostname
+    int port;               // IRC server port (usually 6667)
+    const char *nickname;   // Bot nickname on IRC
+    const char *user;       // Username for IRC registration
+};
+```
+
+## Usage Example
+
+```cpp
+#include <IrcPlugin.h>
+#include <IrcConfig.h>
+
+// Configure IRC connection
+IrcConfig ircConfig = {
+    .server = "irc.freenode.net",
+    .port = 6667,
+    .nickname = "MySprocketBot",
+    .user = "sprocket"
+};
+
+// Create and activate plugin
+IrcPlugin ircPlugin(ircConfig);
+ircPlugin.activate(scheduler);
+```
+
+## Configuration File
+
+The plugin can be configured via JSON files:
+
+```json
+{
+    "ircServer": "irc.freenode.net",
+    "ircPort": 6667,
+    "ircNickname": "MySprocketBot",
+    "ircUser": "sprocket"
+}
+```
+
+## IRC Commands
+
+The plugin can respond to various IRC commands:
+
+- **Status Requests**: Get device status information
+- **Control Commands**: Remote device control
+- **Configuration**: Update device settings
+- **System Info**: Device and network information
+
+## Message Flow
+
+### Incoming Messages
+- IRC messages are received and parsed
+- Commands are processed and executed
+- Responses are sent back to the IRC channel
+
+### Outgoing Messages
+- Device status updates can be sent to IRC
+- Event notifications are broadcast to channels
+- System alerts and error messages
+
+## Installation
+
+1. Include the IRC plugin in your Sprocket project
+2. Configure IRC server settings
+3. Initialize the plugin with your configuration
+4. Activate the plugin through the Sprocket scheduler
+5. Join desired IRC channels for communication
+
+## Dependencies
+
+- Sprocket-Core framework
+- Arduino framework
+- IRCClient library
+- WiFiClient (ESP8266/ESP32)
+- TaskScheduler library
+
+## Platform Support
+
+- ESP8266
+- ESP32
+
+## Examples
+
+See the `examples/` directory for complete usage examples:
+- `basic/` - Basic IRC bot setup and command handling
+
+## IRC Server Compatibility
+
+The plugin is compatible with most IRC servers:
+- Freenode
+- IRCNet
+- Undernet
+- EFnet
+- Custom/private servers
+
+## Security Considerations
+
+- Use private channels for sensitive commands
+- Implement command authentication if needed
+- Be mindful of IRC server rate limits
+- Consider using SSL/TLS connections when available
+
+## Network Requirements
+
+- Stable internet connection
+- Access to IRC server ports
+- Proper firewall configuration
+- DNS resolution for server hostnames
+
+## Use Cases
+
+- **Remote Monitoring**: Get device status via IRC
+- **Remote Control**: Control devices through chat commands
+- **Status Broadcasting**: Send alerts and notifications
+- **Multi-Device Coordination**: Coordinate multiple Sprocket devices
+
+## License
+
+See LICENSE file for details. 
\ No newline at end of file