ESP32_Serial_Swiss_Army_Knife/docs/idf_candidate_integration.md

Official PlatformIO IDF 5.5.3 candidate integration

Initial package preparation: 2026-09-16, Linux x86_64; integration update: 2026-09-18. Preparation-only statements below describe the earlier stage. Root platformio.ini and reviewed guards/overrides are now migrated; shared-SDK installation is not claimed complete and no device/deployment acceptance is claimed.

Final integration evidence — 2026-09-18

Supplied final parent command, run from the repository root:

CCACHE_DISABLE=1 python3 -B tools/validate_phase9.py --build-dir .pio/idf-candidate-5.5.3/app-validated/.pio/build/esp32-s3-devkitc-1-n16r8 --idf-path .pio/idf-candidate-5.5.3/core/packages/framework-espidf --platformio-core-dir .pio/idf-candidate-5.5.3/core --interop --web-performance

PASS 24/24. This selects the actual fresh isolated build, SDK and toolchain core; it is not a default-root-build execution. The separate fresh .pio/idf-candidate-5.5.3/app-validated build PASS reports 95,552 B linked RAM / 1,749,493 B flash, versus historical 94,340 / 1,768,901 B (+1,212 B RAM / −19,408 B flash). The default parent pio run timed out after 200 seconds during installation, before compilation; no normal root build PASS is claimed.

Pre/post source equality: 3,237 files, SHA-256 3a1af78c15cfdd02da1055a8957b4086f9018862b7aa1c7c52fd2401a1a0a031. Actual generated-input registration covers nine C sources plus one forced header. WS receive tests exercise generated code: 982 cases / 10 mutation checks, including the five signed sizeof corrections. The stale web-cookie fixture asserting IDF 5.5.0 was corrected, not bypassed. Historical stale-WS compilation/coverage failures in the rebase review are resolved by this final snapshot, not hidden or retroactively called passes.

The fix-bearing Wi-Fi bundle is integrated in the candidate, with unchanged PMF/WPA3; radio-hardware vulnerability closure and full target/resource/recovery gates remain pending. Nine notice catalog entries were semantically rebased, the other 66 unchanged (75 total); supplied notice evidence is 36 fixtures PASS, two actual deterministic bundles each 77 files / 4,433,930 bytes. Archive pins and source equality do not prove complete immutable root/ancillary/Python dependency closure, legal clearance or Phase 9 acceptance. This documentation update records supplied parent evidence; it did not rerun these builds, suites, bundles or hardware tests.

Concrete result

Select official platformio/espressif32@6.13.0 + platformio/framework-espidf@3.50503.0 (IDF 5.5.3) + platformio/toolchain-xtensa-esp-elf@14.2.0+20251107. The official adapter also selects platformio/toolchain-riscv32-esp@14.2.0+20251107 for ESP32-S3 ULP; include it even when evaluating the Xtensa application.

This is an explicitly released supported pairing, not a speculative package override. Exact downloaded archive hashes below make the selected inputs content-pinned; tags/version labels alone are not treated as immutable.

Official channels checked:

• Platform registry: latest stable 7.1.3, published September 11, 2026. Latest release API agrees (prerelease=false). Its manifest selects ~4.60100.0, IDF 6.1, not IDF 5.5.
• Framework registry: newest published 5.5 package is 3.50503.0, published February 18, 2026. Returned 5.5 versions are 3.50503.0, 3.50502.0 and 3.50500.0. No 5.5.4/5.5.5 package appears in that response. Thus 5.5.3 is the latest available official PlatformIO 5.5 candidate, not the latest upstream Espressif 5.5 maintenance release. Registry framework metadata labels its tier community but its owner is platformio; the platform itself is tier official.
• 6.13.0 release, release API: explicitly adds IDF 5.5.3 and updates IDF toolchains to 14.2.0+20251107. Stable release, February 26, 2026.
• 6.13.0 manifest: framework ~3.50503.0, Xtensa 14.2.0+20251107. Adapter removes the legacy chip-specific Xtensa toolchains for standalone IDF, enables unified Xtensa for S3, and selects the same-date PlatformIO RISC-V package for S3 ULP.
• Xtensa registry and RISC-V registry both publish the selected Linux x86_64 artifacts.

If the requirement is specifically upstream 5.5.5, rather than the newest officially delivered 5.5 maintenance release, that requirement remains blocked on official packaging/support. Do not substitute 7.1.3 plus an arbitrary 5.5 override or a raw GitHub source archive.

Actual downloaded identities

All four complete archives were downloaded into .pio/idf-candidate-5.5.3/archives/ and their local bytes passed both registry size and SHA-256 checks. These are measured download checks, not just registry advertisements. No archive was unpacked into the shared PlatformIO SDK. Total compressed size: 992,746,039 bytes.

Artifact	Bytes	SHA-256
espressif32-6.13.0.tar.gz	1,009,115	5d1032b43828773ba87cf2e509432202c0bfe64f7304b58c9d669f13b116c6e0
framework-espidf-3.50503.0.tar.gz	76,402,966	8353f6fd5030dd7e662500891428fad15d46efd7e4b718cab2fe6bfb9e7f13fc
toolchain-xtensa-esp-elf-linux_x86_64-14.2.0+20251107.tar.gz	322,439,270	a5de49ce3299b0d9253ab6a423648bc23113db96b34a7cc8e57702cae1bb190e
toolchain-riscv32-esp-linux_x86_64-14.2.0+20251107.tar.gz	592,894,688	1af8e233931500b8712079808e4974413d95d3601d03275dff79665c436e9d33

Machine-readable registry URLs, artifact URLs, versions, system selectors, sizes and hashes: artifacts.json. No automatic repinning occurs.

The verifier reads members directly from the hash-verified archives without extracting or executing vendor files. Actual checks passed:

• Platform manifest version, framework range and exact Xtensa requirement.
• SDK package version and SDK tools/tools.json recommendation esp-14.2.0_20251107.
• Fixed wpa_ap_get_wpa_ie(size_t *len) callback declaration.
• All seven packaged ESP32-S3 Wi-Fi libraries match the 5.5.3 release-point Git blob identities, not the fix-point-only bundle, recorded in the existing Wi-Fi plan. The plan already establishes release commit 2c211b236707889e8400c4dc5644dd5c4ee071e0 and Wi-Fi submodule e0befaa593277b4e80726079fbd521b4681754c2; this task does not repeat fix research.

Whole-archive SHA-256 pins include the delivered PHY/coexistence/source/header contents, preventing changes to those bytes going unnoticed by this verifier. The subsequent semantic rebase review compared every regular packaged file in esp_wifi (163), esp_phy (114), esp_coex (41), and wpa_supplicant (301) against the installed candidate: all matched. This is complete comparison of those delivered component trees, not merely seven Wi-Fi archives. This is not an independent recursive source-to-package audit, vendor signature verification, proof of opaque implementation correctness, or execution of the compiler binaries.

Reproduce preparation and verification

From the repository root, with Python 3.9+ on Linux x86_64:

python3 -B tools/idf_candidate/test_prepare.py
python3 -B tools/idf_candidate/prepare.py

The second command is offline, verifies all four already-downloaded archives, and makes no installation. Missing or altered inputs fail. Four offline helper tests cover corrupted hash/size, URL restrictions, contract failure, and absent/ambiguous archive members.

On a fresh checkout, download and create the isolated project:

python3 -B tools/idf_candidate/prepare.py --fetch --prepare

Network is restricted by the tool to HTTPS dl.registry.platformio.org and dl.registry.nm1.platformio.org, including redirects. Approximately 993 MB download space is needed plus substantial unpacked/build space for the later test. --sdk-only --fetch obtains/verifies only the platform and SDK. Existing mismatched archives fail rather than being overwritten. A killed download may leave a .partial file; inspect/remove that candidate-only partial before retrying. --prepare deliberately refuses an existing smoke directory rather than overwriting it. Preparation already succeeded here; use offline verification, not a second --prepare.

Generated smoke project: .pio/idf-candidate-5.5.3/smoke/. Its configuration uses the verified local official platform archive and exact local framework/toolchain archives, with core_dir under .pio/idf-candidate-5.5.3/core/. Its sources are a separate empty app_main; it neither inherits production config nor imports application overrides. Generic official ESP32-S3 board is intentional: this tests package integration, not the production N16R8 board or feature configuration.

Command to test the isolated candidate

After successful verification, from the repository root:

env -u PLATFORMIO_PACKAGES_DIR -u PLATFORMIO_PLATFORMS_DIR -u PLATFORMIO_BUILD_DIR -u PLATFORMIO_CACHE_DIR -u IDF_PATH -u IDF_TOOLS_PATH -u IDF_PYTHON_ENV_PATH PLATFORMIO_CORE_DIR=/home/mscholz/Repos/ESP32_serial_swiss_army_knife/.pio/idf-candidate-5.5.3/core CCACHE_DISABLE=1 pio run --project-dir .pio/idf-candidate-5.5.3/smoke

For another checkout location, replace the absolute PLATFORMIO_CORE_DIR accordingly. Run in a normal clean PlatformIO shell, not an activated unrelated IDF environment. The initial preparation task did not run this smoke invocation; the later fresh application build PASS is recorded above and does not retroactively claim execution of this exact smoke command. It may download platform ancillary packages and IDF Python dependencies (registry/mirror, PyPI/files.pythonhosted.org and Espressif download endpoints as requested by the adapter); grant those hosts separately as needed. Those ancillary/Python dependencies are not yet a complete frozen build closure. The prepared four-input lock is not advertised as a fully reproducible toolchain environment/SBOM. No upload, monitor or erase command is part of this evaluation.

Rebase disposition and remaining integration gates

The official package-availability/toolchain mismatch question and bounded application build/host compatibility checks are resolved for the validated candidate. The per-entry semantic review retains every old protected correction (rebasing changed IDF original hashes), retains wolfSSH C/ABI overlays, and adds the ninth C override for five signed WS receive-size comparisons. Nothing was removed as superseded or bypassed by a permissive version guard. Reviewed heap extent/private HTTPD guards now target 5.5.3; generated-input ownership/include order and behavioral suites pass on the final build.

Remaining gates:

1. A successful normal root build: the default attempt stopped during installation, before compilation. Exact root version pins are not enforcement of the downloaded archive hashes.
2. Complete immutable ancillary/Python/tool/managed-component dependency closure; four verified primary archives and source equality are not a full reproducible environment or SBOM.
3. Target/radio/resource/recovery validation in the Wi-Fi plan, including the exact trigger and unchanged PMF/WPA3. Candidate integration is not hardware vulnerability closure.
4. Recipient notices, corresponding source, radio-blob legal basis and release-specific runtime/bootloader attribution. Nine notice entries have been semantically rebased and 66 retained unchanged, but assembly is not delivery or legal clearance.
5. Explicit whole-Phase-9 target acceptance. No upload, erase, credential migration, PMF weakening or generated-asset regeneration is part of this documentation update.