[swinp]

An ESP32 OTA image can be valid and have a new version while targeting the wrong PCB or network interface. Add opt-in compatibility metadata so the VS Code uploader can compare the running device with the candidate image before starting OTA.

Changes

• A single THINGER_OTA_CHECK(FIELD) declaration generates both a versioned manifest in the application binary and the THINGER_OTA_CHECK output resource.
• ThingerESP32OTA registers the resource automatically and advertises it through $ota/options.
• Check unique field names, lengths, field count and payload size at compile time; preserve one linked manifest across translation units.
• Add analog/I2C examples, declaration validation checks, documentation and example compilation in the existing ESP32 CI matrix.

For example, PCB_VERSION = V2 on a device and PCB_VERSION = V3 in a candidate become available to the uploader without executing the new firmware. Existing sketches that omit the macro keep their firmware behavior.

Validation

• Both esp32dev example variants compile with PlatformIO Espressif32 6.10.0 / Arduino-ESP32 2.0.17.
• 14 compiler checks pass, including expected failures for invalid declarations and deduplication across translation units.
• The companion extension's production parser reads both generated images and detects their different PCB model and version, despite identical firmware version strings.
• Both generated images pass esptool checksum and validation-hash checks.
• No physical ESP32 or authenticated server was available for end-to-end OTA validation; the expanded GitHub CI matrix has not been run locally.

Related to thinger-io/vscode-extension#7.
Companion extension PR: thinger-io/vscode-extension#8.

[alvarolb]

@swinp thank you very much for this proposal! It's now released in 2.47.0, together with the VS Code extension 1.2.0, based on your idea and with your manifest format (@THINGER_OTA_CHECK:1@ and the THINGER_OTA_CHECK(FIELD) X-macro), and with you as co-author of the commit.

We made our own implementation instead of merging this PR, to fit some changes we discussed with the extension:

• Every board with OTA, not only ESP32: it lives in the ThingerOTA base class (ESP32, ESP8266, Pico W, UNO R4 WiFi, Nano 33 IoT/MKR, Portenta/Opta, Nano RP2040…).
• The device reports its fields directly in $ota/options (check: {...}), so there is no separate resource or extra request.
• The device also enforces it: $ota/begin is rejected if the fields of the new firmware are different or missing, unless force is set (the extension sends it when the user confirms). So it also protects updates from other clients, such as the REST API or scripts.
• Fully backward compatible: devices without THINGER_OTA_CHECK are updated exactly as before, with no extra requests or dialogs.
• Lower limits, as the fields are now built on every $ota/options request: up to 16 fields, keys of up to 32 characters, values of up to 128.

#define THINGER_OTA_CHECK(FIELD) FIELD("PCB_MODEL", "SENSOR_I2C") FIELD("PCB_VERSION", "V2")
#include <ThingerESP32OTA.h>

We tested it end to end on a real UNO R4 WiFi: a different field asks for confirmation, cancelling sends nothing, and the same fields update without asking. Closing this one, thanks again!