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 a persistent repository cache so stale global
metadata cannot select an uploader or compiler by accident. The ESP8266
framework pin is independent of the ESP32 baseline; see the [linker
workaround](ESP8266-LINKER-WORKAROUND.md).

Run the current ESP32 lane locally with:

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

The script keeps that lane in a dedicated persistent PlatformIO Core/cache
directory by default (`${XDG_CACHE_HOME:-$HOME/.cache}/arduinoha-platformio/core-3.3.11`).
This prevents stale global `tool-esptoolpy` metadata 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. 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:

```bash
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.