mirror of
https://gitlab.com/wirelos/sprocket-plugin-web.git
synced 2025-12-14 14:01:27 +01:00
153 lines
3.9 KiB
Markdown
153 lines
3.9 KiB
Markdown
# 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. |