152 lines
5.5 KiB
Markdown
152 lines
5.5 KiB
Markdown
---
|
|
title: "REST Server Component Documentation"
|
|
description: "Documentation for the RESTServer component which provides HTTP and WebSocket APIs for Modbus communication"
|
|
keywords: ["REST", "API", "WebSocket", "Modbus", "ESP32"]
|
|
---
|
|
|
|
## REST Server
|
|
|
|
**Path**: [`src/components/RestServer.cpp`](../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](https://github.com/me-no-dev/ESPAsyncWebServer) - Asynchronous web server library
|
|
- [AsyncJson](https://github.com/me-no-dev/ESPAsyncWebServer) - JSON support for the async web server
|
|
- [ArduinoJson](https://arduinojson.org/) - JSON parsing and serialization
|
|
- [ArduinoLog](https://github.com/thijse/Arduino-Log) - Logging utility
|
|
- [AsyncTCP](https://github.com/me-no-dev/AsyncTCP) - Asynchronous TCP library
|
|
- [Component](../src/Component.h) - Base component class
|
|
- [Bridge](../src/Bridge.h) - System bridge
|
|
- [ModbusTCP](../src/modbus/ModbusTCP.h) - Modbus TCP implementation
|
|
- [LittleFS](https://arduino-esp8266.readthedocs.io/en/latest/filesystem.html) - Filesystem for static files
|
|
|
|
```mermaid
|
|
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.
|
|
|
|
```mermaid
|
|
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:
|
|
|
|
```cpp
|
|
#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
|
|
```
|
|
|
|
### References
|
|
|
|
- [ESPAsyncWebServer Documentation](https://github.com/me-no-dev/ESPAsyncWebServer)
|
|
- [RFC 6455 - The WebSocket Protocol](https://tools.ietf.org/html/rfc6455)
|
|
- [RESTful API Design Guide](https://restfulapi.net/)
|
|
- [ArduinoJson Documentation](https://arduinojson.org/v6/doc/) |