[cjkas]

Summary

This is part 2 of the IDF 5.5 migration. It is stacked on #70, so merge that first. The decision and its trade-offs are in ADR 0003.

 [esp32]
-platform = espressif32 @ 6.13.0                       ; Arduino 2.0.17 / IDF 4.4.7
+platform = …/pioarduino/…/55.03.312/…zip              ; Arduino 3.3.12 / IDF 5.5, pinned
 envs
   esp32dev     CORE_DEBUG_LEVEL 3 -> 2                 ; needed to fit the 1.5 MB OTA slot
   esp32devdbg  3
-  esp32c3                                             ; image no longer fits its OTA slot
   esp32s3      3 -> 2
   esp32c6      own libs/platform -> shared [esp32]    ; still debug + huge_app

How an updated firmware gets confirmed. The core's verifyRollbackLater() hook is overridden:

boot after OTA     state PENDING_VERIFY, the core skips verification
loop()             once uptime >= 60 s and net.connected(): esp_ota_mark_app_valid_cancel_rollback()
reset before that  the bootloader boots the previous firmware

Other changes:

• esp_task_wdt_reconfigure() replaces esp_task_wdt_init(). On 3.x the core starts the watchdog before setup(), so init failed and the C6 build kept the 5 s default.
• ETH.begin() uses the 3.x argument order, and the Arduino 2.x #if branches are removed.
• CI installs pioarduino (Core 6.2) and runs .github/size_check.py, which compares firmware.bin with the app partition in partitions.bin. It fails with less than 8 KB free.
• Docs: ADR 0003, a Building section in the README, AGENTS.md, and a GitOTA certificate note in SECURITY_PLAN.md.

Evidence

Why the size check exists. PlatformIO's Flash: line counts ELF sections, not the image that has to fit:

Env	PlatformIO "Flash:"	firmware.bin	App slot	Free
esp32dev	1,508,932 (95.9%)	1,555,488	1,572,864	17.0 KB ✅
esp32c3	1,551,001 (98.6%) ✅	1,651,216	1,572,864	−76.5 KB
esp32s3	1,427,901	1,473,696	3,342,336	1,824.8 KB ✅
esp32c6 (huge_app)	1,664,334	1,800,416	3,145,728	1,313.8 KB ✅
esp32devdbg (huge_app)	1,632,808	1,695,056	3,145,728	1,416.7 KB ✅

For comparison, v3.0.14 on IDF 4.4: ESP32 1,382,640, C3 1,437,440.

• pio test -e native with pioarduino Core: 415/415 passed, including the new otaProven tests.
• The firmware.elf symbols show the hooks are linked:
  • T verifyRollbackLater: our strong override.
  • W verifyOta: the core's weak default, never called.
  • T __wrap_log_printf and T __wrap_log_printfv: the log lock still sits under the ESP Insights wrap.

Not yet tested on hardware, and needed before the 3.1.0 pre-release:

• OTA from v3.0.14 to this build on an ESP32
• Forced rollback: reset within 60 s of the first boot
• USB flash of the onboard image
• CC1101 send and receive
• 24 h memStatus heap and loop health
• Ethernet board (volunteer)
• C6 radio (volunteer)

Merge Danger

Door: two-way

Reverting the commit puts the build back on 6.13.0. A device that has installed and confirmed an IDF 5.5 firmware can still go back to 3.0.x through a normal OTA, because the partition table, NVS and backup formats are unchanged. The tooling change does reach every contributor: pioarduino replaces PlatformIO Core in ~/.platformio/penv.

Blast Radius: release

• C3 users get no new releases. GitOTA on a C3 board will show an error for 3.1.0 because the release has no ino.esp32c3.bin.
• Logs: release builds lose the info and debug lines (about 220 call sites). Warnings and errors stay.
• Existing bug, not fixed here: GitOTA's LittleFS step requests SomfyController.littlefs.bin, but releases publish littlefs.esp32*.bin. An online update installs the new firmware and keeps the old web UI. After a rollback, the old firmware also runs with whatever UI is on the device.

🤖 Generated with Claude Code