From ec4c32db329ba3b4784bc785c9813e4c437274c5 Mon Sep 17 00:00:00 2001 From: Alex Hope-O'Connor Date: Thu, 17 Sep 2026 12:10:53 +1000 Subject: [PATCH] ci: add current ESP32 validation lane --- .github/workflows/ci.yml | 4 ++- .github/workflows/release.yml | 3 ++ docs/DEVELOPMENT.md | 42 +++++++++++++++++----- docs/TESTING.md | 18 ++++++++-- examples/AsyncDashboardDemo/platformio.ini | 4 +++ examples/HelloPlaceholder/platformio.ini | 3 ++ examples/NestedLayouts/platformio.ini | 3 ++ examples/README.md | 6 ++++ examples/StreamingAsync/platformio.ini | 3 ++ platformio.ini | 8 +++++ scripts/test.sh | 38 ++++++++++++++++---- 11 files changed, 113 insertions(+), 19 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 706140f..9f66230 100644 --- a/.github/workflows/ci.yml +++ b/.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 }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 2d860bb..619edb9 100644 --- a/.github/workflows/release.yml +++ b/.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" diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 4114854..fdd4efc 100644 --- a/docs/DEVELOPMENT.md +++ b/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 ``` diff --git a/docs/TESTING.md b/docs/TESTING.md index 99a21ad..469a5b9 100644 --- a/docs/TESTING.md +++ b/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). diff --git a/examples/AsyncDashboardDemo/platformio.ini b/examples/AsyncDashboardDemo/platformio.ini index 534482c..1ff57d0 100644 --- a/examples/AsyncDashboardDemo/platformio.ini +++ b/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 diff --git a/examples/HelloPlaceholder/platformio.ini b/examples/HelloPlaceholder/platformio.ini index fced0a1..46b1edd 100644 --- a/examples/HelloPlaceholder/platformio.ini +++ b/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 diff --git a/examples/NestedLayouts/platformio.ini b/examples/NestedLayouts/platformio.ini index fced0a1..46b1edd 100644 --- a/examples/NestedLayouts/platformio.ini +++ b/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 diff --git a/examples/README.md b/examples/README.md index addd439..6ff6a07 100644 --- a/examples/README.md +++ b/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 | diff --git a/examples/StreamingAsync/platformio.ini b/examples/StreamingAsync/platformio.ini index a5fa4c9..9bacc76 100644 --- a/examples/StreamingAsync/platformio.ini +++ b/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 diff --git a/platformio.ini b/platformio.ini index 1a6cce4..abc472c 100644 --- a/platformio.ini +++ b/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 diff --git a/scripts/test.sh b/scripts/test.sh index a2f1e01..2ab2508 100755 --- a/scripts/test.sh +++ b/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"