5.5 KiB
5.5 KiB
| title | description | keywords | |||||
|---|---|---|---|---|---|---|---|
| REST Server Component Documentation | Documentation for the RESTServer component which provides HTTP and WebSocket APIs for Modbus communication |
|
REST Server
Path: src/components/RestServer.cpp
Revision History: Initial documentation
The RESTServer component provides a RESTful API and WebSocket interface for interacting with the Modbus system, allowing remote monitoring and control of registers and coils. It serves static files from the filesystem and implements a comprehensive API for system monitoring and Modbus operations.
REQUIREMENTS
- WiFi or Ethernet connectivity
- ESP32 with sufficient memory for web server operation
- LittleFS filesystem for serving static files (optional, enabled via
ENABLE_LITTLEFS) - WebSocket support (optional, enabled via
ENABLE_WEBSOCKET)
FEATURES
- RESTful API for Modbus operations (read/write registers and coils)
- WebSocket interface for real-time updates and commands
- Serves static files from the filesystem (HTML, CSS, JS)
- System information and status endpoint
- Log level control
- RTU operation queue monitoring
- CORS support for cross-origin requests
- Pagination support for large datasets
- JSON-based communication format
DEPENDENCIES
- ESPAsyncWebServer - Asynchronous web server library
- AsyncJson - JSON support for the async web server
- ArduinoJson - JSON parsing and serialization
- ArduinoLog - Logging utility
- AsyncTCP - Asynchronous TCP library
- Component - Base component class
- Bridge - System bridge
- ModbusTCP - Modbus TCP implementation
- LittleFS - Filesystem for static files
graph TD
RESTServer --> ESPAsyncWebServer
RESTServer --> AsyncJson
RESTServer --> ArduinoJson
RESTServer --> ArduinoLog
RESTServer --> AsyncTCP
RESTServer --> Component
RESTServer --> Bridge
RESTServer --> ModbusTCP
RESTServer --> LittleFS[LittleFS "optional"]
RESTServer --> WebSocket[AsyncWebSocket "optional"]
BEHAVIOUR
The RESTServer handles API requests and WebSocket communications for interfacing with the Modbus system.
stateDiagram-v2
[*] --> Initialize
Initialize --> SetupRoutes
SetupRoutes --> Ready
Ready --> HandleHTTPRequest: HTTP Request
HandleHTTPRequest --> ServeStaticFile: File Request
HandleHTTPRequest --> ProcessAPICall: API Request
HandleHTTPRequest --> Ready
Ready --> HandleWebSocket: WebSocket Event
HandleWebSocket --> ProcessCommand: Message Received
HandleWebSocket --> NotifyClient: Client Connected
HandleWebSocket --> CleanupClient: Client Disconnected
HandleWebSocket --> Ready
Ready --> BroadcastUpdate: Modbus Data Changed
BroadcastUpdate --> Ready
ProcessAPICall --> ReadModbusData: GET Request
ProcessAPICall --> WriteModbusData: POST Request
ProcessCommand --> ReadModbusData: Read Command
ProcessCommand --> WriteModbusData: Write Command
TODOS
PERFORMANCE
- Consider implementing message compression for WebSocket communications to reduce bandwidth usage
- Optimize JSON serialization for large datasets to reduce memory usage
- Implement caching mechanisms for frequently accessed static files
- Add pagination for all resource-intensive endpoints to prevent memory issues
SECURITY
- Implement authentication for API endpoints and WebSocket connections
- Add rate limiting to prevent abuse
- Consider using HTTPS for encrypted communications
- Validate all input parameters more strictly
- Implement token-based authentication for long-lived WebSocket connections
COMPLIANCE
- Ensure compliance with REST API best practices
- Implement proper error handling and status codes according to HTTP standards
- Ensure WebSocket implementation complies with RFC 6455
- Consider implementing OpenAPI/Swagger documentation for API endpoints
- Add proper CORS configuration for security
RECOMMENDATIONS
- Keep WebSocket messages below the maximum size limit (currently 12KB)
- Use pagination for large datasets to avoid memory issues
- Monitor memory usage during operation, especially with large JSON responses
- Consider implementing a websocket message queue for high-traffic systems
- Add graceful disconnection handling for WebSocket clients
EXAMPLE
This is how you would initialize and mount a RESTServer component:
#ifdef ENABLE_WIFI
// Create REST server component
restServer = new RESTServer(
WiFi.localIP(), // Local IP address from WiFi
80, // HTTP port
&modbusTCP, // Modbus TCP manager
this // Owner component (Bridge)
);
if (restServer) {
components.push_back(restServer);
Log.infoln(F("REST Server initialized on port 80"));
} else {
Log.errorln(F("REST Server initialization failed"));
}
#endif