docs: add comprehensive README with Web plugin documentation

2025-12-14 22:02:23 +01:00 · 2025-08-15 21:32:30 +02:00
parent d9a75abfe6
commit 6d66ac7d51
1 changed files with 153 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,153 @@
+# Sprocket Web Plugin
+
+A comprehensive web interface plugin for the Sprocket framework, providing HTTP server, WebSocket communication, and web-based device control capabilities.
+
+## Overview
+
+The Web plugin enables web-based interaction with Sprocket devices, offering a full-featured web server with API endpoints, WebSocket support, and file serving capabilities.
+
+## Features
+
+- **HTTP Server**: Full-featured web server with configurable ports and authentication
+- **WebSocket Support**: Real-time bidirectional communication with web clients
+- **REST API**: HTTP endpoints for device control and configuration
+- **File Serving**: Static file hosting from SPIFFS filesystem
+- **Firmware Updates**: Web-based OTA firmware update capability
+- **Authentication**: Basic HTTP authentication support
+- **Event Integration**: Seamless integration with Sprocket's event system
+
+## Components
+
+### WebServerPlugin
+Core web server functionality with configurable settings.
+
+### WebApiPlugin
+REST API endpoints and WebSocket communication.
+
+### WebConfigPlugin
+Configuration management and web-based settings.
+
+### WebUtils
+Utility functions for web operations and file handling.
+
+## Configuration
+
+```cpp
+struct WebServerConfig {
+    const char *contextPath;    // URL context path
+    const char *docRoot;        // Document root directory
+    const char *defaultFile;    // Default index file
+    int port;                   // Server port (default: 80)
+    int useBasicAuth;           // Enable authentication
+    const char *user;           // Username for auth
+    const char *password;       // Password for auth
+};
+```
+
+## Usage Example
+
+```cpp
+#include <WebServerPlugin.h>
+#include <WebApiPlugin.h>
+#include <WebServerConfig.h>
+
+// Configure web server
+WebServerConfig webConfig = {
+    .contextPath = "/",
+    .docRoot = "/www",
+    .defaultFile = "index.html",
+    .port = 80,
+    .useBasicAuth = 1,
+    .user = "admin",
+    .password = "password"
+};
+
+// Create web server plugin
+WebServerPlugin webServer(webConfig);
+
+// Create API plugin
+WebApiPlugin webApi(webServer.server);
+
+// Activate plugins
+webServer.activate(scheduler);
+webApi.activate(scheduler);
+```
+
+## Web Interface
+
+The plugin provides a complete web interface including:
+
+- **Device Dashboard**: Real-time status and control
+- **Configuration Panel**: Web-based settings management
+- **Firmware Updates**: OTA update interface
+- **API Documentation**: Interactive API explorer
+
+## API Endpoints
+
+### REST API
+- `GET /api/status` - Device status information
+- `POST /api/control` - Device control commands
+- `GET /api/config` - Current configuration
+- `POST /api/config` - Update configuration
+
+### WebSocket Events
+- Real-time device status updates
+- Live sensor data streaming
+- Interactive control commands
+- Event notifications
+
+## File Structure
+
+```
+/www/
+├── index.html          # Main dashboard
+├── script.js           # JavaScript functionality
+├── styles.css          # Styling
+├── favicon.png         # Browser icon
+└── gradients.json      # UI configuration
+```
+
+## Installation
+
+1. Include the Web plugin in your Sprocket project
+2. Configure web server settings
+3. Initialize WebServerPlugin and WebApiPlugin
+4. Activate plugins through the Sprocket scheduler
+5. Access web interface via device IP address
+
+## Dependencies
+
+- Sprocket-Core framework
+- Arduino framework
+- ESPAsyncWebServer library
+- ESPAsyncWebSocket library
+- SPIFFS filesystem support
+- TaskScheduler library
+
+## Platform Support
+
+- ESP8266
+- ESP32
+
+## Examples
+
+See the `examples/` directory for complete usage examples:
+- `basic/` - Basic web server setup and API usage
+
+## Security Considerations
+
+- Enable authentication for production use
+- Use HTTPS when possible
+- Validate all incoming requests
+- Implement rate limiting for API endpoints
+
+## Network Requirements
+
+- WiFi or Ethernet connection
+- Accessible IP address
+- Proper firewall configuration
+- DNS resolution (optional)
+
+## License
+
+See LICENSE file for details.