Monitor and control FranklinWH aPower / aGate energy storage from Home Assistant - fully UI-configurable, multi-gateway aware, Energy-dashboard ready.
- UI configuration - add the integration from Settings → Devices & Services. No YAML needed.
- Multi-gateway aware - accounts with more than one aGate get a picker; each gateway becomes its own device with its own entities.
- Reauthentication flow - when your password changes, Home Assistant prompts to re-enter it; no restart needed.
- One device, all entities - every sensor, switch, number, and select lives under a single FranklinWH device card.
- Read & write - not just monitoring. Toggle smart circuits, change operating mode, set battery reserve, change export mode and limit, enable/disable the generator.
- Energy Dashboard ready - kWh sensors carry the right device classes for the HA Energy panel.
- Stale-tolerant polling - keeps the last good reading on the dashboard during transient cloud outages instead of strobing entities to "unavailable".
- Sign-flip toggles - invert battery / grid sign at the entity layer (no template-sensor workaround).
- Service calls -
franklin_wh.set_mode,franklin_wh.set_export_settings,franklin_wh.set_generatorfor use in scripts and automations.
Click the badge below to open HACS and add this repository in one step:
Or manually:
- In Home Assistant, open HACS → Integrations.
- Menu (⋮) → Custom repositories.
- Add the repo URL:
https://github.com/Emkraan/homeassistant-franklinwh - Category: Integration. Click Add.
- Install FranklinWH from the list.
- Restart Home Assistant.
- Settings → Devices & Services → Add Integration → FranklinWH and follow the prompts.
- Copy this repository's
custom_components/franklin_wh/folder into<config>/custom_components/franklin_wh/. - Restart Home Assistant.
- Add the integration from the UI as above.
All configuration is done via the UI. You will need:
- The email and password for your FranklinWH account.
- (Optional) Your gateway serial number - needed only if you have multiple aGates and want to confirm which one to add.
Find the gateway SN in the FranklinWH mobile app: Settings → Device Info → SN.
After setup, click Configure on the integration card to access:
| Option | Default | What it does |
|---|---|---|
| Entity name prefix | FranklinWH |
Prefix used in entity friendly names |
| Update interval (seconds) | 30 |
How often to poll the FranklinWH cloud (10-600s) |
| Keep last-known data when the cloud fails | on |
Avoids dashboard strobing during transient outages |
| Flip battery-use sign | off |
Invert sign of battery_use so charge/discharge match your convention |
| Flip grid-use sign | off |
Invert sign of grid_use so import/export match your convention |
All entities are grouped under one device per gateway.
| Entity | Description | Unit |
|---|---|---|
| State of charge | Battery state of charge | % |
| Battery use | Live charge/discharge power | kW |
| Battery charge | Lifetime energy charged | kWh |
| Battery discharge | Lifetime energy discharged | kWh |
| Home load | Live home power use | kW |
| Home use | Lifetime home energy | kWh |
| Grid use | Live import/export power | kW |
| Grid import | Lifetime energy imported | kWh |
| Grid export | Lifetime energy exported | kWh |
| Grid status | Enum: NORMAL / DOWN / OFF | - |
| Solar production | Live solar power | kW |
| Solar energy | Lifetime solar energy | kWh |
| Generator output | Live generator power | kW |
| Generator energy | Lifetime generator energy | kWh |
| Smart Circuit 1 / 2 load | Live load on each smart circuit | W |
| Smart Circuit 1 / 2 lifetime use | Lifetime energy per circuit | Wh |
| V2L use / export / import | Vehicle-to-Load metrics | W / Wh |
| Entity | When on |
|---|---|
| Grid online | Grid status is NORMAL |
| Generator enabled | Generator is currently running |
| Entity | Controls |
|---|---|
| Smart Circuit 1 | Relay 1 |
| Smart Circuit 2 | Relay 2 |
| V2L circuit | Relay 3 |
⚠️ If two circuits are physically merged at the gateway (SwMerge), the FranklinWH cloud will refuse mismatched commands to protect your wiring. Toggling one will return an error in that case - set both to the same value, or unmerge in the FranklinWH app.
| Entity | Range | Notes |
|---|---|---|
| Battery reserve | 0-100 % | Reserves battery SoC for the active operating mode |
| Grid export limit | 0-100 kW | Hidden when export mode is "no export" |
| Entity | Options |
|---|---|
| Operating mode | Time of use / Self consumption / Emergency backup |
| Grid export mode | Solar only / Solar and battery / No export |
Change operating mode and (optionally) the SoC reserve in one call.
service: franklin_wh.set_mode
data:
mode: time_of_use # or self_consumption / emergency_backup
reserve_soc: 20 # optional, 0-100
gateway: "100xxxx" # optional, only needed if you have multiple gatewaysservice: franklin_wh.set_export_settings
data:
export_mode: solar_and_apower # or solar_only / no_export
export_limit_kw: 5.0 # optional, ignored when no_exportservice: franklin_wh.set_generator
data:
enabled: trueEarlier versions of this integration required sensor: and switch: blocks in configuration.yaml. On startup, the integration will:
- Auto-import legacy YAML into a config entry,
- Raise a Repairs issue prompting you to remove the YAML, and
- Continue to honor the YAML for one release cycle.
After the import succeeds, delete the franklin_wh blocks from configuration.yaml. The UI flow is now the only supported path.
| Symptom | Likely cause | Fix |
|---|---|---|
Invalid auth during setup |
Wrong email/password | Double-check; note that FranklinWH may temporarily lock the account after several failed tries |
Account locked |
Too many failed logins | Wait 15 minutes |
Cannot connect |
Cloud outage or DNS | Check https://energy.franklinwh.com/ from the HA host |
| Entities go "unavailable" intermittently | Cloud is flaky | Make sure Keep last-known data when the cloud fails is enabled in options |
Smart-circuit toggle returns RuntimeError |
The gateway has the relays merged (SwMerge=1) |
Toggle both relays together via the service call, or unmerge in the FranklinWH app |
| No switches appear | Gateway reports no Smart Circuit module | Confirm hardware presence in the FranklinWH app |
Enable verbose logs with:
logger:
logs:
custom_components.franklin_wh: debug
franklinwh: debugLicensed under the MIT License. See LICENSE for details.