diff --git a/README.md b/README.md index 432e16a..40dc597 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,90 @@ # WiFiManager -Espressif ESPx WiFi Connection manager with fallback web configuration portal +Espressif ESPx WiFi connection manager with a fallback web configuration portal. -## ⚠️ Fork Notice +## Fork notice -**This is a fork with breaking changes.** This fork has been modified and optimized specifically for PlatformIO usage. +**This is a fork with breaking changes.** The web portal is built with **DFTE** ([Device Framework Template Engine](https://github.com/alexhopeoconnor/DFTE)): composable templates and chunked HTML responses instead of upstream’s monolithic string assembly. -**Repository:** [alexhopeoconnor/WiFiManager](https://github.com/alexhopeoconnor/WiFiManager) +**This repository:** [alexhopeoconnor/WiFiManager](https://github.com/alexhopeoconnor/WiFiManager) -**For the original, unmodified version of WiFiManager, please visit the upstream repository:** -- [tzapu/WiFiManager](https://github.com/tzapu/WiFiManager) +**Upstream (original):** [tzapu/WiFiManager](https://github.com/tzapu/WiFiManager) -This fork may contain breaking changes and is not compatible with the upstream version. Use at your own risk. +## Dependencies -## Authors +**DFTE** is required and is declared in `library.json` (PlatformIO / `lib_deps` pick it up automatically). For **this repo’s** `platformio.ini` tests, a **sibling checkout** is expected: -- **Alex Hope-O'Connor** ([@alexhopeoconnor](https://github.com/alexhopeoconnor)) - Fork maintainer -- Original work by **tzapu** and contributors +```ini +lib_deps = + ESP32Async/ESPAsyncWebServer@3.9.1 + symlink://../DFTE +``` -## Installation +Clone `DFTE` next to `WiFiManager` (same parent directory), or point `lib_deps` at the Git URL used in `library.json`. -This fork is optimized for PlatformIO. Add to your `platformio.ini`: +Other pinned dependency: **ESP32Async/ESPAsyncWebServer** (see `library.json`). + +## Installation (PlatformIO) ```ini [env:your_environment] -platform = espressif8266 ; or espressif32 -board = d1_mini ; your board +platform = espressif8266 ; or espressif32 +board = d1_mini ; your board framework = arduino -lib_deps = - path = ../../../WiFiManager ; Relative path to this library +lib_deps = + https://github.com/alexhopeoconnor/WiFiManager.git ``` +Or a local path: + +```ini +lib_deps = + file:///path/to/WiFiManager +``` + +## HTML customization (DFTE) + +- **Page shell and routes** stream through DFTE (`TemplateRenderer` + chunked responses). Per-request bundles use their own `PlaceholderRegistry` for dynamic sections; the server also keeps a **shared** registry for defaults (`%STYLES%`, `%SCRIPTS%`, `%PAGE_TITLE%`, `%SUBTITLE%`, `%MENU%`, `%STATUS%`, …). +- **`WM_TEMPLATE_REGISTRY_CAPACITY`** (default in `WiFiManagerServer.h`) sizes the shared registry; raise it if you register many custom placeholders. +- **Override the root document template:** define **`WM_CUSTOM_ROOT_TEMPLATE_HEADER`** to a **quoted** include path (see `lib/WiFiManager/include/templates/RootSelector.h`). By default it includes `Root.h` (`WM_ROOT_TEMPLATE`). +- **Advanced / tests:** `WiFiManagerServer::instance()` exposes the same hooks after the server exists; prefer the `WiFiManager` methods below for typical apps. + +### `WiFiManager` API + +```cpp +wm.registerTemplateSetupCallback([](PlaceholderRegistry& reg) { + // reg.registerProgmemData(...), registerRamData, registerDynamicTemplate, etc. +}); +wm.rebuildPlaceholderRegistry(); // optional: after changing callback while portal runs +``` + +`registerTemplateSetupCallback` may be called **before** `startConfigPortal` / `startWebPortal` (stored until the HTTP server is created). If the portal is **already** running, the callback is applied and the shared registry is **rebuilt** so changes take effect. + +`rebuildPlaceholderRegistry(customizer)` forwards to the server when present: rebuilds defaults, then runs your optional one-shot customizer, or the registered setup callback if `customizer` is null. + +### Content built as `String` / PROGMEM fragments + +Some small HTML snippets (status messages, OTA blurb, help table, etc.) are still assembled in RAM or pulled from `HTML.h` and then injected into templates. That is **intentional**: not every line of markup needs its own placeholder or registry churn. Customize those via DFTE where it pays off (shell, branding, layout); keep trivial blobs as strings when appropriate. + +## Debug: WiFiManager (`DEBUG_WM`) and DFTE logging + +### How DFTE logging is designed + +DFTE keeps a **single global pointer** `deviceFrameworkTemplateEngineLogger` (see DFTE’s `DeviceFrameworkTemplateEngineDebug.h`). By default it is **`nullptr`**: every `DFTE_LOG_*` macro expands to a cheap null check and does nothing—no virtual calls, no strings, no flash cost. A host (sketch or library) implements `DeviceFrameworkTemplateEngineLogger` (virtual `error` / `warn` / `info` / `debug`) and calls `deviceFrameworkTemplateEngineEnableLogging(&myLogger)` once. Until then, DFTE is silent on the happy path; internal code mostly uses `DFTE_LOG_ERROR` and `DFTE_LOG_WARN` when something is wrong. + +### WiFiManager today + +- **`DEBUG_WM`**: compile-time gated with **`WM_DEBUG_LEVEL`** (see commented `#define WM_DFTE_LOGGING` / `WM_DEBUG_LEVEL` in `WiFiManager.h`). At runtime, `_debug`, `_debugLevel`, `_debugPrefix`, and `_debugPort` control volume and destination (`Serial` unless **`WM_DEBUG_PORT`** is set). This is tuned for **firmware size** (strip verbose strings when the macro is absent) and familiar serial prefixes (`*wm:`). +- **`WM_DFTE_LOGGING`** (build flag, **off by default**): when defined, `WiFiManagerServer::setupTemplateEngine()` registers **`WiFiManagerDfteLogger`**, which forwards DFTE messages into **`DEBUG_WM`** with a `[DFTE]` prefix and WM levels (error → `WM_DEBUG_ERROR`, warn → `WM_DEBUG_NOTIFY`, info → `WM_DEBUG_VERBOSE`, debug → `WM_DEBUG_DEV`). If **`deviceFrameworkTemplateEngineIsLoggingEnabled()`** is already true (for example **DeviceFramework** installed `WebInterfaceTemplateEngineLogger` first), WiFiManager **does not replace** that sink; it only owns teardown when it installed its own. **`shutdownServer()`** disables logging and drops the adapter only when WiFiManager installed it—avoiding clobbering a host logger on portal shutdown. + +Use **`pio test -e esp8266_dfte_log --without-uploading --without-testing`** in this repo to compile the test firmware with **`WM_DFTE_LOGGING`** enabled. + +### Should WiFiManager’s logging be refactored to match DFTE’s hook style? + +**Not as a big-bang rewrite.** DFTE’s model fits a **small library** with one pipeline: optional sink, zero cost when disabled. WiFiManager has **hundreds** of `DEBUG_WM` sites and relies on **`#ifdef WM_DEBUG_LEVEL`** to remove entire print paths from the binary. Replacing that with only a runtime pointer would either **regain flash/RAM** for the strings or require keeping both mechanisms. + +A practical middle path (what we did here) is: **keep `DEBUG_WM` + `WM_DEBUG_LEVEL` for WM-native traces**, and **optionally bridge DFTE into the same stream** with `WM_DFTE_LOGGING`. If you later want a unified sink for *both*, a small internal `WiFiManagerLogSink` interface *behind* `DEBUG_WM` could forward to `Serial` or a custom `Print`—that is incremental and does not force every call site through a virtual function in release builds. + ## License -See [LICENSE](LICENSE) file for details. +See [LICENSE](LICENSE). diff --git a/extras/WiFiManager.template.html b/extras/WiFiManager.template.html deleted file mode 100644 index 934c033..0000000 --- a/extras/WiFiManager.template.html +++ /dev/null @@ -1,400 +0,0 @@ - - - - - - {v} - - - - - - - - - - -
- - - -

/

- - - - -

-

-

-

-

-

-

-

-

-

-

- - -

/wifi

-
Access Point 01
-
Access Point 02
-
Access Point 03
-
Access Point 04
-
Access Point 05
-
Access Point 06
-
Access Point 07
-
Access Point 08
-
Access Point 09
-
Access Point 10
100%
-
Access Point 11
70%
-
Access Point 12
10%
-
Access Point 13
100%
-
Access Point 14
66%
-
Access Point 15
56%
- - -
{v}
- - -



- - -

custom parameter

-
-
- - -
- - -
- - -
- - -
- - -

Saving Credentials

Trying to connect ESP to network.
If it fails reconnect to AP to try again
- - -
Connected to {v}
with IP {i}
- - -
Not Connected to {v}{r}
- - -
Not Connected to apname - - -
Authentication Failure - - -
AP not found - - -
Could not Connect - -
- -
No AP set
- - -

H4 Color Header P

content
- - -

H4 Color Header S

content
- - -

Heading 1

-

Heading 2

-

Heading 3

-

Heading 4

-

WIFI HEAD (WIFI_OFF)

-
-
Chip ID
123456
-
Flash Chip ID
1234556
-
IDE Flash Size
4194304 bytes
-
Real Flash Size
4194304 bytes
-
Empty
-
Soft AP IP
192.168.4.1
-
Soft AP MAC
00:00:00:00:00:00
-
Station MAC
00:00:00:00:00:00
-
- - -

Available Pages

- - - - - - - - - - - - - - - - - - - - -
PageFunction
/Menu page.
/wifiShow WiFi scan results and enter WiFi configuration.(/0wifi noscan)
/wifisaveSave WiFi configuration information and configure device. Needs variables supplied.
/closeClose the configuration server and configuration WiFi network.
/infoInformation page
/closeClose the captiveportal popup,configportal will remain active
/exitExit Config Portal, configportal will close
/restartReboot the device
/eraseErase WiFi configuration and reboot Device. Device will not reconnect to a network until new WiFi configuration data is entered.
-

About

- Version v1.x.x-xxxxx
- Build_date
- Build_file
- Arduino_version
-

Github https://github.com/tzapu/WiFiManager - - -

Form UPLOAD
-

- - - * Upload may not function inside captive portal, Open in browser - http://192.168.4.1 - - - - -


-
- -
- -
- - - - - -
- - -

Select Choice

- -
- -
- - -
- - - -
- - - - -
- - - diff --git a/extras/parse.js b/extras/parse.js deleted file mode 100644 index 97a3e38..0000000 --- a/extras/parse.js +++ /dev/null @@ -1,60 +0,0 @@ -'use strict'; - -const fs = require('fs'); - -console.log('starting'); - -const inFile = 'WiFiManager.template.html'; -const outFile = 'template.h'; - -const defineRegEx = //gm; -console.log('parsing', inFile); - -fs.readFile(inFile, 'utf8', function (err,data) { - if (err) { - return console.log(err); - } - //console.log(data); - - let defines = data.match(defineRegEx); - - //console.log(defines); - var stream = fs.createWriteStream(outFile); - stream.once('open', function(fd) { - for (const i in defines) { - - const start = defines[i]; - const end = start.replace(' -
-
Access Point 01
-
Access Point 02
-
Access Point 03
-
Access Point 04
-
Access Point 05
-
Access Point 06
-
Access Point 07
-
Access Point 08
-
Access Point 09
-
Access Point 10
-
Access Point 11
-
Access Point 12
-
Access Point 13
-
Access Point 14
-
-
- -
- -
-
- -
- -
- -
-
- -
- -
- -
-
- -
-
-
Scan
-
- - - diff --git a/lib/WiFiManager/include/WiFiManager.h b/lib/WiFiManager/include/WiFiManager.h index 734c277..09790d5 100644 --- a/lib/WiFiManager/include/WiFiManager.h +++ b/lib/WiFiManager/include/WiFiManager.h @@ -21,9 +21,11 @@ #endif #include +#include #include "WiFiManagerParameter.h" +// #define WM_DFTE_LOGGING // opt-in: register a DFTE log sink that forwards to DEBUG_WM (see README) // #define WM_MDNS // includes MDNS, also set MDNS with sethostname // #define WM_FIXERASECONFIG // use erase flash fix // #define WM_ERASE_NVS // esp32 erase(true) will erase NVS @@ -126,7 +128,7 @@ #include #include #include - +#include // Include utility functions #include "WiFiManagerUtils.h" @@ -196,10 +198,12 @@ const char WM_VERSION_STR[] PROGMEM = "v2.0.18"; // Forward declarations class WiFiManagerServer; class WiFiManagerHandlers; +class WiFiManagerDfteLogger; class WiFiManager { public: + // Forward declare nested class - defined later after WM_WebServer is available class WiFiManagerRequestArgs; @@ -432,6 +436,13 @@ class WiFiManager // set the webapp title, default WiFiManager void setTitle(String title); + // DFTE (portal HTML): register extra placeholders or override defaults (%STYLES%, %PAGE_TITLE%, …). + // Call before startConfigPortal / startWebPortal to have it applied when the server starts; if the + // portal is already running, the shared registry is rebuilt immediately. + void registerTemplateSetupCallback(std::function cb); + // Rebuild the server’s shared PlaceholderRegistry (defaults + registerTemplateSetupCallback, or customizer if passed). + void rebuildPlaceholderRegistry(std::function customizer = nullptr); + // add params to its own menu page and remove from wifi, NOT TO BE COMBINED WITH setMenu! void setParamsPage(bool enable); @@ -565,6 +576,7 @@ class WiFiManager protected: // vars std::unique_ptr _serverManager; + std::function _templateSetupCallback; // ip configs @todo struct ? IPAddress _ap_static_ip; @@ -827,6 +839,7 @@ protected: #endif protected: + friend class WiFiManagerDfteLogger; // WM_DFTE_LOGGING: bridge calls protected DEBUG_WM //helpers (rendering methods moved to WiFiManagerHandlers) boolean isIp(String str); diff --git a/lib/WiFiManager/include/WiFiManagerDfteLogger.h b/lib/WiFiManager/include/WiFiManagerDfteLogger.h new file mode 100644 index 0000000..7d174bb --- /dev/null +++ b/lib/WiFiManager/include/WiFiManagerDfteLogger.h @@ -0,0 +1,54 @@ +/** + * WiFiManagerDfteLogger.h + * + * Optional bridge from DFTE's logging hooks to WiFiManager::DEBUG_WM. + * Enabled only when the sketch / library build defines WM_DFTE_LOGGING. + */ + +#ifndef WiFiManagerDfteLogger_h +#define WiFiManagerDfteLogger_h + +#if defined(ESP8266) || defined(ESP32) + +#include +#include "WiFiManager.h" + +/** + * Forwards DeviceFrameworkTemplateEngineLogger calls to WiFiManager's + * existing DEBUG_WM pipeline (respects _debug, _debugLevel, _debugPrefix, _debugPort). + */ +class WiFiManagerDfteLogger : public DeviceFrameworkTemplateEngineLogger { +public: + explicit WiFiManagerDfteLogger(WiFiManager* wm) : _wm(wm) {} + + void error(const String& msg) override { + logLine(WM_DEBUG_ERROR, msg); + } + void warn(const String& msg) override { + logLine(WM_DEBUG_NOTIFY, msg); + } + void info(const String& msg) override { + logLine(WM_DEBUG_VERBOSE, msg); + } + void debug(const String& msg) override { + logLine(WM_DEBUG_DEV, msg); + } + +private: + WiFiManager* _wm; + + void logLine(wm_debuglevel_t level, const String& msg) { + if (!_wm) { + return; + } + String line; + line.reserve(static_cast(msg.length()) + 12u); + line += F("[DFTE] "); + line += msg; + _wm->DEBUG_WM(level, line); + } +}; + +#endif // ESP8266 || ESP32 + +#endif // WiFiManagerDfteLogger_h diff --git a/lib/WiFiManager/include/WiFiManagerServer.h b/lib/WiFiManager/include/WiFiManagerServer.h index 0d026ee..9420195 100644 --- a/lib/WiFiManager/include/WiFiManagerServer.h +++ b/lib/WiFiManager/include/WiFiManagerServer.h @@ -32,6 +32,10 @@ class WiFiManager; // Forward declaration - full definition needed in .cpp file class WiFiManagerHandlers; +#ifdef WM_DFTE_LOGGING +class WiFiManagerDfteLogger; +#endif + // ----------------------------------------------------------------------------------------------- // HTTP ROUTES @@ -57,6 +61,7 @@ class WiFiManagerServer { static WiFiManagerServer* instance(); WiFiManagerServer(WiFiManager* wm); + ~WiFiManagerServer(); // Template engine setup and access void setupTemplateEngine(); @@ -115,6 +120,12 @@ class WiFiManagerServer { // Shared DFTE placeholder registry std::unique_ptr _tplRegistry; std::function _tplSetupCallback; + +#ifdef WM_DFTE_LOGGING + // DFTE -> DEBUG_WM bridge (only installed when WM_DFTE_LOGGING and no other logger registered) + std::unique_ptr _dfteLogger; + bool _wmOwnsDfteLogSink = false; +#endif // Singleton instance static WiFiManagerServer* s_instance; diff --git a/lib/WiFiManager/include/templates/HTML.h b/lib/WiFiManager/include/templates/HTML.h index 398b2d7..3d244fc 100644 --- a/lib/WiFiManager/include/templates/HTML.h +++ b/lib/WiFiManager/include/templates/HTML.h @@ -58,7 +58,7 @@ const char HTML_HELP[] PROGMEM = "/erase" "Erase WiFi configuration and reboot device. Device will not reconnect to a network until new WiFi configuration data is entered." "" - "

Github https://github.com/tzapu/WiFiManager."; + "

Fork https://github.com/alexhopeoconnor/WiFiManager."; #else const char HTML_HELP[] PROGMEM = ""; #endif diff --git a/lib/WiFiManager/library.json b/lib/WiFiManager/library.json deleted file mode 100644 index be2ae4e..0000000 --- a/lib/WiFiManager/library.json +++ /dev/null @@ -1,51 +0,0 @@ -{ - "name": "WiFiManager", - "version": "2.0.18", - "keywords": [ - "wifi", - "wi-fi", - "esp", - "esp8266", - "esp32", - "espressif8266", - "espressif32", - "nodemcu", - "wemos", - "arduino" - ], - "description": "WiFi Configuration manager with web configuration portal for ESP boards", - "authors": [ - { - "name": "tzapu", - "url": "https://github.com/tzapu" - }, - { - "name": "tablatronix", - "url": "https://github.com/tablatronix", - "maintainer": true - }, - { - "name": "Alex Hope-O'Connor", - "url": "https://github.com/alexhopeoconnor" - } - ], - "repository": { - "type": "git", - "url": "https://github.com/alexhopeoconnor/WiFiManager.git" - }, - "frameworks": "arduino", - "platforms": [ - "espressif8266", - "espressif32" - ], - "dependencies": [ - { - "name": "ESP32Async/ESPAsyncWebServer", - "version": "3.9.1" - }, - "https://github.com/alexhopeoconnor/DFTE.git" - ], - "export": { - "include": "include" - } -} \ No newline at end of file diff --git a/lib/WiFiManager/src/WiFiManager.cpp b/lib/WiFiManager/src/WiFiManager.cpp index a32e21b..ce11c4a 100644 --- a/lib/WiFiManager/src/WiFiManager.cpp +++ b/lib/WiFiManager/src/WiFiManager.cpp @@ -499,6 +499,7 @@ void WiFiManager::setupConfigPortal() { // Lazy initialization: only create server manager when config portal is actually needed if (!_serverManager) { _serverManager = std::make_unique(this); + _serverManager->registerTemplateSetupCallback(_templateSetupCallback); } _serverManager->createServer(_httpPort); _serverManager->registerRoutes(); @@ -1969,6 +1970,20 @@ void WiFiManager::setTitle(String title){ _title = title; } +void WiFiManager::registerTemplateSetupCallback(std::function cb) { + _templateSetupCallback = std::move(cb); + if (_serverManager) { + _serverManager->registerTemplateSetupCallback(_templateSetupCallback); + _serverManager->rebuildPlaceholderRegistry(); + } +} + +void WiFiManager::rebuildPlaceholderRegistry(std::function customizer) { + if (_serverManager) { + _serverManager->rebuildPlaceholderRegistry(std::move(customizer)); + } +} + /** * Set params as separate page not in wifi * NOT COMPATIBLE WITH setMenu! diff --git a/lib/WiFiManager/src/WiFiManagerServer.cpp b/lib/WiFiManager/src/WiFiManagerServer.cpp index 23b7e75..8b4f709 100644 --- a/lib/WiFiManager/src/WiFiManagerServer.cpp +++ b/lib/WiFiManager/src/WiFiManagerServer.cpp @@ -11,6 +11,10 @@ #include "WiFiManagerServer.h" #include "WiFiManager.h" #include "WiFiManagerHandlers.h" // Full definition needed for unique_ptr +#ifdef WM_DFTE_LOGGING +#include "WiFiManagerDfteLogger.h" +#include +#endif #include "templates/CSS.h" #include "templates/JS.h" #include "templates/Root.h" @@ -28,6 +32,8 @@ WiFiManagerServer::WiFiManagerServer(WiFiManager* wm) s_instance = this; } +WiFiManagerServer::~WiFiManagerServer() = default; + // Static getters for RAM placeholders (registry requires zero-arg functions) using singleton const char* WiFiManagerServer::tplGetPageTitle() { auto srv = WiFiManagerServer::instance(); @@ -128,6 +134,17 @@ void WiFiManagerServer::setupTemplateEngine() { // Allow consumers to customize placeholders applyTemplateSetupCallback(*_tplRegistry); + +#ifdef WM_DFTE_LOGGING + // Install DFTE log sink only if nothing else registered yet (e.g. DeviceFramework's bridge). + if (!deviceFrameworkTemplateEngineIsLoggingEnabled()) { + if (!_dfteLogger) { + _dfteLogger = std::make_unique(_wm); + } + deviceFrameworkTemplateEngineEnableLogging(_dfteLogger.get()); + _wmOwnsDfteLogSink = true; + } +#endif } void WiFiManagerServer::createServer(uint16_t port) { @@ -274,6 +291,16 @@ void WiFiManagerServer::processDNS() { } void WiFiManagerServer::shutdownServer() { +#ifdef WM_DFTE_LOGGING + if (_wmOwnsDfteLogSink) { + if (deviceFrameworkTemplateEngineGetLogger() == _dfteLogger.get()) { + deviceFrameworkTemplateEngineDisableLogging(); + } + _dfteLogger.reset(); + _wmOwnsDfteLogSink = false; + } +#endif + // AsyncWebServer doesn't have stop(), just reset the unique_ptr to free resources if (server) { server.reset(); diff --git a/library.json b/library.json index 7cbe8d4..4ba6d4e 100644 --- a/library.json +++ b/library.json @@ -41,7 +41,7 @@ "dependencies": [ { "name": "ESP32Async/ESPAsyncWebServer", - "version": "3.9.1" + "version": "^3.9.1" }, "https://github.com/alexhopeoconnor/DFTE.git" ], diff --git a/platformio.ini b/platformio.ini index 7a52b7a..822fe07 100644 --- a/platformio.ini +++ b/platformio.ini @@ -5,11 +5,14 @@ platform = espressif8266 board = d1_mini framework = arduino +; Postmortem jump relocation fix for large binaries (see ESP8266-LINKER-WORKAROUND.md in arduino-home-assistant) +platform_packages = + platformio/framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git#521ae60a89e64bb0d1eb7a0b7addf620ced5cad3 monitor_speed = 115200 test_framework = unity test_build_src = no lib_deps = - ESP32Async/ESPAsyncWebServer@3.9.1 + ESP32Async/ESPAsyncWebServer@^3.9.1 symlink://../DFTE [env:esp32] @@ -24,6 +27,12 @@ build_unflags = build_flags = -std=gnu++14 lib_deps = - ESP32Async/ESPAsyncWebServer@3.9.1 + ESP32Async/ESPAsyncWebServer@^3.9.1 symlink://../DFTE +; Optional: compile tests with DFTE logs bridged into DEBUG_WM (see README) +[env:esp8266_dfte_log] +extends = env:esp8266 +build_flags = + -DWM_DFTE_LOGGING +