Add driver for ESPAsyncWebServer, which allows the library to be used on ESP32 without the current connection quirks.

In order to support this, a few more things have been moved behind the output driver abstraction layer. This
results in yet fewer lines of code to write.

TODO: More testing, before merging.

Author: tfry-git

EmbAJAX.h

@@ -28,6 +28,7 @@
 class EmbAJAXOutputDriverBase;
 class EmbAJAXElement;
 class EmbAJAXContainerBase;
+class EmbAJAXPageBase;
 
 /** @brief Abstract base class for anything shown on an EmbAJAXPage
  *
@@ -117,6 +118,13 @@ class EmbAJAXOutputDriverBase {
     virtual void printHeader(bool html) = 0;
     virtual void printContent(const char *content) = 0;
     virtual const char* getArg(const char* name, char* buf, int buflen) = 0;
+    /** Set up the given page to be served on the given path.
+     *
+     *  @param change_callback See EmbAJAXPage::handleRequest() for details.
+     */
+    virtual void installPage(EmbAJAXPageBase *page, const char *path, void (*change_callback)()=0) = 0;
+    /** Insert this hook into loop(). Takes care of the appropriate server calls, if needed. */
+    virtual void loopHook() = 0;
 
     uint16_t revision() const {
         return _revision;
@@ -163,17 +171,6 @@ class EmbAJAXOutputDriverBase {
     uint16_t next_revision;
 };
 
-// If the user has not #includ'ed a specific output driver implementation, make a good guess, here
-#if not defined (EMBAJAX_OUTUPUTDRIVER_IMPLEMENTATION)
-#if defined (ESP8266)
-#include <EmbAJAXOutputDriverESP8266.h>
-#elif defined (ESP32)
-#include <EmbAJAXOutputDriverESP32.h>
-#else
-#error No output driver available for this hardware (yet). Please implement your own (it is easy!) and submit a patch.
-#endif
-#endif
-
 /** Convenience macro to set up an EmbAJAXPage, without counting the number of elements for the template. See EmbAJAXPage::EmbAJAXPage()
  *  @param name Variable name of the page instance
  *  @param title HTML Title
@@ -546,7 +543,7 @@ template<size_t NUM> class EmbAJAXHideableContainer : public EmbAJAXElement {
 
 /** @brief A set of radio buttons (mutally exclusive buttons), e.g. for on/off, or low/mid/high, etc.
  *
- *  You can insert either the whole group into an ArudJAXPage at once, or - for more flexbile
+ *  You can insert either the whole group into an EmbAJAXPage at once, or - for more flexbile
  *  layouting - retrieve the individual buttons using() button, and insert them into the page
  *  as independent elements. */
 template<size_t NUM> class EmbAJAXRadioGroup : public EmbAJAXContainer<NUM>, public EmbAJAXRadioGroupBase {
@@ -643,13 +640,22 @@ template<size_t NUM> class EmbAJAXOptionSelect : public EmbAJAXOptionSelectBase
     const char* _labels[NUM];
 };
 
+/** @brief Absrract internal helper class
+ *
+ * Needed for internal reasons. Refer to EmbAJAXPage, instead. */
+class EmbAJAXPageBase {
+public:
+    virtual void handleRequest(void (*change_callback)()=0) = 0;
+    virtual void printPage() = 0;
+};
+
 /** @brief The main interface class
  *
  *  This is the main interface class. Create a web-page with a list of elements on it, and arrange for
  *  print() (for page loads) adn handleRequest() (for AJAX calls) to be called on requests. By default,
  *  both page loads, and AJAX are handled on the same URL, but the first via GET, and the second
  *  via POST. */
-template<size_t NUM> class EmbAJAXPage : public EmbAJAXContainer<NUM> {
+template<size_t NUM> class EmbAJAXPage : public EmbAJAXContainer<NUM>, public EmbAJAXPageBase {
 public:
     /** Create a web page.
      *  @param children list of elements on the page
@@ -659,6 +665,10 @@ template<size_t NUM> class EmbAJAXPage : public EmbAJAXContainer<NUM> {
         _title = title;
         _header_add = header_add;
     }
+    /** Duplication of print(), needed for internal reasons. Use print(), instead! */
+    void printPage() override {
+        print();
+    }
     /** Serve the page including headers and all child elements. You should arrange for this function to be called, whenever
      *  there is a GET request to the desired URL. */
     void print() const override {
@@ -672,12 +682,23 @@ template<size_t NUM> class EmbAJAXPage : public EmbAJAXContainer<NUM> {
      *                         response to the change, you should specify this function, and handle the change inside it.
      *                         This way, an update can be sent back to the client, immediately, for a smooth UI experience.
      *                         (Otherwise the client will be updated on the next poll). */
-    void handleRequest(void (*change_callback)()=0) {
+    void handleRequest(void (*change_callback)()=0) override {
         EmbAJAXBase::handleRequest(EmbAJAXContainer<NUM>::_children, NUM, change_callback);
     }
 protected:
     const char* _title;
     const char* _header_add;
 };
 
+// If the user has not #includ'ed a specific output driver implementation, make a good guess, here
+#if not defined (EMBAJAX_OUTUPUTDRIVER_IMPLEMENTATION)
+#if defined (ESP8266)
+#include <EmbAJAXOutputDriverESP8266.h>
+#elif defined (ESP32)
+#include <EmbAJAXOutputDriverESP32.h>
+#else
+#error No output driver available for this hardware (yet). Please implement your own (it is easy!) and submit a patch.
+#endif
+#endif
+
 #endif

EmbAJAXOutputDriverESP32.h

@@ -23,7 +23,7 @@
 #define EMBAJAXOUTPUTDRIVERESP32_H
 
 #include <WebServer.h>
-#define EmbAJAXOutputDriverWebserverClass Webserver
+#define EmbAJAXOutputDriverWebServerClass WebServer
 
 #include <WiFi.h>  // Makes the examples work cross-platform; not strictly needed
 

EmbAJAXOutputDriverESPAsync.h

@@ -0,0 +1,85 @@
+/**
+ * EmbAJAX - Simplistic framework for creating and handling displays and controls on a WebPage served by an Arduino (or other small device).
+ * 
+ * Copyright (C) 2018-2019 Thomas Friedrichsmeier
+ * 
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or (at
+ * your option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * 
+**/
+
+#ifndef EMBAJAXOUTPUTDRIVERESPASYNC_H
+#define EMBAJAXOUTPUTDRIVERESPASYNC_H
+
+#if defined (EMBAJAX_OUTUPUTDRIVER_IMPLEMENTATION)
+#error Duplicate definition of output driver. Fix your include-directives.
+#endif
+#define EMBAJAX_OUTUPUTDRIVER_IMPLEMENTATION
+
+// For EmbAJAXPage. Important to include after defining EMBAJAX_OUTUPUTDRIVER_IMPLEMENTATION
+#include "EmbAJAX.h"
+
+#include <ESPAsyncWebServer.h>
+
+#if defined (ESP32)
+#define EmbAJAXOutputDriverWebServerClass AsyncWebServer
+#else
+#define EmbAJAXOutputDriverWebServerClass ESPAsyncWebServer
+#endif
+
+/**  @brief Output driver implementation. This implementation works with ESPAsyncWebServer (https://github.com/me-no-dev/ESPAsyncWebServer).
+ *   
+ *   To use this class, you will have to include EmbAJAXOutputDriverESPAsync.h *before* EmbAJAX.h
+ */
+class EmbAJAXOutputDriverESPAsync : public EmbAJAXOutputDriverBase {
+public:
+    /** To register an (ESP)AsyncWebServer with EmbAJAX, simply create a (global) instance of this class. 
+        @param server pointer to the server. The class of this is usually an auto-detected sensible default for the platform, AsyncWebServer on ESP32, ESPAsyncWebServer on ESP8266. */
+    EmbAJAXOutputDriverESPAsync(EmbAJAXOutputDriverWebServerClass *server) {
+        EmbAJAXBase::setDriver(this);
+        _server = server;
+        _request = 0;
+    }
+    void printHeader(bool html) override {
+        _response = _request->beginResponseStream(html ? "text/html" : "text/json");
+    }
+    void printContent(const char *content) override {
+        _response->print(content);
+    }
+    const char* getArg(const char* name, char* buf, int buflen) override {
+        _request->arg(name).toCharArray (buf, buflen);
+        return buf;
+    }
+    void installPage(EmbAJAXPageBase *page, const char *path, void (*change_callback)()=0) override {
+        _server->on(path, [=](AsyncWebServerRequest* request) {
+             _request = request;
+             _response = 0;
+             if (_request->method() == HTTP_POST) {  // AJAX request
+                 page->handleRequest(change_callback);
+             } else {  // Page load
+                 page->printPage();
+             }
+             _request->send(_response);
+             _request = 0;
+        });
+    }
+    void loopHook() override {};
+private:
+    EmbAJAXOutputDriverWebServerClass *_server;
+    AsyncWebServerRequest *_request;
+    AsyncResponseStream *_response;
+};
+
+typedef EmbAJAXOutputDriverESPAsync EmbAJAXOutputDriver;
+
+#endif

EmbAJAXOutputDriverGeneric.h

@@ -31,12 +31,15 @@
 #error Please define EmbAJAXOutputDriverWebServerClass or #include appropriate hardware specific driver
 #endif
 
+// For EmbAJAXPage. Important to include after defining EMBAJAX_OUTUPUTDRIVER_IMPLEMENTATION
+#include "EmbAJAX.h"
+
 /**  @brief Output driver implementation. This implementation should work for most arduino web servers with minimal adjustmnets. */
-class EmbAJAXOutputDriver : public EmbAJAXOutputDriverBase {
+class EmbAJAXOutputDriverGeneric : public EmbAJAXOutputDriverBase {
 public:
     /** To register an WebServer with EmbAJAX, simply create a (globaL) instance of this class. 
         @param server pointer to the server. The class of this is usually an auto-detected sensible default for the platform, e.g. ESP8266WebServer on ESP8266. */
-    EmbAJAXOutputDriver(EmbAJAXOutputDriverWebServerClass *server) {
+    EmbAJAXOutputDriverGeneric(EmbAJAXOutputDriverWebServerClass *server) {
         EmbAJAXBase::setDriver(this);
         _server = server;
     }
@@ -54,9 +57,23 @@ class EmbAJAXOutputDriver : public EmbAJAXOutputDriverBase {
     const char* getArg(const char* name, char* buf, int buflen) override {
         _server->arg(name).toCharArray (buf, buflen);
         return buf;
+    }
+    void installPage(EmbAJAXPageBase *page, const char *path, void (*change_callback)()=0) override {
+        _server->on(path, [=]() {
+             if (_server->method() == HTTP_POST) {  // AJAX request
+                 page->handleRequest(change_callback);
+             } else {  // Page load
+                 page->printPage();
+             }
+        });
+    }
+    void loopHook() override {
+        _server->handleClient();
     };
 private:
     EmbAJAXOutputDriverWebServerClass *_server;
 };
 
+typedef EmbAJAXOutputDriverGeneric EmbAJAXOutputDriver;
+
 #endif

README.md

@@ -58,9 +58,22 @@ The following additional features may be of interest (supported as of now):
 Currently there are output drivers for ESP8266 and ESP32. However, drivers are really easy to add. All that is needed is a very
 basic abstraction across some web server calls.
 
-ESP8266 support is solid. ESP32-support is currently plagued by a bug in the ESP32's networking code, that causes incoming connections
-to fail under some circumstances (https://github.com/espressif/arduino-esp32/issues/1921).
+#### ESP32 quirks and workaround
 
+Unfortunately, ESP32-support is currently plagued by a bug in the ESP32's networking code, that causes incoming connections
+to fail under some circumstances (https://github.com/espressif/arduino-esp32/issues/1921). If you are using ESP32, and EmbAJAX
+feels sluggish, displays do not update, or the status indicator sometimes turns red, despite good network strength, you are probably
+being hit by this bug.
+
+You can work around this by using the ESPAsyncWebServer library (https://github.com/me-no-dev/ESPAsyncWebServer). To do so,
+(after installing the lib), you will need to add:
+
+```cpp
+#include <AsyncTCP.h>
+#include <EmbAJAXOutputDriverESPAsync.h>
+```
+
+**above** ```#include <EmbAJAX.h>``` in your EmbAJAX sketches. No further adjustments are needed in the examples, provided, here.
 
 ## Example sketch
 
@@ -89,23 +102,15 @@ MAKE_EmbAJAXPage(page, "EmbAJAXTest", "",
   new EmbAJAXStatic("</b></p>")
 )
 
-// This is all you need to write for the page handler
-void handlePage() {
-  if(server.method() == HTTP_POST) { // AJAX request
-    page.handleRequest(updateUI);
-  } else {  // Page load
-    page.print();
-  }
-}
-
 void setup() {
   // Example WIFI setup as an access point. Change this to whatever suits you, best.
   WiFi.mode(WIFI_AP);
   WiFi.softAPConfig (IPAddress (192,168,4,1), IPAddress (0,0,0,0), IPAddress (255,255,255,0));
   WiFi.softAP("EmbAJAXTest", "12345678");
 
   // Tell the server to serve our EmbAJAX test page on root
-  server.on("/", handlePage);
+  // installPage() abstracts over the (trivial but not uniform) WebServer-specific instructions to do so
+  driver.installPage(&page, "/", updateUI);
   server.begin();
 
   updateUI();  // initialize display
@@ -123,8 +128,8 @@ void updateUI() {
 }
 
 void loop() {
-  // handle network
-  server.handleClient();
+    // handle network. loopHook() simply calls server.handleClient(), in most but not all server implementations.
+    driver.loopHook();
 }
 
 ```
@@ -157,13 +162,18 @@ added to the ESP8266 arduino core. So check back soon (or submit your pull reque
 ## Some implementation notes
 
 Currently, the web servers for embeddables I have dealt with so far, are limited to one client at a time. Therefore, if using
-a permanent AJAX connection, all further access would be blocked. Even separate page loads from the same browser. So, instead,
+a permanent connection, all further access would be blocked. Even separate page loads from the same browser. So, instead,
 we resort to regular polling for updates. An update poll is always included, automatically, when the client sends control
 changes to the server, so in most cases, the client would still appear to be refreshed, immediately.
 
 To avoid sending all states of all controls on each request from each client, the framework keeps track of the latest "revision number"
 sent to any client. The client pings back its current revision number on each request, so only real changes have to be forwarded.
 
+Concurrent access by an arbitrary number of separate clients is the main reason behind going with AJAX, instead of WebSockets, even if the
+latter are often described as more "modern". Note that the purpoted drawback to AJAX - latency - can easily be circumventented for most use
+cases, as desribed, above. Still, it would be relatively easy to generalize the framework to also allow a WebSocket-connection. I'm not
+doing this, ATM, for fear of adding unneccessary complexity for little or no practical gain.
+
 You may have noted that the framework avoids the use of the String class, even though that would make some things easier. The reason
 for this design choice is that the overhead of using char*, here, in a sketch that may be using String, already, is low. However, if this
 framework were to rely on String, while nothing else in the sketch uses String, that would incur a significant overhead. Further, it should

examples/Blink/Blink.ino

@@ -32,23 +32,15 @@ MAKE_EmbAJAXPage(page, "EmbAJAX example - Blink", "",
   new EmbAJAXStatic("<i>FAST</i></p>")
 )
 
-// This is all you need to write for the page handler
-void handlePage() {
-  if(server.method() == HTTP_POST) { // AJAX request
-    page.handleRequest(updateUI);
-  } else {  // Page load
-    page.print();
-  }
-}
-
 void setup() {
   // Example WIFI setup as an access point. Change this to whatever suits you, best.
   WiFi.mode(WIFI_AP);
   WiFi.softAPConfig (IPAddress (192,168,4,1), IPAddress (0,0,0,0), IPAddress (255,255,255,0));
   WiFi.softAP("EmbAJAXTest", "12345678");
 
   // Tell the server to serve our EmbAJAX test page on root
-  server.on("/", handlePage);
+  // installPage() abstracts over the (trivial but not uniform) WebServer-specific instructions to do so
+  driver.installPage(&page, "/", updateUI);
   server.begin();
 
   pinMode(LEDPIN, OUTPUT);
@@ -61,8 +53,8 @@ void updateUI() {
 }
 
 void loop() {
-  // handle network
-  server.handleClient();
+  // handle network. loopHook() simply calls server.handleClient(), in most but not all server implementations.
+  driver.loopHook();
 
   // And these lines are all you have to write for the logic: Access the elements as if they were plain
   // local controls

examples/Inputs/Inputs.ino

@@ -109,23 +109,15 @@ MAKE_EmbAJAXPage(page, "EmbAJAX example - Inputs", "",
     new EmbAJAXStatic("</b></td></tr></table>")
 )
 
-// This is all you need to write for the page handler
-void handlePage() {
-    if(server.method() == HTTP_POST) { // AJAX request
-        page.handleRequest(updateUI);
-    } else {  // Page load
-        page.print();
-    }
-}
-
 void setup() {
     // Example WIFI setup as an access point. Change this to whatever suits you, best.
     WiFi.mode(WIFI_AP);
     WiFi.softAPConfig (IPAddress (192,168,4,1), IPAddress (0,0,0,0), IPAddress (255,255,255,0));
     WiFi.softAP("EmbAJAXTest", "12345678");
 
     // Tell the server to serve our EmbAJAX test page on root
-    server.on("/", handlePage);
+    // installPage() abstracts over the (trivial but not uniform) WebServer-specific instructions to do so
+    driver.installPage(&page, "/", updateUI);
     server.begin();
 
     valtext.setPlaceholder("192.168.1.1");
@@ -149,6 +141,6 @@ void updateUI() {
 }
 
 void loop() {
-    // handle network
-    server.handleClient();
+    // handle network. loopHook() simply calls server.handleClient(), in most but not all server implementations.
+    driver.loopHook();
 }