Felicity Energy für Home Assistant¶

Custom Integration für Felicity Solar Hybrid-Wechselrichter und Batterien. Sie liest die Live-Werte über die Felicity Cloud (shine-api.felicitysolar.com) und stellt neun Sensoren bereit.

Demo-Instanz: https://ha-felicity.speicherguru.de/

Sensoren¶

Sensor	Einheit	Device Class	State Class
Solar Generation Power	`W`	`power`	`measurement`
Battery State of Charge	`%`	`battery`	`measurement`
Battery Charge/Discharge Power	`W`	`power`	`measurement`
Grid Import/Export Power	`W`	`power`	`measurement`
Solar Energy	`kWh`	`energy`	`total_increasing`
Grid Import Energy	`kWh`	`energy`	`total_increasing`
Grid Export Energy	`kWh`	`energy`	`total_increasing`
Battery Charge Energy	`kWh`	`energy`	`total_increasing`
Battery Discharge Energy	`kWh`	`energy`	`total_increasing`

Die fünf Energiesensoren werden aus den Leistungswerten integriert und persistent gespeichert. Sie sind direkt im Energie-Dashboard nutzbar.

Funktionsumfang¶

Polling über den HA-DataUpdateCoordinator (Standard 60 s, einstellbar 30–900 s).
Zwei Authentifizierungswege – ohne Speicherung eines Kontopassworts:
Demo – deterministische Simulation, keine Zugangsdaten nötig.
Token – Felicity-Cloud-Token einmalig einfügen; das ist der produktive, passwortlose Weg.
Automatisches Dashboard – beim Einrichten eines Accounts wird optional ein Lovelace-Dashboard in der Sidebar erstellt (ein Dashboard pro Account, opt-in über Optionen).
Keine erfundenen Nullwerte. Fehlt ein Messwert, wird der Sensor unknown. Schlägt der Abruf fehl, werden alle Sensoren unavailable – niemals 0 W oder 0 %.
Reauth-Flow, wenn der Token abläuft.
Multi-Account: Mehrere Config-Entries können gleichzeitig laufen, jeder mit eigenem Sensor-Set und eigenem Dashboard.

Installation¶

Manuell (empfohlen)¶

Release-ZIP felicity_energy.zip von Releases herunterladen.
ZIP entpacken, so dass dieser Pfad entsteht:

<HA-Konfiguration>/custom_components/felicity_energy/manifest.json

Home Assistant neu starten.
Einstellungen → Geräte & Dienste → Integration hinzufügen → „Felicity Energy".

Entwicklung aus dem Repository¶

git clone https://git.zarembo.de/Speicherguru/ha-felicity.git

Ordner custom_components/felicity_energy in die HA-Konfiguration kopieren und HA neu starten.

Einrichtung¶

Demo-Modus¶

Integration hinzufügen → Demo mode wählen → Bestätigen.

Neun Sensoren mit simulierten Werten entstehen sofort. Demo schaltet sich nie automatisch ein, wenn die Cloud-Verbindung fehlschlägt.

Felicity-Cloud-Token (produktiv)¶

Unter https://shine.felicitysolar.com anmelden.
Browser-Entwicklertools → Netzwerk → einen API-Request öffnen (z. B. get_energy_flow2).
Den kompletten Wert des Authorization-Request-Headers kopieren (beginnt mit Bearer_, Unterstrich kein Leerzeichen).
Integration hinzufügen → Felicity Cloud access token wählen → Token einfügen → Bestätigen.

Token-Lebensdauer: ca. 30 Tage. Bei Ablauf startet HA automatisch den Reauth-Flow. Kein Passwort wird gespeichert.

Automatisches Dashboard¶

Beim Einrichten eines Accounts legt die Integration automatisch ein Lovelace-Dashboard in der Sidebar an. Es enthält:

Live-Leistungswerte (Solar, Batterie, Netz)
Kumulierte Energiewerte (kWh)
Verlaufsgrafiken (Leistung, Tagesmengen, Batterieladezustand)

Das Dashboard kann über Konfigurieren → „Create a dashboard in the sidebar" aktiviert oder deaktiviert werden. Details: docs/how-to/dashboard.md.

Energie-Dashboard¶

Die Integration stellt die benötigten kWh-Sensoren direkt bereit. Im HA-Energie-Dashboard (Einstellungen → Energie) die passenden Sensoren wählen:

Dashboard-Feld	Sensor
Solarproduktion	Solar Energy
Netzverbrauch	Grid Import Energy
Rücklieferung	Grid Export Energy
Energie in die Batterie	Battery Charge Energy
Energie aus der Batterie	Battery Discharge Energy

Optionen¶

Nach der Einrichtung über Konfigurieren:

Option	Standard	Beschreibung
Polling interval	60 s	Wie oft HA die Felicity Cloud abfragt (30–900 s)
Grid power sign convention	Positiv = Bezug	Vorzeichen der Netzleistungs- und Energiesensoren
Create a dashboard in the sidebar	Ein	Automatisches Lovelace-Dashboard für diesen Account

Änderungen laden den Config Entry neu. Details: docs/how-to/options.md.

Fehlerverhalten¶

Situation	Verhalten
Ein Messwert fehlt	Dieser Sensor wird `unknown`
HTTP 401/403 oder Token abgelaufen	`ConfigEntryAuthFailed` → Reauth-Flow
Timeout / HTTP 5xx	`UpdateFailed` → alle Sensoren `unavailable`
Rate Limit (HTTP 429)	`UpdateFailed` → `unavailable`, nächster Versuch im Intervall
Demo-Modus	Simulierte Werte
Ungültige Zugangsdaten	Kein Fallback auf Demo

Multi-Account¶

Mehrere Config-Entries laufen vollständig unabhängig nebeneinander, jeder mit eigenem Sensor-Set, eigenem Coordinator und eigenem Dashboard. Details: docs/how-to/multi-account.md.

Entwicklung¶

python -m venv .venv && .venv/Scripts/activate   # Windows
pip install -r requirements_test.txt
python -m pytest -q
python -m ruff check .

Repository-Struktur¶

custom_components/felicity_energy/
  __init__.py       Setup, Runtime-Daten, Token-Persistenz
  api_cloud.py      Cloud-Client, Parsing, Demo-Simulation
  config_flow.py    UI-Einrichtung, Reauth, Optionen
  coordinator.py    Polling und Fehlerübersetzung
  dashboard.py      Auto-Lovelace-Dashboard pro Config Entry
  energy.py         Persistente kWh-Integratoren
  sensor.py         Leistungs-, SoC- und Energiesensoren
  const.py          Konstanten, API-Pfade, Defaults
  manifest.json     HA-Metadaten
  translations/     en.json, de.json
tests/              pytest-Suite (53 Tests)
docs/               Architektur, How-to-Guides

CI/CD¶

CI: Ruff + pytest bei jedem Push/PR.
PR-Umgebung: Pro PR eine öffentliche HA-Instanz unter https://pr-<nr>.ha-felicity.speicherguru.de.
Release: Tag v* → ZIP bauen → Gitea-Release → Release-Instanz updaten.

Sicherheit¶

Kein Kontopasswort wird gespeichert oder protokolliert.
Tokens liegen nur im HA-Config-Entry (.storage/core.config_entries).
PR-Zugangsdaten sind Wegwerf-Credentials.

Lizenz¶

MIT – siehe LICENSE.

Mitwirken¶

Issues und Pull Requests: https://git.zarembo.de/Speicherguru/ha-felicity

Bitte vor einem PR pytest und ruff lokal ausführen.