feat(myenergi): Zappi and Eddi monitoring, auto-config and boost controls

[springfall2008]

Adds a myenergi component providing Zappi (EV charger) and Eddi (hot water diverter) monitoring, automatic wiring of their energy sensors into the optimiser, and boost controls.

Two APIs, one interface

myenergi exposes two unrelated APIs, and Predbat needs both:

	Direct ("director")	3rd-party
Host	director.myenergi.net, redirecting via X_MYENERGI-asn	api.s18.myenergi.net
Auth	HTTP Digest — hub serial + API key, self-served at myaccount.myenergi.com	OAuth2 bearer JWT
Availability	Any myenergi owner, today	Needs manual partner registration
Eddi	Fully supported	Documented as "in development"

Both sit behind a MyEnergiTransport ABC and normalise to one MyEnergiDevice dataclass, so publishing, auto-config, controls and tests are written once. myenergi_auth_method selects between them, defaulting to direct.

The cloud transport reuses oauth_mixin.py exactly as fox.py/deye.py/solis.py do. It cannot be exercised end to end until myenergi issue partner credentials; it is built against the published OpenAPI schema and unit-tested on recorded payloads.

What it does

• Monitoring — per-device entities named sensor.predbat_myenergi_{kind}_{serial}_*, so multi-device sites work.
• Automatic configuration (myenergi_automatic, default on) — Zappi session energy into car_charging_energy as a list (several chargers sum), plus car_charging_planned from the plug-status sensor; the first Eddi into iboost_energy_today. All via set_arg_auto(), so an explicit apps.yaml value is reported rather than silently replaced.
• Controls — a boost switch with a companion number entity for the amount. Events queue onto the run loop rather than running on the event thread. A Zappi outside Eco/Eco+ is refused locally instead of issuing a call myenergi would reject.
• Stubs — mode, priority, minimum green level, phase setting and schedules are documented interface stubs that warn once and return False. Libbi, webhooks, managed mode and super schedules are out of scope.
• CLI harness — python3 myenergi.py --hub-serial … --api-key … exercises either transport against a live account without running Predbat.

Configuration

myenergi_hub_serial: '12345678'
myenergi_api_key: 'your-api-key'

Get the key from myaccount.myenergi.com → Advanced → API Key; the hub serial is on the hub and in the app.

Notes for reviewers

• car_charging_planned templates. The shipped templates match sensor.myenergi_zappi_[0-9a-z]+_plug_status, which targets the third-party ha-myenergi HACS integration and does not match this component's entity names — so charge planning silently fell back to the car_charging_threshold heuristic. automatic_config() now wires it, and 'ev ready to charge' (pilot states C1/D1) was added to car_charging_planned_response in the 24 templates carrying the myenergi vocabulary. It was the only connected pilot state missing while less-ready states were already accepted. Nothing under apps/predbat/ reads templates/, so existing installs are unaffected.
• aiohttp>=3.12 is now pinned. DigestAuthMiddleware and ClientSession(middlewares=…) require it; the direct transport guards on availability with an actionable message rather than failing with a raw AttributeError.
• myenergi_poll_seconds is capped at 30 minutes so a large value cannot trip components.py's 60-minute staleness check now that the success timestamp only advances on cycles that actually polled.

Known limitation

Session energy sensors reset to zero at session end. Predbat's incrementing-counter cleanup handles that correctly — iboost_today and car_charging_energy both come out right. However clean_incrementing_reverse only treats a drop as a reset when it exceeds ~1 kWh, so a session ending below that can be under-counted, in both figures. Documented in docs/components.md.

Testing

apps/predbat/tests/test_myenergi.py — 74 assertions covering normalisation, both transports (including every error path and the record_api_call reason labels), transport selection, publishing, auto-config, controls, the stubs, and last-good-reading retention. Registered as myenergi in TEST_REGISTRY.

Full ./run_all --quick passes.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The myenergi component activation gate currently prevents valid OAuth refresh-only configurations (token_hash-only) from ever constructing the component, and the cloud transport’s boost path should reject unsupported device kinds rather than treating everything as Eddi.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a new pluggable myenergi component to Predbat to monitor Zappi (EV charger) and Eddi (hot water diverter) devices, auto-wire their energy/plug-status sensors into Predbat’s optimiser inputs, and expose boost controls—supporting both the direct digest API and the official cloud OAuth API behind a shared transport interface.

Changes:

• Introduces apps/predbat/myenergi.py implementing device normalisation, two transports (direct + cloud), publishing, auto-config, boost controls, and a CLI harness.
• Registers the new component + config keys, and adds comprehensive unit tests wired into the existing test runner.
• Updates shipped templates to accept the additional Zappi plug state ev ready to charge, plus documentation and spellcheck dictionary updates.

File summaries

File	Description
templates/teslemetry.yaml	Adds ev ready to charge to car-plug planned-response values (commented template list).
templates/tesla_powerwall.yaml	Adds ev ready to charge to car-plug planned-response values (commented template list).
templates/sunsynk.yaml	Adds ev ready to charge to car-plug planned-response values (commented template list).
templates/solis_cloud.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
templates/solax_sx4.yaml	Adds ev ready to charge to car-plug planned-response values (commented template list).
templates/solax_cloud.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
templates/solaredge.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
templates/solar_assistant_growatt_sph.yaml	Adds ev ready to charge to car-plug planned-response values (commented template list).
templates/solar_assistant_growatt_spa.yaml	Adds ev ready to charge to car-plug planned-response values (commented template list).
templates/sofar.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
templates/sofar_modbus.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
templates/sigenergy_sigenstor.yaml	Adds ev ready to charge to car-plug planned-response values (commented template list).
templates/sigenergy_cloud.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
templates/luxpower.yaml	Adds ev ready to charge to car-plug planned-response values (commented template list).
templates/hanchu_cloud.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
templates/givenergy_givtcp.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
templates/givenergy_ems.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
templates/givenergy_cloud.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
templates/ginlong_solis.yaml	Adds ev ready to charge to car-plug planned-response values (commented template list).
templates/ge_cloud_octopus_standalone.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
templates/fronius.yaml	Adds ev ready to charge to car-plug planned-response values (commented template list).
templates/fox_cloud.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
templates/ep_cube_cloud.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
templates/enphase_cloud.yaml	Adds ev ready to charge to car-plug planned-response values (active list).
requirements.txt	Pins aiohttp>=3.12 to support digest middleware usage.
docs/superpowers/specs/2026-08-23-myenergi-integration-design.md	Adds a detailed design spec for the integration.
docs/components.md	Documents the new component, options, entities, controls, and limitations.
docs/apps-yaml.md	Documents new myenergi_* configuration keys and behaviour.
apps/predbat/unit_test.py	Registers the new myenergi test suite in the test runner.
apps/predbat/tests/test_myenergi.py	Adds a comprehensive test suite for normalisation, transports, publishing, auto-config, controls, and template acceptance.
apps/predbat/myenergi.py	Implements the myenergi component, transports, publishing, auto-config, controls, and CLI harness.
apps/predbat/config.py	Adds new config schema keys for the myenergi component.
apps/predbat/components.py	Registers the myenergi component in COMPONENT_LIST.
.cspell/custom-dictionary-workspace.txt	Adds new domain words used by the integration and docs.

Review details

• Files reviewed: 33/35 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.