FranklinWH Automation (Home Assistant)

This is a Home Assistant custom integration that exposes FranklinWH control services you can use in automations. It uses the franklinwh Python library, which is the same library used by the existing franklin_wh sensor/switch integration.

Current Plan (Draft)

Goals

• Enable automations to react to FranklinWH export conditions.
• Provide control actions that are supported by the FranklinWH API library.
• Keep the solution compatible with your existing franklin_wh sensors.

Scope

• Custom integration franklinwh_automation that exposes control services.
• Home Assistant package that implements the export‑driven automation.
• Use franklinwh Python library calls (mode + grid status) as control actions.

Out of Scope (for now)

• Direct “import limit” control (not exposed by the current API/library).
• UI dashboard work beyond service usage.

Requirements (Assumptions)

• You already run the franklin_wh integration for sensors.
• Two gateways (aGates) are configured and available in HA.
• Export is detectable via sensor.franklinwh_grid_use (negative = export).
• You can store gateway IDs in secrets.yaml.

Implementation Steps

1. Install the custom integration from this repo into HA.
2. Configure it with username/password + gateway ID for the target aGate.
3. Add the package franklinwh_automation.yaml to your HA config.
4. Tune thresholds and SOC values in HA.

Open Questions

• Does sensor.franklinwh_grid_use go negative on export in your setup?
• Which gateway should be controlled when the other is exporting?
• Any preferred SOC thresholds or time‑of‑use behaviors?

Install

1. Copy custom_components/franklinwh_automation into your Home Assistant config folder (or use a custom components workflow).
2. Restart Home Assistant.
3. Add the integration via Settings → Devices & Services → Add Integration.

Configure

You will be prompted for:

• username: FranklinWH account email.
• password: FranklinWH account password.
• gateway_id: Target aGate gateway ID (SN).

Services

franklinwh_automation.set_mode

service: franklinwh_automation.set_mode
data:
  gateway_id: "10060005A02X24470657"
  mode: self_consumption
  soc: 20

franklinwh_automation.set_grid_status

Example automation action:

service: franklinwh_automation.set_grid_status
data:
  gateway_id: "10060005A02X24470657"
  status: offgrid
  soc: 5

Sensors

• sensor.<name>_mode shows the current gateway mode.
• Attribute min_soc reflects the SOC value reported for that mode.

Notes

The FranklinWH API does not currently expose a documented import limit control. This integration focuses on the supported controls exposed by the upstream library. If/when an import limit endpoint is discovered, we can add a new service here.