ESP32Async · mathieucarbou · Apr 8, 2025 · Apr 4, 2025
diff --git a/examples/WebSocketEasy/WebSocketEasy.ino b/examples/WebSocketEasy/WebSocketEasy.ino
@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright 2016-2025 Hristo Gochkov, Mathieu Carbou, Emil Muratov
+
+//
+// WebSocket example using the easy to use AsyncWebSocketMessageHandler handler that only supports unfragmented messages
+//
+
+#include <Arduino.h>
+#ifdef ESP32
+#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>
+
+static AsyncWebServer server(80);
+
+// create an easy-to-use handler
+static AsyncWebSocketMessageHandler wsHandler;
+
+// add it to the websocket server
+static AsyncWebSocket ws("/ws", wsHandler.eventHandler());
+
+// alternatively you can do as usual:
+//
+// static AsyncWebSocket ws("/ws");
+// ws.onEvent(wsHandler.eventHandler());
+
+static const char *htmlContent PROGMEM = R"(
+<!DOCTYPE html>
+<html>
+<head>
+ <title>WebSocket</title>
+</head>
+<body>
+ <h1>WebSocket Example</h1>
+ <>Open your browser console!</p>
+ <input type="text" id="message" placeholder="Type a message">
+ <button onclick='sendMessage()'>Send</button>
+ <script>
+ var ws = new WebSocket('ws://192.168.4.1/ws');
+ ws.onopen = function() {
+ console.log("WebSocket connected");
+ };
+ ws.onmessage = function(event) {
+ console.log("WebSocket message: " + event.data);
+ };
+ ws.onclose = function() {
+ console.log("WebSocket closed");
+ };
+ ws.onerror = function(error) {
+ console.log("WebSocket error: " + error);
+ };
+ function sendMessage() {
+ var message = document.getElementById("message").value;
+ ws.send(message);
+ console.log("WebSocket sent: " + message);
+ }
+ </script>
+</body>
+</html>
+ )";
+static const size_t htmlContentLength = strlen_P(htmlContent);
+
+void setup() {
+ Serial.begin(115200);
+
+#ifndef CONFIG_IDF_TARGET_ESP32H2
+ WiFi.mode(WIFI_AP);
+ WiFi.softAP("esp-captive");
+#endif
+
+ // serves root html page
+ server.on("/", HTTP_GET, [](AsyncWebServerRequest *request) {
+ request->send(200, "text/html", (const uint8_t *)htmlContent, htmlContentLength);
+ });
+
+ wsHandler.onConnect([](AsyncWebSocket *server, AsyncWebSocketClient *client) {
+ Serial.printf("Client %" PRIu32 " connected\n", client->id());
+ server->textAll("New client: " + String(client->id()));
+ });
+
+ wsHandler.onDisconnect([](AsyncWebSocket *server, uint32_t clientId) {
+ Serial.printf("Client %" PRIu32 " disconnected\n", clientId);
+ server->textAll("Client " + String(clientId) + " disconnected");
+ });
+
+ wsHandler.onError([](AsyncWebSocket *server, AsyncWebSocketClient *client, uint16_t errorCode, const char *reason, size_t len) {
+ Serial.printf("Client %" PRIu32 " error: %" PRIu16 ": %s\n", client->id(), errorCode, reason);
+ });
+
+ wsHandler.onMessage([](AsyncWebSocket *server, AsyncWebSocketClient *client, const uint8_t *data, size_t len) {
+ Serial.printf("Client %" PRIu32 " data: %s\n", client->id(), (const char *)data);
+ });
+
+ wsHandler.onFragment([](AsyncWebSocket *server, AsyncWebSocketClient *client, const AwsFrameInfo *frameInfo, const uint8_t *data, size_t len) {
+ Serial.printf("Client %" PRIu32 " fragment %" PRIu32 ": %s\n", client->id(), frameInfo->num, (const char *)data);
+ });
+
+ server.addHandler(&ws);
+ server.begin();
+}
+
+static uint32_t lastWS = 0;
+static uint32_t deltaWS = 2000;
+
+void loop() {
+ uint32_t now = millis();
+
+ if (now - lastWS >= deltaWS) {
+ ws.cleanupClients();
+ ws.printfAll("now: %" PRIu32 "\n", now);
+ lastWS = millis();
+#ifdef ESP32
+ Serial.printf("Free heap: %" PRIu32 "\n", ESP.getFreeHeap());
+#endif
+ }
+}
diff --git a/platformio.ini b/platformio.ini
@@ -32,6 +32,7 @@ src_dir = examples/PerfTests
 ; src_dir = examples/Templates
 ; src_dir = examples/Upload
 ; src_dir = examples/WebSocket
+; src_dir = examples/WebSocketEasy
 
 [env]
 framework = arduino

diff --git a/src/AsyncWebSocket.h b/src/AsyncWebSocket.h
@@ -291,7 +291,7 @@ class AsyncWebSocket : public AsyncWebHandler {
  String _url;
  std::list<AsyncWebSocketClient> _clients;
  uint32_t _cNextId;
- AwsEventHandler _eventHandler{nullptr};
+ AwsEventHandler _eventHandler;
  AwsHandshakeHandler _handshakeHandler;
  bool _enabled;
 #ifdef ESP32
@@ -305,8 +305,8 @@ class AsyncWebSocket : public AsyncWebHandler {
  PARTIALLY_ENQUEUED = 2,
  } SendStatus;
 
- explicit AsyncWebSocket(const char *url) : _url(url), _cNextId(1), _enabled(true) {}
- AsyncWebSocket(const String &url) : _url(url), _cNextId(1), _enabled(true) {}
+ explicit AsyncWebSocket(const char *url, AwsEventHandler handler = nullptr) : _url(url), _cNextId(1), _eventHandler(handler), _enabled(true) {}
+ AsyncWebSocket(const String &url, AwsEventHandler handler = nullptr) : _url(url), _cNextId(1), _eventHandler(handler), _enabled(true) {}
  ~AsyncWebSocket(){};
  const char *url() const {
  return _url.c_str();
@@ -413,4 +413,86 @@ class AsyncWebSocketResponse : public AsyncWebServerResponse {
  }
 };
 
+class AsyncWebSocketMessageHandler {
+public:
+ AwsEventHandler eventHandler() const {
+ return _handler;
+ }
+
+ void onConnect(std::function<void(AsyncWebSocket *server, AsyncWebSocketClient *client)> onConnect) {
+ _onConnect = onConnect;
+ }
+
+ void onDisconnect(std::function<void(AsyncWebSocket *server, uint32_t clientId)> onDisconnect) {
+ _onDisconnect = onDisconnect;
+ }
+
+ /**
+ * Error callback
+ * @param reason null-terminated string
+ * @param len length of the string
+ */
+ void onError(std::function<void(AsyncWebSocket *server, AsyncWebSocketClient *client, uint16_t errorCode, const char *reason, size_t len)> onError) {
+ _onError = onError;
+ }
+
+ /**
+ * Complete message callback
+ * @param data pointer to the data (binary or null-terminated string). This handler expects the user to know which data type he uses.
+ */
+ void onMessage(std::function<void(AsyncWebSocket *server, AsyncWebSocketClient *client, const uint8_t *data, size_t len)> onMessage) {
+ _onMessage = onMessage;
+ }
+
+ /**
+ * Fragmented message callback
+ * @param data pointer to the data (binary or null-terminated string), will be null-terminated. This handler expects the user to know which data type he uses.
+ */
+ // clang-format off
+ void onFragment(std::function<void(AsyncWebSocket *server, AsyncWebSocketClient *client, const AwsFrameInfo *frameInfo, const uint8_t *data, size_t len)> onFragment) {
+ _onFragment = onFragment;
+ }
+ // clang-format on
+
+private:
+ // clang-format off
+ std::function<void(AsyncWebSocket *server, AsyncWebSocketClient *client)> _onConnect;
+ std::function<void(AsyncWebSocket *server, AsyncWebSocketClient *client, uint16_t errorCode, const char *reason, size_t len)> _onError;
+ std::function<void(AsyncWebSocket *server, AsyncWebSocketClient *client, const uint8_t *data, size_t len)> _onMessage;
+ std::function<void(AsyncWebSocket *server, AsyncWebSocketClient *client, const AwsFrameInfo *frameInfo, const uint8_t *data, size_t len)> _onFragment;
+ std::function<void(AsyncWebSocket *server, uint32_t clientId)> _onDisconnect;
+ // clang-format on
+
+ // this handler is meant to only support 1-frame messages (== unfragmented messages)
+ AwsEventHandler _handler = [this](AsyncWebSocket *server, AsyncWebSocketClient *client, AwsEventType type, void *arg, uint8_t *data, size_t len) {
+ if (type == WS_EVT_CONNECT) {
+ if (_onConnect) {
+ _onConnect(server, client);
+ }
+ } else if (type == WS_EVT_DISCONNECT) {
+ if (_onDisconnect) {
+ _onDisconnect(server, client->id());
+ }
+ } else if (type == WS_EVT_ERROR) {
+ if (_onError) {
+ _onError(server, client, *((uint16_t *)arg), (const char *)data, len);
+ }
+ } else if (type == WS_EVT_DATA) {
+ AwsFrameInfo *info = (AwsFrameInfo *)arg;
+ if (info->opcode == WS_TEXT) {
+ data[len] = 0;
+ }
+ if (info->final && info->index == 0 && info->len == len) {
+ if (_onMessage) {
+ _onMessage(server, client, data, len);
+ }
+ } else {
+ if (_onFragment) {
+ _onFragment(server, client, info, data, len);
+ }
+ }
+ }
+ };
+};
+
 #endif /* ASYNCWEBSOCKET_H_ */