firmware-base/docs/RestServer.md

title	description	keywords
RestServer Component	RESTful API server implementation for ESP32 with WebSocket support	REST API WebSocket ESP32 Modbus AsyncWebServer

RestServer

Path: src/components/RestServer.h

Revision History: Initial documentation

The RestServer component implements a RESTful API server that interfaces with the Modbus system. It provides HTTP endpoints for accessing and manipulating Modbus registers and coils, as well as WebSocket functionality for real-time communication with clients.

REQUIREMENTS

Hardware

• ESP32 microcontroller
• WiFi connectivity

Software

• Arduino core for ESP32
• AsyncWebServer library
• AsyncJSON library
• ArduinoJSON library
• AsyncTCP library
• LittleFS for serving static files

FEATURES

• RESTful API endpoints for Modbus system interaction
• WebSocket support for real-time data updates
• System information retrieval
• Modbus coil and register access and manipulation
• Log level configuration
• File system browsing capabilities
• Static file serving from LittleFS

DEPENDENCIES

• Component - Base class for component functionality
• Bridge - Communication interface
• ModbusTCP - Modbus TCP implementation
• ESPAsyncWebServer - Asynchronous web server library
• ArduinoJSON - JSON parsing and creation library

graph TD
    RestServer --> Component
    RestServer --> Bridge
    RestServer --> ModbusTCP
    RestServer --> AsyncWebServer
    RestServer --> ArduinoJSON
    RestServer --> AsyncTCP

BEHAVIOUR

The RestServer component initializes an AsyncWebServer and sets up various RESTful API endpoints. When WebSocket support is enabled, it also initializes an AsyncWebSocket server for real-time communication.

stateDiagram-v2
    [*] --> Setup
    Setup --> Running: setup()
    Running --> ProcessRequests: loop()
    ProcessRequests --> Running
    Running --> BroadcastUpdates: WebSocket event
    BroadcastUpdates --> Running
    Running --> HandleMessage: onMessage()
    HandleMessage --> Running

The component responds to HTTP requests for system information, Modbus coil/register access, and file system operations. When WebSocket is enabled, it broadcasts updates to connected clients in real-time.

TODOS

PERFORMANCE

• Consider implementing caching mechanisms for frequently accessed data
• Optimize JSON document size based on actual needs
• Investigate memory usage during peak concurrent connections
• Consider implementing pagination for large data sets

SECURITY

• Implement authentication for API access
• Consider HTTPS support for secure communication
• Add rate limiting to prevent abuse
• Implement input validation for all API endpoints
• Consider implementing CORS protection

COMPLIANCE

• Ensure GDPR compliance for any data collected
• Follow RESTful API best practices
• Document API endpoints using OpenAPI/Swagger specification

RECOMMENDATIONS

• Use environment variables or configuration files for server settings
• Implement proper error handling and logging
• Consider implementing API versioning
• Separate API logic from server implementation for better maintainability
• Provide client-side libraries or SDK for easier integration

EXAMPLE

The following example shows how to initialize and mount the RestServer component:

#ifdef ENABLE_REST_SERVER
  IPAddress localIP = WiFi.localIP();
  restServer = new RESTServer(
      localIP,       // IP address
      80,            // Port
      modbusTCPServer, // ModbusTCP manager
      this           // Owner component
  );
  if (restServer) {
    components.push_back(restServer);
    Log.infoln(F("RESTServer initialized. IP:%s, Port:%d"),
              localIP.toString().c_str(), 80);
  } else {
    Log.errorln(F("RESTServer initialization failed."));
  }
#endif

References

${DOXYGEN_PLACEHOLDER}

${VENDOR_PLACEHOLDER}