arduino-home-assistant/docs/compatibility.md

Compatibility baseline

This maintenance line begins from fork commit 84cc0037b1c0 (release v3.0.2). It intentionally tracks Home Assistant's MQTT discovery test harness without merging upstream development wholesale.

Reference	Audited revision / target
Fork baseline	84cc0037b1c0 (v3.0.2)
Upstream main	1d333ab229b2 (v2.1.0)
Upstream develop	a7039fad810b (unreleased WIP 2.2.0)
Device discovery minimum	Home Assistant 2024.11.0
Test harness matrix	2024.11.3, current stable, current dev

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 two maintained lanes:

Selector	Target	Pinned stack	Role
esp8266	ESP8266 D1 mini	Arduino-ESP8266 commit 521ae60	Maintained Postmortem linker-fix test-harness lane
esp32	ESP32 Dev Module	pioarduino 55.03.311 / Arduino-ESP32 3.3.11 / ESP-IDF 5.5.5	Maintained baseline

Every lane pins its complete framework stack. The ESP32 runner keeps its maintained pioarduino graph in the persistent cache shared by these maintained framework repositories, so stale global metadata cannot select an uploader or compiler by accident without redownloading matching inputs for every repository. The ESP8266 framework pin is independent of the ESP32 baseline; see the linker workaround.

Run the current ESP32 lane locally with:

./scripts/test.sh compile --platform esp32
./scripts/test.sh examples --platform esp32

The script keeps that lane in the persistent PlatformIO Core/cache shared by the maintained framework repositories by default (${XDG_CACHE_HOME:-$HOME/.cache}/arduino-framework-platformio/core-3.3.11). This prevents stale global tool-esptoolpy metadata from shadowing the current pioarduino package-form uploader while avoiding duplicate Core 3.3.11 downloads. Set ARDUINOHA_PLATFORMIO_CORE_DIR, ARDUINOHA_PLATFORMIO_PACKAGES_DIR, and ARDUINOHA_PLATFORMIO_CACHE_DIR for a dedicated disk. The script never clears that cache or repairs it by overriding one compiler package.

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.
• No obj_id serialization: Home Assistant removed that discovery field. Use setDefaultEntityId() for new code.
• No binary-sensor state_class: it is not valid in the current HA MQTT binary sensor schema.
• No upstream IMqttClient abstraction or unreviewed entity-type feature PRs.

Ongoing audit routine

The upstream remote has no usable push URL. Fetch and compare explicitly:

git fetch --prune upstream
git log --oneline main..upstream/develop
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.