WiFiManager/docs/DEVELOPMENT.md

Development and releases

Released consumers use the public Git tag. While changing WiFiManager and a sibling dependency together, point an ignored local PlatformIO override at a symlink:// or file:// checkout rather than changing tracked application dependencies.

lib_deps =
    WiFiManager=symlink:///path/to/WiFiManager

Target pins

WiFiManager currently has two explicit ESP32 test lanes:

Lane	pioarduino platform	Purpose
esp32	51.03.05 / Arduino-ESP32 3.0.5	temporary compatibility contract
esp32_core_3_3_11 / CLI esp32-current	55.03.311 / Arduino-ESP32 3.3.11	maintained current validation lane

This is a test-target contract, not a library-manifest dependency: a consuming application chooses its own platform and must validate the complete framework/toolchain stack. Do not let a shared global PlatformIO cache choose framework metadata or a compiler implicitly, and do not override just the toolchain to repair a cache mismatch. Each pioarduino platform owns its matching framework, uploader, and compiler package set.

Core 3 Wi-Fi builds need the C++14, SOC_WIFI_SUPPORTED, and Network/src settings in this repository's platformio.ini; keep those settings together when adding an ESP32 environment. The portal OTA fixture uses the current 3.3.11 lane for ESP32 even while the 3.0.5 compatibility lane remains available.

ESP8266 test environments pin framework commit 521ae60 for the upstream Postmortem large-jump linker fix. The exact rationale and update rule are in the shared ESP8266 linker-workaround note. For the pioarduino release-to-Core mapping and cache-collision diagnosis, see DeviceFramework's toolchain guide.

./scripts/test.sh automatically places the esp32-current lane, and ./tools/portal-hardware ota --platform esp32 places its current A/B fixture, in a dedicated PlatformIO Core/cache directory, defaulting to ${XDG_CACHE_HOME:-$HOME/.cache}/wifimanager-platformio/core-3.3.11. That keeps pioarduino's package-form esptool and generated environment separate from the legacy 3.0.5 tool-esptoolpy graph. Override the location with WIFIMANAGER_PLATFORMIO_CORE_DIR, WIFIMANAGER_PLATFORMIO_PACKAGES_DIR, and WIFIMANAGER_PLATFORMIO_CACHE_DIR when space belongs elsewhere. The first clean install is several GiB; reserve at least 4 GiB plus cache headroom. It is a deliberate quarantine, not a reason to delete or override packages in the shared PlatformIO installation.

For a disposable cache investigation, point that variable at an exact temporary directory, run the affected command, inspect the resolved graph, then remove only that directory:

wm_pio_core="$(mktemp -d /tmp/wifimanager-pio-XXXXXX)"
WIFIMANAGER_PLATFORMIO_CORE_DIR="$wm_pio_core" \
  ./scripts/test.sh compile --platform esp32-current
WIFIMANAGER_PLATFORMIO_CORE_DIR="$wm_pio_core" \
  ./scripts/test.sh packages --platform esp32-current
rm -rf -- "$wm_pio_core"

Start a release with bump-version.sh. It updates package metadata and canonical installation snippets, then creates the changelog section. Replace its generated TODO with the release summary and update any behavioural documentation before running:

./scripts/bump-version.sh vMAJOR.MINOR.PATCH
# Replace the generated CHANGELOG TODO with the release summary.
./scripts/check-docs.sh
./scripts/test.sh compile --platform esp8266
./scripts/test.sh compile --platform esp32
./scripts/test.sh compile --platform esp32-current
./scripts/test.sh unity --platform esp8266
./scripts/test.sh unity --platform esp32
./scripts/test.sh unity --platform esp32-current
./scripts/test.sh packages --platform esp32-current
./scripts/test.sh examples --platform esp8266
./scripts/test.sh examples --platform esp32
./scripts/test.sh ota-fixtures --platform esp8266
./scripts/test.sh ota-fixtures --platform esp32-current
./scripts/prepare-release.sh vMAJOR.MINOR.PATCH --tag

When a physical ESP8266 and ESP32 are available, include their local lifecycle tests in the release gate. These tests remain opt-in because they flash the selected board and use its actual radio:

./scripts/test.sh hardware --platform esp8266 --port /dev/serial/by-id/usb-...
./scripts/test.sh hardware --platform esp32 --port /dev/serial/by-id/usb-...

When a physical ESP8266 or ESP32 and a spare USB Wi-Fi adapter are available, run the Docker portal contract as an additional release-gate check. It is opt-in because it flashes the selected board and temporarily joins its AP, but it refuses the host default-route adapter and leaves Docker responsible only for browser/API testing:

./tools/portal-hardware run --platform esp8266 --port /dev/serial/by-id/usb-... \
  --client-interface wlx74da385d4165

From an SSH/headless shell, the portal command may ask once for scoped NetworkManager sudo authorization before the selected board is erased. This is host setup, not a test secret; never add a sudo value to an env file or run the whole runner as root. See Testing for the direct/Polkit and scoped-sudo behavior.

See Testing for cleanup, artifacts, and optional station handoff credentials.

Run the portal HTTP OTA A/B contract separately when a spare adapter and 4 MB test board are available. It erases the selected board's flash, serial-flashes A, and uses the real browser update form to upload B; do not replace its automatic-reboot assertion with a manual reset:

./tools/portal-hardware ota --platform esp8266 --port /dev/serial/by-id/usb-... \
  --client-interface wlx74da385d4165

See Portal HTTP OTA A/B contract for the partition, artifact, final-board-state, and adapter rules.

Push the branch and annotated tag. GitHub Actions repeats the board-free compile checks, validates the package, and creates a GitHub Release using that version’s changelog section. The workflow does not publish to the PlatformIO Registry.

Back to documentation · project overview.