Felicity Energy for Home Assistant¶

Custom integration for Felicity Solar hybrid inverters and batteries. It reads live values from the Felicity Cloud (shine-api.felicitysolar.com) and provides nine sensors.

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

Sensors¶

Sensor	Unit	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`

The five energy sensors are integrated from the power values and stored persistently. They can be used directly in the Energy Dashboard.

Features¶

Polling via the HA DataUpdateCoordinator (default 60 s, configurable 30–900 s).
Two authentication modes — no account password is stored:
Demo — deterministic simulation, no credentials needed.
Token — paste your Felicity Cloud token once; this is the productive, passwordless path.
Automatic dashboard — when setting up an account, an optional Lovelace dashboard is created in the sidebar (one per account, opt-in via options).
No invented zero values. If a measurement is missing, the sensor becomes unknown. If the poll fails, all sensors become unavailable — never 0 W or 0 %.
Reauth flow when the token expires.
Multi-account: Multiple config entries can run simultaneously, each with its own sensor set and its own dashboard.

Installation¶

Manual (recommended)¶

Download the release ZIP felicity_energy.zip from Releases.
Unzip so that this path exists:

<HA config>/custom_components/felicity_energy/manifest.json

Restart Home Assistant.
Settings → Devices & Services → Add Integration → "Felicity Energy".

Development from repository¶

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

Copy custom_components/felicity_energy into your HA config directory and restart HA.

Setup¶

Demo mode¶

Add integration → choose Demo mode → confirm.

Nine sensors with simulated values are created immediately. Demo mode never activates automatically when the cloud connection fails.

Felicity Cloud token (production)¶

Log in at https://shine.felicitysolar.com.
Open browser DevTools → Network → open any API request (e.g. get_energy_flow2).
Copy the full value of the Authorization request header (starts with Bearer_, underscore not space).
Add integration → choose Felicity Cloud access token → paste token → confirm.

Token lifetime: ~30 days. When it expires, HA automatically starts the reauth flow. No password is stored.

Automatic dashboard¶

When setting up an account, the integration automatically creates a Lovelace dashboard in the sidebar. It contains:

Live power values (solar, battery, grid)
Cumulative energy values (kWh)
History graphs (power, daily totals, battery state of charge)

The dashboard can be enabled or disabled via Configure → "Create a dashboard in the sidebar". Details: how-to/dashboard.md.

Energy Dashboard¶

The integration provides the required kWh sensors directly. In the HA Energy Dashboard (Settings → Energy), choose the matching sensors:

Dashboard field	Sensor
Solar production	Solar Energy
Grid consumption	Grid Import Energy
Return to grid	Grid Export Energy
Energy into battery	Battery Charge Energy
Energy from battery	Battery Discharge Energy

Options¶

After setup via Configure:

Option	Default	Description
Polling interval	60 s	How often HA queries the Felicity Cloud (30–900 s)
Grid power sign convention	Positive = import	Sign of the grid power and energy sensors
Create a dashboard in the sidebar	On	Automatic Lovelace dashboard for this account

Changes reload the config entry. Details: how-to/options.md.

Error behaviour¶

Situation	Behaviour
A measurement is missing	That sensor becomes `unknown`
HTTP 401/403 or token expired	`ConfigEntryAuthFailed` → reauth flow
Timeout / HTTP 5xx	`UpdateFailed` → all sensors `unavailable`
Rate limit (HTTP 429)	`UpdateFailed` → `unavailable`, next attempt after interval
Demo mode	Simulated values
Invalid credentials	No fallback to demo

Multi-account¶

Multiple config entries run fully independently, each with their own sensor set, coordinator and dashboard. Details: how-to/multi-account.md.

Development¶

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

Repository structure¶

custom_components/felicity_energy/
  __init__.py       Setup, runtime data, token persistence
  api_cloud.py      Cloud client, parsing, demo simulation
  config_flow.py    UI setup, reauth, options
  coordinator.py    Polling and error translation
  dashboard.py      Auto Lovelace dashboard per config entry
  energy.py         Persistent kWh integrators
  sensor.py         Power, SoC and energy sensors
  const.py          Constants, API paths, defaults
  manifest.json     HA metadata
  translations/     en.json, de.json
tests/              pytest suite (53 tests)
docs/               Architecture, how-to guides

CI/CD¶

CI: Ruff + pytest on every push/PR.
PR environment: One public HA instance per PR at https://pr-<n>.ha-felicity.speicherguru.de.
Release: Tag v* → build ZIP → Gitea release → update release instance.

Security¶

No account password is stored or logged.
Tokens are stored only in the HA config entry (.storage/core.config_entries).
PR credentials are disposable.

License¶

MIT – see LICENSE.

Contributing¶

Issues and pull requests: https://git.zarembo.de/Speicherguru/ha-felicity

Please run pytest and ruff locally before opening a PR.