Add TeslemetryAPI component — Tesla Powerwall control via Teslemetry/Fleet API

[mgazza]

Summary

New TeslemetryAPI component (apps/predbat/teslemetry.py): Tesla Powerwall support over the Teslemetry REST API (which mirrors Tesla Fleet API paths — the base_url is configurable so a direct Fleet API connection works with zero component changes). Ports the proven templates/tesla_powerwall.yaml control semantics (operation mode / backup reserve / grid-charging / export rule / export tariff-trick) from HA service hooks onto component virtual entities, driven by the existing *_service hook loopback.

• Data path: polls live_status (120 s), site_info (capacity → soc_max; seeds operation-mode/reserve entity states), calendar_history (daily kWh) → publishes predbat_teslemetry_* sensors. 401/403 latches an auth-failed guard (recovery via live_status probe only); 429 exponential backoff.
• Control path: five virtual entities (operation_mode, backup_reserve, allow_charging_from_grid, allow_export, tariff_mode) with write-only-on-success semantics — a failed REST command leaves entity state untouched so the repeat: true hooks re-assert next cycle.
• Export tariff-trick: tariff_mode=export_now posts a synthetic ToU tariff (current 30-min window ON_PEAK, sell price max(0.50, 2× live export rate)); correct circle-complement off-peak periods including midnight wrap (property-tested: exact partition of the day for all 48 slots). normal restores a flat tariff from the customer's live rates.
• Boot reconciliation: reads the device's current tariff (GET /tariff_rate) and, if our PREDBAT-EXPORT-NOW marker is present (pod died mid-export), restores the normal tariff + disables export — gated on the real set_read_only config via get_arg.
• Registration: components.py entry (event_filter: predbat_teslemetry_) + APPS_SCHEMA keys teslemetry_key/teslemetry_site_id/teslemetry_base_url.

Companion SaaS PR: Predictive-Cloud-Ltd/predbat-saas feat/tesla-powerwall-teslemetry (onboarding + config generation). Part of Predictive-Cloud-Ltd/predbat-saas#1346.

Testing

• 34 unit tests in tests/test_teslemetry.py (registered in unit_test.py): field mapping/kWh conversions, real _request status branching (401 latch, 429 retry+backoff, recovery), run() bool contract, all five command handlers incl. failure paths, tariff builder (incl. midnight-wrap partition invariant and sell clamp), reconcile (marker found / absent / read-failed / read-only / boot-default gating).
• ./run_all --quick: 122 groups pass (1 pre-existing unrelated failure multi_car_iog_load_slots_regression, verified pre-existing via stash-baseline).
• Pre-commit (black/ruff/interrogate 100%/cspell en-gb) clean.

Known follow-ups

• GET /tariff_rate response shape is inferred from docs (defensive code-walker parse; fails safe) — to be validated on live PW3 hardware during the beta pilot.
• Auth-failed steady state logs a warning per minute (deliberate: component is genuinely unhealthy); may want throttling before long soak.

🤖 Generated with Claude Code

[mgazza]

Addressed findings from a follow-up review pass in 8443eac3:

1. Export tariff window was built in UTC. build_tariff used datetime.now(timezone.utc), but a Powerwall applies tou_periods in the site's local timezone — the same local clock Predbat schedules in. During BST/CEST the ON_PEAK window landed an hour (or two) off, so autonomous-mode export never triggered on any non-UTC site. Now derives site-local wall-clock via base.now_utc.astimezone(base.local_tz).
2. Boot reconcile could be skipped. A transient 401 on the first cycle consumed the first flag before reconcile_on_start ran, so a pod that died mid-export stayed exporting after the token recovered. Reconcile is now gated on a separate reconcile_done latch that only sets after a usable tariff read.
3. soc_max never retried if site_info returned without nameplate_energy — fetch_site_info now returns False in that case so it re-fetches next cycle.
4. calendar_history was missing required params — now requests ?kind=energy&period=day.
5. Control-entity writes wiped their own attributes. set_state_wrapper(entity, value) with empty attrs dropped the select options / number min-max set at registration. A new publish_control() helper re-applies the registered attributes on every write.
6. number_event guarded against a null value from number.increment/decrement (was raising TypeError out of the dispatch loop).

Tests 34 → 42; ge_cloud sibling suite unchanged at 66/66.

[mgazza]

Command-credit optimisation in 1026e6d8 (+ test/doc coverage in 9accebd8):

The control hooks re-assert every ~5-min cycle (repeat: true) and each was POSTing to Teslemetry unconditionally — ~20k commands/month ≈ £25–30/mo per site in Tesla Fleet API command credits. Added write-on-change dedupe in the component:

• New _apply_command(key, signature, sender) skips the POST when the value matches the last confirmed-successful send. The cache updates only on success, so a failed/dropped command still retries next cycle.
• All 5 controls routed through it; the tariff is keyed on its serialised built body, so the export ToU window still re-sends when it advances or the sell price changes (~24–48×/day) — just not every idle cycle.
• Drift correction: fetch_site_info refreshes the cache from the device's actual mode/reserve, so an external change made in the Tesla app is re-asserted.

Net: ~£25–30/mo → ~£2–4/mo per site. Failure-retry and drift both covered by tests; suite 42 → 53.

Known limitation (documented in-code, accepted for the beta pilot): the device-drift refresh is boot-only for mode/reserve, and grid_charging/export_rule aren't device-drift-refreshed at all (site_info doesn't expose their state) — so those self-heal on Predbat's next transition of the control rather than within a cycle. Full periodic device-state reconciliation is a pilot follow-up, to be built against verified PW3 response shapes.