V0.4.0 (#4)

* Switch Library, Added Tests

* Comments, tidy up, etc, bump version

* Update README.md

* V0.4.0dev (#3)

* no password, image

* add image

* Update README.md

* Update README.md

Author: CDFER

README.md

@@ -1,11 +1,41 @@
-# ESP32 Cross Platform Captive Portal Example 
-## Built using Platformio and the Arduino C++ core
+# ESP32 Cross Platform Captive Portal ✨
 
 [![Hippocratic License HL3-CL-EXTR-FFD-MEDIA-MIL-MY-SV-TAL](https://img.shields.io/static/v1?label=Hippocratic%20License&message=HL3-CL-EXTR-FFD-MEDIA-MIL-MY-SV-TAL&labelColor=5e2751&color=bc8c3d)](https://firstdonoharm.dev/version/3/0/cl-extr-ffd-media-mil-my-sv-tal.html)
 
-ESP32 Captive Portal (think airport wifi sign in page) example that works on all devices (or that's the goal).
 
-When you connect to the wifi "captive" password "12345678" it should take you straight to <http://4.3.2.1/> and display a green page with some simple text.
+A ESP32 Captive Portal written in Arudino C++ (think airport wifi sign in page) demo that works on all devices[^1].
+
+## ⚙️ Features
+```
+RAM:   [=         ]  11.6% (used 37976 bytes from 327680 bytes)
+Flash: [==        ]  22.6% (used 711089 bytes from 3145728 bytes)
+```
+- about 0.1s reload time using modern browsers and systems
+- Lots of comments that explain how it all works
+
+## 🖼️ User interface
+![User interface](/images/banner.jpg)
+
+## 📲 Quickstart with ESP Home Flasher tool on Windows, MacOS and Linux
+
+This is a simple all in one GUI tool that can be downloaded from here: <https://github.com/esphome/esphome-flasher/releases/>
+
+Download the firmware from the releases page and chuck it in select the serial port from the dropdown and press flash ESP
+
+If running Windows , you will most likely need a driver from here: <https://www.wemos.cc/en/latest/ch340_driver.html> before your computer will show the ESP32 com port in the drop down menu in ESPhome Flasher.
+
+### Compile yourself using PlatformIO
+
+- Make sure Git client is installed on your system. https://github.com/git-guides/install-git
+- Download and install Visual Studio Code by Microsoft. https://code.visualstudio.com/download
+- Open Visual Studio Code and go to the Extensions manager (the icon with the stacked blocks in the left bar)
+- Search for platformio and install the PlatformIO extension
+- Download the source code by running a git clone (git gui can be found in your right click menu) with the link: https://github.com/CDFER/Captive-Portal-ESP32.git in your projects folder.
+- In VS Code Go to File -> Open Folder and open that root folder (the one that contains platformio.ini, NOT the src folder)
+- Upload to the esp32 using the right arrow button in the bottom left corner of vs code (it takes awhile for the first compile)
+
+
+## Testing Status
 
 | Status | Version   | Connect | Popup | Serve Page | OS                      | Device Name         | Browser | Notes                |
 |--------|-----------|---------|-------|------------|-------------------------|---------------------|---------|----------------------|
@@ -26,45 +56,50 @@ When you connect to the wifi "captive" password "12345678" it should take you st
 | ✅      | V0.1      | ✅       | ✅     | ✅          | Win 10 Edu              | XPS15 9570          | Edge    |                      |
 | ✅      | V0.1      | ✅       | ✅     | ✅          | Android 12 (OneUI4.1)   | Samsung S20 FE 5G   | Default |                      |
 
-## Quickstart with ESP Home Flasher tool on Windows, MacOS and Linux
-
-This is a simple GUI-based tool that can be downloaded from here: <https://github.com/esphome/esphome-flasher/releases/>
-
-If running Windows, you will most likely need a driver from here: <https://www.wemos.cc/en/latest/ch340_driver.html> before your computer will show the COM port in ESPhome Flasher.
-
-## Did it work?
+### Did it work?
 
 If you test this code on a device (even if it works) it would be really helpful if you fill out the form here: <https://forms.gle/ArLPTnwRA3QGTKyc6>
 
+
 ## Known Bugs/limitations with current version
 
 - Oneplus 6 phone (Oxygen OS 11) sometimes gets stuck on setting client side IP address when cellular is on
 - On older devices you may need to open a web browser for it to display
 - max of 4 clients connected at the same time
 - MacOS post macOS Big Sur no pop up
 
+
 ### Further testing required
 
 - If you have a lot of tabs open in Windows 11 (and probably other OS) it increases the load on the ESP32 DNS server.
 - HTML Webpage being served multiple times
 - Other ESP32 chip variants (all testing so far is on the ESP32 D0WDQ6 chip in the ESP32S module)
 - Test increasing the max clients connected up from 4 to max supported 10
 
+
 ### Future Dev Options to look into (Help or suggestions are appreciated):
 
 - Set client DHCP IP address range in private space (currently clients must accept DHCP Server Range: 4.3.2.2 to 4.3.2.12)
 - Support integrating the DHCP or IPv6 Router Advertisement (RA) options for Captive Portals on iOS 14+ and macOS Big Sur+ https://developer.apple.com/news/?id=q78sq5rv
 - Port https://github.com/Aircoookie/WLED-WebInstaller
 
-### Compile yourself using PlatformIO
+### My Reading List
+
+- https://www.linkedin.com/pulse/ios-7-captive-portal-guide-requirements-agathe-guib%C3%A9
+- https://developer.apple.com/news/?id=q78sq5rv
+- 
+
+
+## ✌️ Other
+
+This work was done as part of a project with Simon Ingram of Terrestrial Assemblages with the support of Govett-Brewster Art Gallery / Len Lye Centre
+
+Thanks to @me-no-dev and everyone at @Espressif Systems for making a really awesome chip and porting it to arduino
+
+Thanks to @LTRTNZ and @vincentd123 for putting up with my never ending shit and @Vincent for helping me through this crazy year
+
 
-- Make sure Git client is installed on your system.
-- Download and install Visual Studio Code by Microsoft.
-- Open VS Code and go to the Extensions manager (the icon with the stacked blocks in the left bar)
-- Search for platformio ide and install the PlatformIO extension
-- Download the source code by executing git clone https://github.com/CDFER/Captive-Portal-ESP32.git. in some folder.
-- In VS Code Go to File -> Open Folder and open that root folder (the one that contains platformio.ini, NOT the src folder)
-- Upload to the esp32 using the right arrow button in the bottom left corner of vs code
 
-Made with love by Chris Dirks (@cd_fer) in Aotearoa New Zealand
+[^1]: devices from the last 10 years, or that's the goal of this project :)
 
+Made with love by Chris Dirks (@cd_fer) in Aotearoa New Zealand

images/banner.jpg

@@ -15,7 +15,7 @@ board = esp32dev
 framework = arduino
 lib_deps = 
 	https://github.com/me-no-dev/AsyncTCP
-	ESP Async WebServer
+	https://github.com/me-no-dev/ESPAsyncWebServer
 check_skip_packages = yes # fixes inspect in platformio
 board_build.partitions = huge_app.csv # not required, increases Flash size for program
 

platformio.ini

@@ -1,14 +1,16 @@
-#include <Arduino.h>
+#include <Arduino.h> //not needed in the arduino ide
+
+//Captive Portal
 #include <DNSServer.h>
 #include <esp_wifi.h> //Used for mpdu_rx_disable android workaround
 #include <AsyncTCP.h> 	//https://github.com/me-no-dev/AsyncTCP using the latest dev version from @me-no-dev
-#include <ESPAsyncWebServer.h> //ESP Async WebServer using the latest stable version from @me-no-dev
+#include <ESPAsyncWebServer.h> //https://github.com/me-no-dev/ESPAsyncWebServer using the latest dev version from @me-no-dev
 
-#define DEBUG_SERIAL if(USE_SERIAL)Serial //don't touch, enable serial in platformio.ini
+#define DEBUG_SERIAL if(USE_SERIAL)Serial //don't touch, enable serial in platformio.ini unless you are using the arduino ide
 
-// Dependency Graph
-// |-- AsyncTCP @ 1.1.1+sha.ca8ac5f
-// |-- ESP Async WebServer @ 1.2.3
+// Dependency Graph (these are the libary versions used by this version of the code)
+// |-- AsyncTCP @ 1.1.1+sha.ca8ac5f //Latest version of the main branch
+// |-- ESP Async WebServer @ 1.2.3+sha.f71e3d4 //Latest version of the main branch
 // |   |-- AsyncTCP @ 1.1.1+sha.ca8ac5f
 // |   |-- FS @ 2.0.0
 // |   |-- WiFi @ 2.0.0
@@ -18,18 +20,23 @@
 //Pre reading on the fundamentals of captive portals https://textslashplain.com/2022/06/24/captive-portals/
 
 const char * ssid = "captive"; //FYI The SSID can't have a space in it.
-const char * password = "12345678";
+//const char * password = "12345678"; //Atleast 8 chars
+const char * password = NULL; // no password
 
-#define MAX_CLIENTS 4
-#define WIFI_CHANNEL 6 //2.4ghz channel 6
+#define MAX_CLIENTS 4 //ESP32 supports up to 10 but I have not tested it yet
+#define WIFI_CHANNEL 6 //2.4ghz channel 6 https://en.wikipedia.org/wiki/List_of_WLAN_channels#2.4_GHz_(802.11b/g/n/ax)
 
 
 const IPAddress localIP(4, 3, 2, 1); // the IP address the web server, Samsung requires the IP to be in public space
-const IPAddress gatewayIP(4, 3, 2, 1); // IP address of the network
-const IPAddress subnetMask(255,255,255,0);
+const IPAddress gatewayIP(4, 3, 2, 1); // IP address of the network should be the same as the local IP for captive portals
+const IPAddress subnetMask(255,255,255,0); //no need to change: https://avinetworks.com/glossary/subnet-mask/
+
+const String localIPURL = "http://4.3.2.1"; //a string version of the local IP with http, used for redirecting clients to your webpage
 
-const String localIPURL = "http://4.3.2.1";
 
+//WARNING IOS (and maybe macos) WILL NOT POP UP IF IT CONTAINS THE WORD "Success" https://www.esp8266.com/viewtopic.php?f=34&t=4398
+//SAFARI (IOS) there is a 128KB limit to the size of the HTML. The HTML can reference external resources/images that bring the total over 128KB
+//SAFARI (IOS) popup browser has some severe limitations (javascript disabled, cookies disabled, no .gz extension (even though gzip files are supported)) 
 const char index_html[] PROGMEM = R"=====(
   <!DOCTYPE html> <html>
     <head>
@@ -56,11 +63,11 @@ void setup(){ //the order of the code is important and it is critical the the an
   #if USE_SERIAL == true
   Serial.begin(115200);
   while (!Serial);
-  Serial.println("\n\nCaptive Test, V0.3.0dev compiled " __DATE__ " " __TIME__ " by CD_FER");
+  Serial.println("\n\nCaptive Test, V0.4.0 compiled " __DATE__ " " __TIME__ " by CD_FER"); //__DATE__ is provided by the platformio ide
   #endif
 
-  WiFi.mode(WIFI_AP);
-  WiFi.softAPConfig(localIP, gatewayIP, subnetMask); //Samsung requires the IP to be in public space
+  WiFi.mode(WIFI_AP); //access point mode
+  WiFi.softAPConfig(localIP, gatewayIP, subnetMask);
   WiFi.softAP(ssid, password, WIFI_CHANNEL, 0, MAX_CLIENTS);
 
   dnsServer.setTTL(300); //set 5min client side cache for DNS
@@ -77,33 +84,38 @@ void setup(){ //the order of the code is important and it is critical the the an
   esp_wifi_start(); //Restart WiFi
   delay(100); //this is necessary don't ask me why
 
-  //Required
-  server.on("/connecttest.txt",[](AsyncWebServerRequest *request){request->redirect("http://logout.net");}); //windows 11 captive portal workaround
+	//Required
+	server.on("/connecttest.txt",[](AsyncWebServerRequest *request){request->redirect("http://logout.net");}); //windows 11 captive portal workaround
+	server.on("/wpad.dat",[](AsyncWebServerRequest *request){request->send(404);}); //Honestly don't understand what this is but a 404 stops win 10 keep calling this repeatedly and panicking the esp32 :)
 
-  //Probably not all are Required, but some are. Others might speed things up?
-  server.on("/canonical.html",[](AsyncWebServerRequest *request){request->redirect(localIPURL);}); //firefox captive portal call home
-  server.on("/chrome-variations/seed",[](AsyncWebServerRequest *request){request->send(200);}); //chrome captive portal call home
-  server.on("/redirect",[](AsyncWebServerRequest *request){request->redirect(localIPURL);}); //microsoft redirect
-  server.on("/success.txt",[](AsyncWebServerRequest *request){request->send(200);}); //firefox captive portal call home
-  server.on("/wpad.dat",[](AsyncWebServerRequest *request){request->send(404);}); //Honestly don't understand what this is but a 404 stops win 10 keep calling this repeatedly and panicking the esp32 :)
-  server.on("/generate_204",[](AsyncWebServerRequest *request){request->redirect(localIPURL);}); //chromium? android? captive portal redirect
-  server.on("/service/update2/json",[](AsyncWebServerRequest *request){request->send(200);}); //firefox?
-  server.on("/chat",[](AsyncWebServerRequest *request){request->send(404);}); //No stop asking Whatsapp, there is no internet connection
-  server.on("/startpage",[](AsyncWebServerRequest *request){request->redirect(localIPURL);});
+	//Background responses: Probably not all are Required, but some are. Others might speed things up?
+	//A Tier (commonly used by modern systems)
+	server.on("/generate_204",[](AsyncWebServerRequest *request){request->redirect(localIPURL);}); // android captive portal redirect
+	server.on("/redirect",[](AsyncWebServerRequest *request){request->redirect(localIPURL);}); //microsoft redirect
+	server.on("/hotspot-detect.html",[](AsyncWebServerRequest *request){request->redirect(localIPURL);}); //apple call home
+	server.on("/canonical.html",[](AsyncWebServerRequest *request){request->redirect(localIPURL);}); //firefox captive portal call home
+	server.on("/success.txt",[](AsyncWebServerRequest *request){request->send(200);}); //firefox captive portal call home
+	server.on("/ncsi.txt",[](AsyncWebServerRequest *request){request->redirect(localIPURL);}); //windows call home
+
+	//B Tier (uncommon)
+	// server.on("/chrome-variations/seed",[](AsyncWebServerRequest *request){request->send(200);}); //chrome captive portal call home
+	// server.on("/service/update2/json",[](AsyncWebServerRequest *request){request->send(200);}); //firefox?
+	// server.on("/chat",[](AsyncWebServerRequest *request){request->send(404);}); //No stop asking Whatsapp, there is no internet connection
+	// server.on("/startpage",[](AsyncWebServerRequest *request){request->redirect(localIPURL);});
 
 
   //return 404 to webpage icon
   server.on("/favicon.ico",[](AsyncWebServerRequest *request){request->send(404);}); //webpage icon
 
-  //Serve Basic HTML Page WARNING IOS (and maybe macos) WILL NOT POP UP IF THIS PAGE CONTAINS THE WORD "Success" https://www.esp8266.com/viewtopic.php?f=34&t=4398
+  //Serve Basic HTML Page
   server.on("/", HTTP_ANY, [](AsyncWebServerRequest *request){
     AsyncWebServerResponse *response = request->beginResponse(200, "text/html", index_html);
-    response->addHeader("Cache-Control", "public,max-age=31536000");
+    response->addHeader("Cache-Control", "public,max-age=31536000"); //save this file to cache for 1 year (unless you refresh)
     request->send(response);
     DEBUG_SERIAL.println("Served Basic HTML Page");
-
   });
 
+  //the catch all
   server.onNotFound([](AsyncWebServerRequest *request){
     request->redirect(localIPURL);
     DEBUG_SERIAL.print("onnotfound ");
@@ -122,6 +134,6 @@ void setup(){ //the order of the code is important and it is critical the the an
 }
 
 void loop(){
-  dnsServer.processNextRequest();
-  delay(1);
+  dnsServer.processNextRequest(); //I call this atleast every 10ms in my other projects (can be higher but I haven't tested it for stability)
+  delay(1); //seems to help with stability, if you are doing other things in the loop this may not be needed
 }