ci: add current ESP32 validation lane

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        platform: [esp8266, esp32]
+        platform: [esp8266, esp32, esp32_3_3_11]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
@@ -33,4 +33,6 @@ jobs:
           python-version: '3.11'
       - run: python -m pip install --upgrade platformio==6.1.19
       - run: ./scripts/test.sh compile --platform ${{ matrix.platform }}
+      - if: matrix.platform == 'esp32_3_3_11'
+        run: ./scripts/test.sh packages --platform esp32_3_3_11
       - run: ./scripts/test.sh examples --platform ${{ matrix.platform }}

.github/workflows/release.yml

@@ -21,6 +21,9 @@ jobs:
       - run: ./scripts/test.sh examples --platform esp8266
       - run: ./scripts/test.sh compile --platform esp32
       - run: ./scripts/test.sh examples --platform esp32
+      - run: ./scripts/test.sh compile --platform esp32_3_3_11
+      - run: ./scripts/test.sh packages --platform esp32_3_3_11
+      - run: ./scripts/test.sh examples --platform esp32_3_3_11
       - run: ./scripts/check-docs.sh
       - run: ./scripts/prepare-release.sh "$GITHUB_REF_NAME"
       - run: ./scripts/release-notes.sh "$GITHUB_REF_NAME" > "$RUNNER_TEMP/release-notes.md"

docs/DEVELOPMENT.md

@@ -4,16 +4,37 @@ Released applications should use a public Git tag. While changing DFTE with a si
 
 ## Target pins
 
-The ESP32 test and example environments pin pioarduino `51.03.05`, which
-selects Arduino-ESP32 3.0.5 / ESP-IDF 5.1.4+. This is a fixture contract, not a
-DFTE package dependency: a consuming application owns its `platform` pin and
-tests the complete framework/toolchain stack. The ESP8266 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](https://github.com/alexhopeoconnor/arduino-home-assistant/blob/main/docs/ESP8266-LINKER-WORKAROUND.md).
+DFTE keeps two explicit ESP32 fixture lanes while consumers move to the current
+framework baseline:
 
-For the pioarduino release-to-Core mapping and the narrow repair for a stale
-global PlatformIO tool package, see [DeviceFramework's toolchain guide](https://github.com/alexhopeoconnor/DeviceFramework/blob/main/docs/TOOLCHAINS.md).
+| Test selector | pioarduino platform | Framework stack | Purpose |
+| --- | --- | --- | --- |
+| `esp32` | `51.03.05` | Arduino-ESP32 3.0.5 / ESP-IDF 5.1.4+ | Deliberate legacy compatibility coverage |
+| `esp32_3_3_11` | `55.03.311` | Arduino-ESP32 3.3.11 / ESP-IDF 5.5.5 | Current validation baseline |
+
+These are fixture contracts, not DFTE package dependencies: a consuming
+application owns its `platform` pin and tests the complete framework/toolchain
+stack. Do not copy a compiler or toolchain package between lanes; each pinned
+pioarduino platform resolves its matched framework, uploader, and toolchain.
+The legacy lane is retained deliberately until the supported ESP32 floor is
+changed in a reviewed compatibility decision.
+
+All DFTE ESP8266 test and example 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](https://github.com/alexhopeoconnor/arduino-home-assistant/blob/main/docs/ESP8266-LINKER-WORKAROUND.md).
+
+For the pioarduino release-to-Core mapping and cache-collision diagnosis, see
+[DeviceFramework's toolchain guide](https://github.com/alexhopeoconnor/DeviceFramework/blob/main/docs/TOOLCHAINS.md).
+
+`./scripts/test.sh` keeps the `esp32_3_3_11` lane in a dedicated PlatformIO
+Core/cache directory by default:
+`${XDG_CACHE_HOME:-$HOME/.cache}/dfte-platformio/core-3.3.11`. That prevents a
+legacy 3.0.5 `tool-esptoolpy` installation from shadowing the current
+pioarduino uploader. Override it with `DFTE_PLATFORMIO_CORE_DIR`,
+`DFTE_PLATFORMIO_PACKAGES_DIR`, and `DFTE_PLATFORMIO_CACHE_DIR` for another
+disk or a disposable clean-room investigation; do not delete an unrelated
+global toolchain or pin one compiler separately.
 
 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:
 
@@ -25,6 +46,9 @@ Start a release with `bump-version.sh`. It updates package metadata and canonica
 ./scripts/test.sh compile --platform esp32
 ./scripts/test.sh examples --platform esp8266
 ./scripts/test.sh examples --platform esp32
+./scripts/test.sh compile --platform esp32_3_3_11
+./scripts/test.sh packages --platform esp32_3_3_11
+./scripts/test.sh examples --platform esp32_3_3_11
 ./scripts/prepare-release.sh vMAJOR.MINOR.PATCH --tag
 ```
 

docs/TESTING.md

@@ -1,15 +1,29 @@
 # Testing
 
-The two PlatformIO Unity commands compile the complete DFTE test suites without uploading or executing them, so they require no attached board.
+The three PlatformIO Unity commands compile the complete DFTE test suites without uploading or executing them, so they require no attached board.
 
 ```bash
 ./scripts/test.sh compile --platform esp8266
 ./scripts/test.sh compile --platform esp32
 ./scripts/test.sh examples --platform esp8266
 ./scripts/test.sh examples --platform esp32
+./scripts/test.sh compile --platform esp32_3_3_11
+./scripts/test.sh packages --platform esp32_3_3_11
+./scripts/test.sh examples --platform esp32_3_3_11
 ```
 
-The first two commands compile the library test suites with `test_build_src = yes`. The example commands compile every standalone project on each target, protecting the code that the documentation links users to. CI runs the library target checks on the maintained branch and pull requests.
+`esp32` is the explicit Arduino-ESP32 3.0.5 compatibility lane.
+`esp32_3_3_11` uses pioarduino `55.03.311` (Arduino-ESP32 3.3.11 / ESP-IDF
+5.5.5) as the current validation baseline. The three `compile` commands
+compile the complete suites with `test_build_src = yes`; the example commands
+compile every standalone project on each target, protecting the code that the
+documentation links users to. CI runs every listed target lane on the
+maintained branch and pull requests.
+
+The current lane is isolated by the script in a dedicated Core/cache directory
+so the package-form Arduino-ESP32 Core 3.3.11 uploader cannot inherit legacy 3.0.5 Python
+metadata. `packages` prints the resolved package graph after the current build;
+it is a verification step, not a request to change a compiler pin.
 
 The standalone examples are buildable PlatformIO projects; see [examples](../examples/README.md).
 

examples/AsyncDashboardDemo/platformio.ini

@@ -34,3 +34,7 @@ build_flags =
   -DSOC_WIFI_SUPPORTED=1
   -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src
   -I$PROJECT_LIBDEPS_DIR/$PIOENV/AsyncTCP/src
+
+[env:dashboard_esp32_3_3_11]
+extends = env:dashboard_esp32
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.311/platform-espressif32.zip

examples/HelloPlaceholder/platformio.ini

@@ -18,3 +18,6 @@ platform_packages =
 platform = https://github.com/pioarduino/platform-espressif32/releases/download/51.03.05/platform-espressif32.zip
 board = esp32dev
 
+[env:example_esp32_3_3_11]
+extends = env:example_esp32
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.311/platform-espressif32.zip

examples/NestedLayouts/platformio.ini

@@ -18,3 +18,6 @@ platform_packages =
 platform = https://github.com/pioarduino/platform-espressif32/releases/download/51.03.05/platform-espressif32.zip
 board = esp32dev
 
+[env:example_esp32_3_3_11]
+extends = env:example_esp32
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.311/platform-espressif32.zip

examples/README.md

@@ -10,6 +10,12 @@ pio device monitor -d examples/HelloPlaceholder -e example_esp8266
 
 Choose the corresponding ESP32 environment where provided. The examples use the checked-out DFTE source, so they double as practical integration checks for this repository.
 
+The normal `example_esp32` / `dashboard_esp32` environments retain the
+Arduino-ESP32 3.0.5 compatibility lane. Repository CI also builds the matching
+`*_esp32_3_3_11` environments against the current Arduino-ESP32 3.3.11
+validation baseline. A consuming application should select and pin its own
+complete PlatformIO platform stack.
+
 | Example | Start here when you want to… |
 | --- | --- |
 | [HelloPlaceholder](HelloPlaceholder/) | understand the smallest registry/context/chunk flow over serial |

examples/StreamingAsync/platformio.ini

@@ -35,3 +35,6 @@ build_flags =
   -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src
   -I$PROJECT_LIBDEPS_DIR/$PIOENV/AsyncTCP/src
 
+[env:example_esp32_3_3_11]
+extends = env:example_esp32
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.311/platform-espressif32.zip

platformio.ini

@@ -9,8 +9,16 @@ test_framework = unity
 test_build_src = yes
 
 [env:test_template_engine_esp32]
+; Legacy Arduino-ESP32 3.0.5 compatibility lane. Keep this explicit while
+; consumers complete their migration to the current validation baseline below.
 platform = https://github.com/pioarduino/platform-espressif32/releases/download/51.03.05/platform-espressif32.zip
 board = nodemcu-32s
 framework = arduino
 test_framework = unity
 test_build_src = yes
+
+; Arduino-ESP32 3.3.11 / ESP-IDF 5.5.5 validation lane. Pin the complete
+; pioarduino platform so its framework and toolchain stay matched.
+[env:test_template_engine_esp32_3_3_11]
+extends = env:test_template_engine_esp32
+platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.311/platform-espressif32.zip

scripts/test.sh

@@ -2,26 +2,50 @@
 set -euo pipefail
 
 usage() {
-    echo "Usage: $0 compile|examples --platform esp8266|esp32" >&2
+    echo "Usage: $0 compile|examples|packages --platform esp8266|esp32|esp32_3_3_11" >&2
     exit 2
 }
 
-[[ $# -eq 3 && ( "${1:-}" == "compile" || "${1:-}" == "examples" ) && "${2:-}" == "--platform" ]] || usage
+[[ $# -eq 3 && ( "${1:-}" == "compile" || "${1:-}" == "examples" || "${1:-}" == "packages" ) && "${2:-}" == "--platform" ]] || usage
 case "${3:-}" in
-    esp8266|esp32) platform="$3" ;;
+    esp8266|esp32|esp32_3_3_11) platform="$3" ;;
     *) usage ;;
 esac
 
 root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-if [[ "$1" == "compile" ]]; then
+pio_for_platform() {
+    if [[ "$platform" != "esp32_3_3_11" ]]; then
+        pio "$@"
+        return
+    fi
+
+    # Arduino-ESP32 Core 3.3.11 uses a package-form uploader. Isolate its Core-managed
+    # Python environment from the legacy 3.0.5 tool-esptoolpy graph.
+    local core_dir packages_dir cache_dir
+    core_dir="${DFTE_PLATFORMIO_CORE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/dfte-platformio/core-3.3.11}"
+    packages_dir="${DFTE_PLATFORMIO_PACKAGES_DIR:-$core_dir/packages}"
+    cache_dir="${DFTE_PLATFORMIO_CACHE_DIR:-$core_dir/cache}"
+    install -d -m 700 "$core_dir" "$packages_dir" "$cache_dir"
+    PLATFORMIO_CORE_DIR="$core_dir" PLATFORMIO_PACKAGES_DIR="$packages_dir" \
+        PLATFORMIO_CACHE_DIR="$cache_dir" pio "$@"
+}
+
+case "$1" in
+compile|packages)
     case "$platform" in
         esp8266) test_environment="test_template_engine_8266" ;;
         esp32) test_environment="test_template_engine_esp32" ;;
+        esp32_3_3_11) test_environment="test_template_engine_esp32_3_3_11" ;;
     esac
-    pio test -d "$root" -e "$test_environment" --without-uploading --without-testing
+    if [[ "$1" == "packages" ]]; then
+        pio_for_platform pkg list -d "$root" -e "$test_environment"
+        exit 0
+    fi
+    pio_for_platform test -d "$root" -e "$test_environment" --without-uploading --without-testing
     echo "DFTE compile check passed for $platform"
     exit 0
-fi
+    ;;
+esac
 
 suffix="$platform"
 mapfile -t examples < <(find "$root/examples" -mindepth 2 -maxdepth 2 -type f -name platformio.ini -printf '%h\n' | sort)
@@ -32,6 +56,6 @@ fi
 for example in "${examples[@]}"; do
     env_name="example_$suffix"
     [[ "$(basename "$example")" == "AsyncDashboardDemo" ]] && env_name="dashboard_$suffix"
-    pio run -d "$example" -e "$env_name" </dev/null
+    pio_for_platform run -d "$example" -e "$env_name" </dev/null
 done
 echo "DFTE examples compile check passed for $platform"