ci: add current ESP32 validation lane

.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 }}

.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"

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).

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.

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

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

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

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

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 |

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.

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" </dev/null
+            pio_for_platform run -d "$example" -e "$environment" </dev/null
         done
         echo "ArduinoHA examples compile check passed for $environment"
         ;;