wertigpar/ha-emaldo

1. Overall shape

This is a Home Assistant custom integration, not a standalone app. Home Assistant loads custom_components/emaldo, creates entities and services from a config entry, and the integration continuously syncs Emaldo battery state into Home Assistant entities.

2. Main external boundary

The integration talks to Emaldo through two channels: a REST API for authentication, battery/power snapshots, and schedule data, and a separate end-to-end encrypted UDP channel for override and real-time control operations. That split is the core architectural boundary in the repo.

3. Bundled Emaldo client library

custom_components/emaldo/emaldo_lib/ is the integration’s internal SDK for Emaldo. It contains the REST client, crypto helpers, E2E UDP transport, constants, and exception types. The Home Assistant layer depends on this library rather than calling the API directly.

4. Setup and lifecycle

config_flow.py handles initial setup, reconfiguration, and options. __init__.py wires the config entry into Home Assistant, forwards setup to the entity platforms, and keeps the integration reloadable without removal. This is the lifecycle boundary for credentials and polling settings.

5. Shared runtime state

The integration uses a shared client pattern so multiple entities and coordinators operate on the same authenticated Emaldo session and cached state. That avoids duplicated logins and keeps REST and E2E activity coordinated per Home Assistant config entry.

6. Real-time and daily data coordinator

coordinator.py is the main polling loop for battery, power, and daily energy data. It drives the fast-changing sensors and keeps last-known values when Emaldo is temporarily unreachable, using retry/backoff behavior rather than failing the entities outright.

7. Schedule and override coordinator

schedule_coordinator.py is the schedule-focused subsystem. It polls on a separate schedule, reads the AI plan plus any user override slots, and exposes chart-ready schedule data. It also handles the “next-day schedule ready” event when tomorrow’s plan first appears.

8. Entity platform split

The entity files map Emaldo capabilities onto Home Assistant entity types:

• sensor.py for power, energy, module diagnostics, balancing state, and schedule sensors

• switch.py for control toggles like third-party PV, sell-back, AI range override, and emergency charge

• number.py for numeric setpoints such as EV fixed charge amount and battery reserve thresholds

• select.py for mode selection such as EV charge mode

• time.py for emergency charge window start/end

• calendar.py for schedule visualization

These entities are mostly thin views over coordinator state and client actions.

9. Service-driven control plane

services.py exposes the higher-level mutation API: set slot ranges, apply bulk schedules, reset to internal AI plan, refresh schedule data, write EV charging schedules, backfill solar history, and set AI battery range. This is the main write path for automations and optimizer integrations.

10. Data model and schedule encoding

A major architectural detail is the 15-minute slot model. Schedule overrides are stored as byte values where 0 means idle, 1–100 encode charge targets, 128 means no override, and 129–255 encode discharge targets. The chart sensor surfaces this as structured attributes for dashboards, while services convert human-friendly actions into slot bytes.

11. Dynamic and model-specific behavior

The integration adapts entity creation to the detected Emaldo device family. Power Core-only entities such as EV controls and certain realtime solar sensors are only created when supported, while per-module battery sensors are registered dynamically after the first successful battery poll.

12. Operational resilience

The repo is built around unreliable external connectivity: the integration tolerates REST failures, retries E2E access, and keeps stale-but-useful sensor state until recovery. That makes the key diagrammatic flow “Emaldo cloud / E2E server ↔ coordinators ↔ entities/services ↔ Home Assistant,” with coordinators acting as the isolation layer between network volatility and entity state.

13. Packaging and Home Assistant metadata

manifest.json, services.yaml, strings.json, and the translations/ files provide Home Assistant metadata, service schemas, and localization. hacs.json marks it for HACS distribution, so the repo is packaged as an installable HA custom integration rather than a general Python library.