Update to version 3.10.0

docs/setup.md

@@ -0,0 +1,197 @@
+# Server Setup
+
+## Setting up the server
+
+```cpp
+#include <Arduino.h>
+#if defined(ESP32) || defined(LIBRETINY)
+#include <AsyncTCP.h>
+#include <WiFi.h>
+#elif defined(ESP8266)
+#include <ESP8266WiFi.h>
+#include <ESPAsyncTCP.h>
+#elif defined(TARGET_RP2040) || defined(TARGET_RP2350) || defined(PICO_RP2040) || defined(PICO_RP2350)
+#include <RPAsyncTCP.h>
+#include <WiFi.h>
+#endif
+
+#include <ESPAsyncWebServer.h>
+
+AsyncWebServer server(80);
+AsyncWebSocket ws("/ws"); // access at ws://[esp ip]/ws
+AsyncEventSource events("/events"); // event source (Server-Sent events)
+
+const char* ssid = "your-ssid";
+const char* password = "your-pass";
+
+//flag to use from web update to reboot the ESP
+bool shouldReboot = false;
+
+void onRequest(AsyncWebServerRequest *request){
+  //Handle Unknown Request
+  request->send(404);
+}
+
+void onBody(AsyncWebServerRequest *request, uint8_t *data, size_t len, size_t index, size_t total){
+  //Handle body
+}
+
+void onUpload(AsyncWebServerRequest *request, String filename, size_t index, uint8_t *data, size_t len, bool final){
+  //Handle upload
+}
+
+void onEvent(AsyncWebSocket * server, AsyncWebSocketClient * client, AwsEventType type, void * arg, uint8_t *data, size_t len){
+  //Handle WebSocket event
+}
+
+void setup(){
+  Serial.begin(115200);
+  WiFi.mode(WIFI_STA);
+  WiFi.begin(ssid, password);
+  if (WiFi.waitForConnectResult() != WL_CONNECTED) {
+    Serial.printf("WiFi Failed!\n");
+    return;
+  }
+
+  // attach AsyncWebSocket
+  ws.onEvent(onEvent);
+  server.addHandler(&ws);
+
+  // attach AsyncEventSource
+  server.addHandler(&events);
+
+  // respond to GET requests on URL /heap
+  server.on("/heap", HTTP_GET, [](AsyncWebServerRequest *request){
+    request->send(200, "text/plain", String(ESP.getFreeHeap()));
+  });
+
+  // upload a file to /upload
+  server.on("/upload", HTTP_POST, [](AsyncWebServerRequest *request){
+    request->send(200);
+  }, onUpload);
+
+  // send a file when /index is requested (SPIFFS example)
+  server.on("/index", HTTP_ANY, [](AsyncWebServerRequest *request){
+    request->send(SPIFFS, "/index.htm");
+  });
+
+  // send a file when /index is requested (LittleFS example)
+  server.on("/index", HTTP_ANY, [](AsyncWebServerRequest *request){
+    request->send(LittleFS, "/index.htm");
+  });
+
+  // Simple Firmware Update Form
+  server.on("/update", HTTP_GET, [](AsyncWebServerRequest *request){
+    request->send(200, "text/html", "<form method='POST' action='/update' enctype='multipart/form-data'><input type='file' name='update'><input type='submit' value='Update'></form>");
+  });
+  server.on("/update", HTTP_POST, [](AsyncWebServerRequest *request){
+    shouldReboot = !Update.hasError();
+    AsyncWebServerResponse *response = request->beginResponse(200, "text/plain", shouldReboot?"OK":"FAIL");
+    response->addHeader("Connection", "close");
+    request->send(response);
+  },[](AsyncWebServerRequest *request, String filename, size_t index, uint8_t *data, size_t len, bool final){
+    if(!index){
+      Serial.printf("Update Start: %s\n", filename.c_str());
+      Update.runAsync(true);
+      if(!Update.begin((ESP.getFreeSketchSpace() - 0x1000) & 0xFFFFF000)){
+        Update.printError(Serial);
+      }
+    }
+    if(!Update.hasError()){
+      if(Update.write(data, len) != len){
+        Update.printError(Serial);
+      }
+    }
+    if(final){
+      if(Update.end(true)){
+        Serial.printf("Update Success: %uB\n", index+len);
+      } else {
+        Update.printError(Serial);
+      }
+    }
+  });
+
+  // attach filesystem root at URL /fs (SPIFFS example)
+  server.serveStatic("/fs", SPIFFS, "/");
+
+  // attach filesystem root at URL /fs (LittleFS example)
+  server.serveStatic("/fs", LittleFS, "/");
+
+  // Catch-All Handlers
+  // Any request that can not find a Handler that canHandle it
+  // ends in the callbacks below.
+  server.onNotFound(onRequest);
+  server.onFileUpload(onUpload);
+  server.onRequestBody(onBody);
+
+  server.begin();
+}
+
+void loop(){
+  if(shouldReboot){
+    Serial.println("Rebooting...");
+    delay(100);
+    ESP.restart();
+  }
+  static char temp[128];
+  sprintf(temp, "Seconds since boot: %u", millis()/1000);
+  events.send(temp, "time"); //send event "time"
+}
+```
+
+**IMPORTANT**: Authentication should now use `AsyncAuthenticationMiddleware` instead of the deprecated methods. See the [Authentication with AsyncAuthenticationMiddleware](middleware.md#authentication-with-asyncauthenticationmiddleware) section.
+
+### Setup global and class functions as request handlers
+
+```cpp
+#include <Arduino.h>
+#include <ESPAsyncWebserver.h>
+#include <Hash.h>
+#include <functional>
+
+void handleRequest(AsyncWebServerRequest *request){}
+
+class WebClass {
+public :
+  AsyncWebServer classWebServer = AsyncWebServer(81);
+
+  WebClass(){};
+
+  void classRequest (AsyncWebServerRequest *request){}
+
+  void begin(){
+    // attach global request handler
+    classWebServer.on("/example", HTTP_ANY, handleRequest);
+
+    // attach class request handler
+    classWebServer.on("/example", HTTP_ANY, std::bind(&WebClass::classRequest, this, std::placeholders::_1));
+  }
+};
+
+AsyncWebServer globalWebServer(80);
+WebClass webClassInstance;
+
+void setup() {
+  // attach global request handler
+  globalWebServer.on("/example", HTTP_ANY, handleRequest);
+
+  // attach class request handler
+  globalWebServer.on("/example", HTTP_ANY, std::bind(&WebClass::classRequest, webClassInstance, std::placeholders::_1));
+}
+
+void loop() {
+
+}
+```
+
+### Methods for controlling websocket connections
+
+```cpp
+  // Disable client connections if it was activated
+  if ( ws.enabled() )
+    ws.enable(false);
+
+  // enable client connections if it was disabled
+  if ( !ws.enabled() )
+    ws.enable(true);
+```