From ea6f1cf3531c56a809ac5a7777fd21924856b5a7 Mon Sep 17 00:00:00 2001 From: Alex Hope-O'Connor Date: Thu, 17 Sep 2026 12:10:59 +1000 Subject: [PATCH] ci: add current ESP32 validation lane --- .github/workflows/ci.yml | 4 +- .github/workflows/release.yml | 3 ++ docs/ESP8266-LINKER-WORKAROUND.md | 10 ++++- docs/compatibility.md | 42 ++++++++++++++++++- examples/01-esp-sensor/platformio.ini | 4 ++ examples/02-switch-callback/platformio.ini | 4 ++ .../03-multi-entity-device/platformio.ini | 4 ++ examples/04-device-discovery/platformio.ini | 4 ++ examples/README.md | 5 +++ platformio.ini | 12 ++++++ scripts/test.sh | 37 +++++++++++++--- 11 files changed, 120 insertions(+), 9 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6d5cc17..5e6813d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -35,7 +35,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 @@ -43,4 +43,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 afdae2c..1f2cee1 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -51,6 +51,9 @@ jobs: - run: pio test -e native --filter test_native_core - 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/ESP8266-LINKER-WORKAROUND.md b/docs/ESP8266-LINKER-WORKAROUND.md index 0260da0..674d94d 100644 --- a/docs/ESP8266-LINKER-WORKAROUND.md +++ b/docs/ESP8266-LINKER-WORKAROUND.md @@ -1,7 +1,7 @@ # ESP8266 Postmortem linker workaround The ESP8266 Arduino framework pin used by the DeviceFramework, WiFiManager, -and DFTE test projects is intentional: +DFTE, and ArduinoHA maintained builds is intentional: ```ini platform_packages = @@ -14,11 +14,17 @@ It changes the restart wrapper to use a relaxed jump and adds an EPC1 address check. The failure is a framework linker/runtime-support issue, not an ArduinoHA or application-source error. +ArduinoHA's root `pio test -e esp8266` environment and every guided ESP8266 +PlatformIO example now use this same snapshot. There is no root-test exception +that can hide a linker regression from the example contract. + Keep this exact framework snapshot in ESP8266 environments that need the maintained test contract. It is unrelated to ESP32, whose pioarduino platform selects its framework and compiler as a unit. Do not replace the SHA with a version range: remove or advance the pin only after an upstream release includes -the fix and the affected large firmware has compiled successfully. +the fix and the affected large firmware has compiled successfully. In +particular, changing the ESP32 validation lane does not justify changing this +ESP8266 pin. The corresponding ESP32 Core 3 pin and shared PlatformIO-cache recovery steps are documented in [DeviceFramework's toolchain guide](https://github.com/alexhopeoconnor/DeviceFramework/blob/main/docs/TOOLCHAINS.md). diff --git a/docs/compatibility.md b/docs/compatibility.md index 9daf64c..1758e2f 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -16,6 +16,45 @@ The only imported upstream code fix is the four missing-device-ID guards from upstream commit `9c9d074`. Device discovery migration, JSON validation, lifecycle handling, and tests are fork-native changes. +## Arduino framework validation lanes + +ArduinoHA compiles its embedded test suites and guided PlatformIO examples in +three deliberately named lanes: + +| Selector | Target | Pinned stack | Role | +| --- | --- | --- | --- | +| `esp8266` | ESP8266 D1 mini | Arduino-ESP8266 commit `521ae60` | Maintained Postmortem linker-fix contract | +| `esp32` | ESP32 Dev Module | pioarduino `51.03.05` / Arduino-ESP32 3.0.5 | Legacy compatibility coverage | +| `esp32_3_3_11` | ESP32 Dev Module | pioarduino `55.03.311` / Arduino-ESP32 3.3.11 / ESP-IDF 5.5.5 | Current validation baseline | + +The ESP32 3.0.5 lane remains intentional compatibility coverage until the +supported floor is changed in a reviewed release decision. It is not allowed to +select a framework or compiler from a global PlatformIO cache by accident; +every lane pins its complete pioarduino platform. The ESP8266 framework pin is +independent of both ESP32 lanes; see the [linker workaround](ESP8266-LINKER-WORKAROUND.md). + +Run the current ESP32 lane locally with: + +```bash +./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 script keeps that current lane in a dedicated PlatformIO Core/cache +directory by default (`${XDG_CACHE_HOME:-$HOME/.cache}/arduinoha-platformio/core-3.3.11`). +This prevents a legacy 3.0.5 `tool-esptoolpy` cache from shadowing the current +pioarduino package-form uploader. Set `ARDUINOHA_PLATFORMIO_CORE_DIR`, +`ARDUINOHA_PLATFORMIO_PACKAGES_DIR`, and +`ARDUINOHA_PLATFORMIO_CACHE_DIR` for a dedicated disk or a disposable +clean-room check; do not repair this condition by overriding a single compiler +or deleting an unrelated global toolchain. + +The embedded multi-suite compile path also defaults +`PLATFORMIO_RUN_JOBS=1`. A caller may explicitly set another value, but the +serial default avoids a reproducible PlatformIO archive missing-object race +seen in the Core 3.3.11 lane. Example builds remain parallel. + ## Deliberate exclusions - No merge or wholesale cherry-pick of upstream `develop` / WIP 2.2.0. @@ -37,4 +76,5 @@ git diff --stat main...upstream/develop Port only independently reviewed changes with regression tests; treat open upstream pull requests as proposals, not release inputs. Run the native, -board-compile, and HA test harness gates before publishing a new release. +board-compile (including both ESP32 lanes), and HA test harness gates before +publishing a new release. diff --git a/examples/01-esp-sensor/platformio.ini b/examples/01-esp-sensor/platformio.ini index 73063ca..5030506 100644 --- a/examples/01-esp-sensor/platformio.ini +++ b/examples/01-esp-sensor/platformio.ini @@ -22,3 +22,7 @@ build_unflags = -std=gnu++11 build_flags = -std=gnu++14 -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src + +[env:esp32_3_3_11] +extends = env:esp32 +platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.311/platform-espressif32.zip diff --git a/examples/02-switch-callback/platformio.ini b/examples/02-switch-callback/platformio.ini index 73063ca..5030506 100644 --- a/examples/02-switch-callback/platformio.ini +++ b/examples/02-switch-callback/platformio.ini @@ -22,3 +22,7 @@ build_unflags = -std=gnu++11 build_flags = -std=gnu++14 -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src + +[env:esp32_3_3_11] +extends = env:esp32 +platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.311/platform-espressif32.zip diff --git a/examples/03-multi-entity-device/platformio.ini b/examples/03-multi-entity-device/platformio.ini index 73063ca..5030506 100644 --- a/examples/03-multi-entity-device/platformio.ini +++ b/examples/03-multi-entity-device/platformio.ini @@ -22,3 +22,7 @@ build_unflags = -std=gnu++11 build_flags = -std=gnu++14 -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src + +[env:esp32_3_3_11] +extends = env:esp32 +platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.311/platform-espressif32.zip diff --git a/examples/04-device-discovery/platformio.ini b/examples/04-device-discovery/platformio.ini index 73063ca..5030506 100644 --- a/examples/04-device-discovery/platformio.ini +++ b/examples/04-device-discovery/platformio.ini @@ -22,3 +22,7 @@ build_unflags = -std=gnu++11 build_flags = -std=gnu++14 -I${platformio.packages_dir}/framework-arduinoespressif32/libraries/Network/src + +[env:esp32_3_3_11] +extends = env: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 94fbac0..a83e280 100644 --- a/examples/README.md +++ b/examples/README.md @@ -7,6 +7,11 @@ pio run -d examples/01-esp-sensor -e esp8266 pio run -d examples/01-esp-sensor -e esp8266 -t upload ``` +The checked-in `esp32` environment preserves Arduino-ESP32 3.0.5 compatibility +coverage. Source-checkout maintenance also builds every guided project with +`esp32_3_3_11`, the Arduino-ESP32 3.3.11 validation lane. A consuming +application should choose and pin its complete PlatformIO platform stack. + | Guided example | What it demonstrates | | --- | --- | | [ESP Sensor](01-esp-sensor/) | Wi-Fi application wiring, a unique device ID, and changing numeric telemetry | diff --git a/platformio.ini b/platformio.ini index a705672..f298749 100644 --- a/platformio.ini +++ b/platformio.ini @@ -3,6 +3,8 @@ ; Full suite: ; pio test -e esp8266 ; pio test -e esp32 +; ./scripts/test.sh compile --platform esp32_3_3_11 +; (uses the isolated current Arduino-ESP32 validation lane) ; ; Single suite (examples): ; pio test -e esp8266 --filter test_utils_serializers @@ -30,6 +32,10 @@ extends = common test_ignore = test_native_core platform = espressif8266 board = d1_mini +; Keep root Unity coverage on the same Postmortem relocation-fix snapshot as +; the maintained ESP8266 examples. See docs/ESP8266-LINKER-WORKAROUND.md. +platform_packages = + platformio/framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git#521ae60a89e64bb0d1eb7a0b7addf620ced5cad3 [env:esp32] extends = common @@ -39,6 +45,12 @@ board = esp32dev build_unflags = -std=gnu++11 build_flags = ${common.build_flags} -std=gnu++14 +; Current Arduino-ESP32 validation lane. Keep the legacy env above until the +; supported floor changes through an explicit compatibility decision. +[env:esp32_3_3_11] +extends = env:esp32 +platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.311/platform-espressif32.zip + ; Host-only regression checks for serialization, topic validation, and the ; PubSubClient mock path. The Arduino compatibility files live exclusively ; under test/native and are never included in firmware environments. diff --git a/scripts/test.sh b/scripts/test.sh index 201ef47..e7cdb37 100755 --- a/scripts/test.sh +++ b/scripts/test.sh @@ -2,22 +2,49 @@ 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) environment="${3}" ;; + esp8266|esp32|esp32_3_3_11) environment="${3}" ;; *) usage ;; esac root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" + +pio_for_platform() { + if [[ "$environment" != "esp32_3_3_11" ]]; then + pio "$@" + return + fi + + # Keep Core 3.3.11's package-form esptool and generated pioarduino + # environment separate from the legacy Core 3.0.5 validation lane. + # A caller can point this at a disposable directory for cache diagnosis. + local core_dir packages_dir cache_dir + core_dir="${ARDUINOHA_PLATFORMIO_CORE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/arduinoha-platformio/core-3.3.11}" + packages_dir="${ARDUINOHA_PLATFORMIO_PACKAGES_DIR:-$core_dir/packages}" + cache_dir="${ARDUINOHA_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) - pio test -d "$root" -e "$environment" --without-uploading --without-testing + # PlatformIO's test command starts many archive jobs by default. This + # multi-suite project has a reproducible missing-object race on Core + # 3.3.11 at high parallelism, so use a deterministic default while + # preserving an explicit caller override. + export PLATFORMIO_RUN_JOBS="${PLATFORMIO_RUN_JOBS:-1}" + pio_for_platform test -d "$root" -e "$environment" --without-uploading --without-testing echo "ArduinoHA compile check passed for $environment" ;; + packages) + pio_for_platform pkg list -d "$root" -e "$environment" + ;; examples) mapfile -t examples < <(find "$root/examples" -mindepth 1 -maxdepth 1 -type d -name '[0-9][0-9]-*' -print | sort) if (( ${#examples[@]} == 0 )); then @@ -25,7 +52,7 @@ case "$1" in exit 1 fi for example in "${examples[@]}"; do - pio run -d "$example" -e "$environment"