Reliability patches (fork): liveness, write retries, RSSI decay, transitions

[leiklier]

Reliability-focused patches to the Plejd BLE library, motivated by an
integration that issues frequent small brightness adjustments. Each patch is
a self-contained commit intended to be upstreamable individually after a live
soak.

Patches

1. Liveness — PlejdMesh.connected now requires self._client.is_connected, not just a non-None handle, so a silently-dropped link no longer looks connected (hass_plejd #162/#125/#147). disconnect() guards on the raw handle so a stale client is still cleaned up.
2. Surfaced write failures + bounded retry — write() now does one quick reconnect-and-retry and raises a typed PlejdWriteError on final failure instead of silently dropping the command. Payloads stay raw hex until write time so a retry re-encrypts against the (possibly new) gateway. Best-effort maintenance writers swallow the error.
3. BLEDevice refresh + RSSI decay — MeshDevice.see() refreshes the handle every advertisement and decays stored RSSI toward -100 dBm with a 5-minute half-life; connect() ranks candidates by the decayed value.
4. Opt-in double-connect workaround — the connect→disconnect→sleep(5)→connect firmware workaround is now behind a connect_workaround flag (default off), with automatic fallback to it if a direct authentication fails. Aligns with PR Try direct BLE authentication before double-connect fallback thomasloven/pyplejd#23; divergences: gated behind an explicit flag and reachable automatically via the auth-failure fallback rather than removed.
5. Software transitions — PlejdLight.turn_on(..., transition=...) runs a cancellable per-device brightness ramp (~150 ms steps), latest-command-cancels-previous. Step generation is the pure, tested ramp_steps().
6. Experimental group writes — PlejdManager.groups / dim_group(address, dim) send a single group command to a room mesh address. Marked experimental.

Tests

Adds a pytest suite (25 tests) + a GitHub Actions workflow covering RSSI decay, ramp generation/cancellation, connected-liveness, the write reconnect-retry (fake Bleak client), and group command construction. All mesh I/O is faked.

Not tested

No live BLE hardware was available, so none of these paths were exercised against a real Plejd mesh. They are covered by unit tests only and need a live soak before upstreaming.

🤖 Generated with Claude Code

---

Review round 1 fixes

Adversarial review found blocking defects; fixed on this branch:

• C1 (CRITICAL) — BleakClient.set_disconnected_callback does not exist on bleak 3.x (verified absent on 3.0.2), so every connect() raised AttributeError and the integration could never connect. Removed the call; the disconnect callback is now passed to establish_connection at connection time. Added tests/test_connect.py::test_connect_uses_only_available_bleak_api, which drives connect() against a deliberately spec'd fake client (not a MagicMock, which would auto-create the attribute) that has no set_disconnected_callback. Audited every other client call (write/read_gatt_char, start/stop_notify, disconnect, is_connected) — all present in bleak 3.x. Fix commit: ble: fix connect for bleak 3.x, single-flight connect, monotonic RSSI. That commit also fixes MeshDevice.update(), which was defined without self and crashed on every successful gateway selection (previously unreached by tests).
• P2 (HIGH) — concurrent write failures each called connect(), causing an establish_connection storm. connect() is now single-flight through a dedicated lock and re-checks connectivity, so concurrent callers await one attempt. Covered by test_connect_is_single_flight. Same commit as C1.
• C2 (HIGH) — the fade previously ran in a detached ensure_future task that swallowed PlejdWriteError (so the error-surfacing feature never fired for fades) and produced "Task exception was never retrieved" noise. Now the colour-temperature write and the first brightness step are awaited synchronously in turn_on, so an immediate failure raises to the caller; the remaining steps run in a task whose body catches PlejdWriteError, logs a single warning with device context, and stops. No exception escapes the task. Tests: test_first_step_written_synchronously_and_failure_raises, test_mid_ramp_failure_is_contained. Fix commit: light: contain ramp-task errors, await cancellation, fade to off.
• C3 (LOW) — _cancel_ramp is now async and awaits the cancelled task (suppressing CancelledError) before a new ramp starts, eliminating brief write overlap between an old and new fade. Same commit as C2.
• Minors — RSSI decay uses time.monotonic() instead of datetime.now() (NTP-safe); last_seen stays a wall-clock datetime for the last-seen sensor. turn_off accepts transition and fades to off. MIN_PY_VERSION bumped to 3.11 to match the CI matrix and the default-byteorder int.to_bytes usage.
• Also fixed — the test suite, pytest.ini and CI workflow were silently excluded by the repo's deny-by-default .gitignore in an earlier commit (only a source fix landed). Whitelisted tests/, pytest.ini and .github/ and committed the full suite.

Test count: 31 passing (was 25). Tag v0.22.0-fork.2 points at the fixed HEAD; v0.22.0-fork.1 was left untouched (never reuse a pushed tag).

Deviation (explicit): setup.py keeps the PEP440-valid 0.22.0+fork.1 rather than the reviewer-suggested 0.22.0-fork.1, because the latter is not a valid PEP440 version and would break pip install -e . in CI. The integration manifest version remains 0.22.0-fork.1. Still no live BLE hardware testing.