fix: bridge nested PlatformIO async dependencies

.github/workflows/ci.yml

@@ -20,4 +20,4 @@ jobs:
         with:
           python-version: '3.11'
       - run: python -m pip install --upgrade platformio==6.1.19
-      - run: pio test -e ${{ matrix.environment }} --without-uploading --without-testing
+      - run: ./scripts/compile-check.sh --platform ${{ matrix.environment }}

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 3.0.5
+
+- Add a library-owned PlatformIO bridge for the asynchronous web/TCP include paths required when WiFiManager is nested beneath DeviceFramework.
+
+## 3.0.4
+
+- Set the package's deep PlatformIO dependency-discovery mode so WiFiManager's asynchronous web/TCP children remain available when it is consumed through DeviceFramework.
+
+## 3.0.3
+
+- Declare the ESP8266 and ESP32 async TCP libraries explicitly in the PlatformIO package manifest so clean consumers resolve the headers required by the asynchronous portal.
+
 ## 3.0.2
 
 - Update the pinned DFTE dependency to the iterator-lifecycle and configuration-safe 1.0.2 release.

README.md

@@ -8,6 +8,38 @@ If you are evaluating this fork, assume that core web-portal architecture has ch
 **This repository:** [alexhopeoconnor/WiFiManager](https://github.com/alexhopeoconnor/WiFiManager)  
 **Upstream:** [tzapu/WiFiManager](https://github.com/tzapu/WiFiManager)
 
+## Basic provisioning
+
+For a standalone Arduino project, create one long-lived `WiFiManager` and call
+`autoConnect` during setup. It first tries saved station credentials; when that
+fails it starts the configuration portal with the supplied AP name and password.
+
+```cpp
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+WiFiManager wifi;
+
+void setup() {
+    Serial.begin(115200);
+    wifi.setConfigPortalTimeout(180);  // seconds; 0 leaves it open
+
+    if (!wifi.autoConnect("Device Setup", "change-me")) {
+        ESP.restart();
+    }
+}
+
+void loop() {
+    // Normal application work after WiFi is connected.
+}
+```
+
+The AP password must meet the Wi-Fi password requirements. For applications
+built on DeviceFramework, configure `setConfigDevicePassword(...)` instead:
+DeviceFramework passes the same validated password to WiFiManager, Arduino OTA,
+HTTP Basic authentication, and WebSerial.
+
+
 ## Breaking Changes
 
 This fork intentionally modernizes and restructures the configuration portal.
@@ -168,32 +200,74 @@ Notes:
 
 This fork depends on **DFTE** ([Device Framework Template Engine](https://github.com/alexhopeoconnor/DFTE)) and **ESP32Async/ESPAsyncWebServer**.
 
-For this repo's `platformio.ini` test setup, DFTE is expected as a sibling checkout:
+The published `library.json` resolves DFTE from the maintained, pinned
+`v1.0.2` Git tag. No sibling checkout is required to consume WiFiManager.
+When developing both libraries together, use a local `symlink://` or
+`file://` dependency in your own ignored PlatformIO override.
 
-```ini
-lib_deps =
-    ESP32Async/ESPAsyncWebServer@3.9.1
-    symlink://../DFTE
-```
 
 ## Installation
 
+Use the release tag and list the asynchronous web/TCP packages at project level.
+PlatformIO installs the manifest dependencies automatically, but its dependency
+finder requires these headers to be direct project dependencies before it adds
+their include paths:
+
 ```ini
-[env:your_environment]
+[common]
-platform = espressif8266   ; or espressif32
+lib_deps =
-board = d1_mini            ; your board
+    WiFiManager=https://github.com/alexhopeoconnor/WiFiManager.git#v3.0.5
+    ESP32Async/ESPAsyncWebServer@3.9.1
+
+[env:esp8266]
+extends = common
+platform = espressif8266
+board = d1_mini
 framework = arduino
 lib_deps =
-    https://github.com/alexhopeoconnor/WiFiManager.git
+    ${common.lib_deps}
+    ESP32Async/ESPAsyncTCP@2.0.0
+
+[env:esp32]
+extends = common
+lib_deps =
+platform = espressif32
+board = esp32dev
+framework = arduino
+    ${common.lib_deps}
+    ESP32Async/AsyncTCP@3.4.9
 ```
 
-Or a local path:
+The text after `#` is a Git ref. PlatformIO clones the repository and checks
+out that tag; it does not download a GitHub Release asset. A tag gives a
+reproducible library input. Use a local checkout only while actively changing
+the library:
 
 ```ini
 lib_deps =
-    file:///path/to/WiFiManager
+    WiFiManager=file:///path/to/WiFiManager
 ```
 
+## Tests and releases
+
+The CI workflow compiles a minimal clean consumer project for both supported
+targets. These commands need no connected board:
+
+```bash
+./scripts/compile-check.sh --platform esp8266
+./scripts/compile-check.sh --platform esp32
+```
+
+Before publishing a version, update `library.json`, `CHANGELOG.md`, and this
+README, run both checks, then create the annotated tag:
+
+```bash
+./scripts/prepare-release.sh vMAJOR.MINOR.PATCH --tag
+```
+
+Push the branch and tag. GitHub Actions validates the PlatformIO package again
+and creates the GitHub Release from that tag.
+
 ## AI Assistance Notice
 
 Parts of this codebase have been developed and refactored with the aid of AI coding agents under human direction and review.

library.json

@@ -1,6 +1,6 @@
 {
   "name": "WiFiManager",
-  "version": "3.0.2",
+  "version": "3.0.5",
   "keywords": [
     "wifi",
     "wi-fi",
@@ -38,13 +38,33 @@
     "espressif8266",
     "espressif32"
   ],
-  "dependencies": {
+  "dependencies": [
-    "ESP32Async/ESPAsyncWebServer": "3.9.1",
+    {
-    "DeviceFrameworkTemplateEngine": "https://github.com/alexhopeoconnor/DFTE.git#v1.0.2"
+      "owner": "ESP32Async",
-  },
+      "name": "ESPAsyncWebServer",
+      "version": "3.9.1"
+    },
+    {
+      "owner": "ESP32Async",
+      "name": "ESPAsyncTCP",
+      "version": "2.0.0",
+      "platforms": "espressif8266"
+    },
+    {
+      "owner": "ESP32Async",
+      "name": "AsyncTCP",
+      "version": "3.4.9",
+      "platforms": "espressif32"
+    },
+    {
+      "name": "DeviceFrameworkTemplateEngine",
+      "version": "https://github.com/alexhopeoconnor/DFTE.git#v1.0.2"
+    }
+  ],
   "build": {
     "includeDir": "lib/WiFiManager/include",
-    "srcDir": "lib/WiFiManager/src"
+    "srcDir": "lib/WiFiManager/src",
+    "extraScript": "tools/platformio/dependencies.py"
   },
   "export": {
     "include": [
@@ -52,7 +72,8 @@
       "lib/WiFiManager/src",
       "LICENSE",
       "README.md",
-      "library.json"
+      "library.json",
+      "tools"
     ]
   },
   "$schema": "https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/schema/library.json",

platformio.ini

@@ -17,6 +17,7 @@ build_flags =
 lib_deps = 
     ESP32Async/ESPAsyncWebServer@3.9.1
     DeviceFrameworkTemplateEngine=https://github.com/alexhopeoconnor/DFTE.git#v1.0.2
+    ESP32Async/ESPAsyncTCP@2.0.0
 
 [env:esp32]
 platform = espressif32@6.13.0
@@ -34,6 +35,7 @@ build_flags =
 lib_deps = 
     ESP32Async/ESPAsyncWebServer@3.9.1
     DeviceFrameworkTemplateEngine=https://github.com/alexhopeoconnor/DFTE.git#v1.0.2
+    ESP32Async/AsyncTCP@3.4.9
 
 ; Optional: compile tests with DFTE logs bridged into WiFiManager::log (see README)
 [env:esp8266_dfte_log]

scripts/compile-check.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+    echo "Usage: $0 --platform esp8266|esp32" >&2
+    exit 2
+}
+
+[[ "${1:-}" == "--platform" ]] || usage
+platform="${2:-}"
+[[ "$platform" == "esp8266" || "$platform" == "esp32" ]] || usage
+[[ $# -eq 2 ]] || usage
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+pio run -d "$root/test/compile-project" -e "$platform"
+
+echo "WiFiManager consumer compile check passed for $platform"

test/compile-project/platformio.ini

@@ -0,0 +1,33 @@
+[platformio]
+default_envs = esp8266
+
+[common]
+framework = arduino
+lib_ldf_mode = chain
+lib_deps =
+    WiFiManager=symlink://../..
+    ESP32Async/ESPAsyncWebServer@3.9.1
+
+[env:esp8266]
+extends = common
+platform = espressif8266
+board = d1_mini
+platform_packages =
+    platformio/framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git#521ae60a89e64bb0d1eb7a0b7addf620ced5cad3
+build_flags =
+    -DWM_LOG_LEVEL=3
+lib_deps =
+    ${common.lib_deps}
+    ESP32Async/ESPAsyncTCP@2.0.0
+
+[env:esp32]
+extends = common
+platform = espressif32@6.13.0
+board = esp32dev
+build_unflags = -std=gnu++11
+build_flags =
+    -std=gnu++14
+    -DWM_LOG_LEVEL=3
+lib_deps =
+    ${common.lib_deps}
+    ESP32Async/AsyncTCP@3.4.9

test/compile-project/src/main.cpp

@@ -0,0 +1,10 @@
+#include <Arduino.h>
+#include <WiFiManager.h>
+
+WiFiManager wifiManager;
+
+void setup() {
+    wifiManager.setConfigPortalTimeout(1);
+}
+
+void loop() {}

tools/platformio/dependencies.py

@@ -0,0 +1,24 @@
+"""Expose WiFiManager's async dependencies to PlatformIO's nested library builds."""
+from __future__ import print_function
+
+import glob
+import os
+
+from SCons.Script import Import
+
+Import("env")
+
+
+def append_dependency_include(package_prefix):
+    """Add the installed package's source directory when PlatformIO has it."""
+    package_root = env.subst("$PROJECT_LIBDEPS_DIR")
+    candidates = glob.glob(os.path.join(package_root, package_prefix + "*", "src"))
+    if candidates:
+        env.Append(CPPPATH=[candidates[0]])
+
+
+append_dependency_include("ESPAsyncWebServer")
+if env.subst("$PIOPLATFORM") == "espressif8266":
+    append_dependency_include("ESPAsyncTCP")
+elif env.subst("$PIOPLATFORM") == "espressif32":
+    append_dependency_include("AsyncTCP")