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

[mgazza]

Summary

This replaces the original service-hook control path for the TeslemetryAPI component (apps/predbat/teslemetry.py, Tesla Powerwall support over the Teslemetry / Tesla Fleet API) with a fox-style window control plane. Predbat now programs Tesla Powerwall exactly the way it programs a Fox inverter — through a TESLA inverter type and virtual schedule entities driven directly by inverter.py — with no HA service hooks anywhere in the control path.

Window control plane

• New "TESLA" entry in INVERTER_DEF (apps/predbat/config.py). Notably support_discharge_freeze: False (the Powerwall has no discharge-freeze/hold state — see below), support_charge_freeze: True, output_charge_control: "none" (no rate control, on/off + target SOC only), time_button_press: True (writes are committed atomically rather than instantly on entity change), and can_span_midnight: False.
• The component publishes the standard Fox-style schedule entities — charge/discharge window start/end time selects, charge/discharge target-SOC numbers, per-window enable switches, a backup-reserve number, and an atomic write button (schedule_write) that commits a staged edit to the live schedule in one step. inverter.py reads and writes these exactly as it does for a Fox inverter; the component itself never talks to the HA service-call layer.

Scheduler emulator

The Powerwall has no native on-device scheduler to hand a plan to (unlike Fox Cloud, which stores its own windows). To emulate one, run() evaluates the committed schedule + wall clock + live SOC every cycle (evaluate_schedule) into a single device-state tuple:

• tariff mode (normal / export_now)
• export rule (never / pv_only / battery_ok)
• grid-charging on/off
• backup reserve %
• operation mode (self_consumption / autonomous / backup)

That tuple is asserted onto the real device via assert_device_state, in a fixed order (tariff first, mode last — the order proven safe by the original template). Each of the five writes is deduplicated: a signature of the last successfully confirmed value is cached per control, and a write is skipped unless the desired value has actually changed. This keeps Teslemetry command-credit spend flat under steady state. If a write fails, the cache is left stale (it's only updated on success), so the identical desired state is simply re-sent and retried on the next 5-minute cycle — no separate retry loop needed. All of this is gated on set_read_only, so a read-only Predbat instance never issues a device command.

One behavioural change from the original template: the idle state (no active charge or discharge window) now sets export rule to pv_only rather than never. The old template's never would curtail excess solar generation while idle; pv_only lets PV export through while still blocking grid export.

Persistence

The committed schedule is saved/loaded through the Storage component (("teslemetry", "schedule")), so it survives an add-on restart mid-plan — the Powerwall can't be asked to hand the schedule back, so Predbat has to remember it.

Automatic configuration

Setting teslemetry_automatic: True now auto-wires the inverter args for you. End-user setup is down to three apps.yaml keys — teslemetry_key, teslemetry_site_id, teslemetry_automatic (an optional fourth, teslemetry_base_url, only needs setting for a non-default Fleet API endpoint). templates/tesla_powerwall.yaml has been rewritten from the old manual HA-integration template to this component-based form, and docs/components.md / docs/inverter-setup.md document the new setup and behaviour (including the export-freeze and idle-pv_only notes above).

Why support_discharge_freeze: False

The Powerwall cannot pin SOC while continuing to export PV — the hardware's self_consumption/autonomous discharge modes let backup reserve absorb solar rather than hold state at a fixed level, so there is no device mode that reproduces Predbat's discharge-freeze semantics. Rather than special-casing this in the Tesla component, the INVERTER_DEF flag is set False and the existing generic gate in execute.py (used by any inverter type lacking the feature) auto-disables set_export_freeze/set_export_freeze_only when the first enabled inverter doesn't support it.

Testing

• tests/test_teslemetry.py: 78 tests (plus the unit_test.py registry entry point) covering the data path, transport robustness, control-entity handlers, tariff/export-trick building, boot reconciliation, write-on-change dedupe, the scheduler emulator, schedule entities + persistence, device-state assertion, and automatic_config wiring.
• ./run_all --quick: all 131 test groups pass, including teslemetry and multi_car_iog_load_slots_regression (previously the one known pre-existing flake on this branch — passed clean on this run).
• Pre-commit (black/ruff/cspell en-gb/markdownlint) 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.
• The scheduler emulator's device-state mapping (tariff/export-rule/mode transitions) is unit-tested against mocked responses only — its behaviour needs validating against live hardware during the beta pilot.

Compatibility notes

• Legacy users of the old template's inline inverter: dict keep their service-hook behaviour — the inline dict overlays the new built-in TESLA type, and the generic *_service args still exist; unset keys now default to the TESLA entry's values (behaviour-neutral in practice).
• The five diagnostic control entities are live mirrors of the emulator's asserted state, so manual changes to them are transient unless set_read_only is enabled.

🤖 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.

[Copilot]

Pull request overview

Adds a new TeslemetryAPI component to integrate Tesla Powerwall control via Teslemetry/Tesla Fleet API, aligning it with Predbat’s existing “Fox-style” inverter window control plane (virtual schedule entities + inverter-driven programming), plus documentation/templates and a large unit test suite.

Changes:

• Introduces apps/predbat/teslemetry.py implementing polling, schedule persistence, tariff syncing, and a scheduler-emulator control loop.
• Registers a new TESLA inverter type and wires the new component into the component registry + config schema.
• Adds a comprehensive tests/test_teslemetry.py suite and updates docs/templates for the new beta setup path.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
templates/teslemetry.yaml	New apps.yaml template for the Teslemetry component configuration.
docs/inverter-setup.md	Documents the new “Teslemetry component (beta)” setup path for Powerwall.
docs/components.md	Adds component documentation for Teslemetry.
apps/predbat/unit_test.py	Registers the new teslemetry test group.
apps/predbat/tests/test_teslemetry.py	Adds extensive unit tests covering the new component’s behavior.
apps/predbat/teslemetry.py	Implements the Teslemetry Powerwall component, control-plane entities, schedule persistence, and emulator.
apps/predbat/config.py	Adds TESLA to INVERTER_DEF and new Teslemetry config keys to APPS_SCHEMA.
apps/predbat/components.py	Registers the teslemetry component and its args.
.gitignore	Ignores docs/superpowers/ artifacts.
.cspell/custom-dictionary-workspace.txt	Adds new accepted words (“dedupe”, “preseed”, etc.).