This is a modern custom integration for Home Assistant that provides comprehensive monitoring and control for FranklinWH home energy storage systems.
⚠️ This project is unofficial and not affiliated with FranklinWH.
📝 About This Fork: Complete rewrite by Joshua Seidel (@JoshuaSeidel) with Anthropic Claude Sonnet 4.5. Originally inspired by @richo's homeassistant-franklinwh and uses the franklinwh-python library.
- 📊 Live battery status (State of Charge, charging/discharging power)
- ☀️ Solar production and energy generation tracking
- 🔌 Grid import/export monitoring with totals
- ⚡ Generator production and energy insights
- 🏠 Home load power monitoring and total energy consumption
- 🔀 Smart circuit switch monitoring (Switches 1-3)
- 🚗 V2L (Vehicle-to-Load) data support
- 🎛️ Individual smart circuit switch control
- ⚙️ Operation mode selection (self_use, backup, time_of_use)
- 🔋 Battery reserve setting
- 🌐 Grid connection control
- 🎨 Config Flow: Easy setup through the Home Assistant UI
- 🔄 DataUpdateCoordinator: Efficient polling with minimal API calls
- 📱 Device Registry: All entities grouped under one device
- 🔍 Diagnostics: Built-in debugging support
- 🌐 Local API Support: Experimental local communication (when available)
- 🛠️ Services: Custom services for advanced control
- In Home Assistant, go to HACS → Integrations.
- Click the menu (⋮) → Custom repositories.
- Add this repository URL:
https://github.com/JoshuaSeidel/homeassistant-franklinwh - Choose category Integration and click Add.
- Search for FranklinWH in HACS and click Download.
- Restart Home Assistant.
- Download this repository as a ZIP file.
- Extract the contents to your Home Assistant
custom_components/franklin_wh/directory. - Restart Home Assistant.
-
Go to Settings → Devices & Services.
-
Click + Add Integration.
-
Search for FranklinWH.
-
Enter your credentials:
- Email Address: Your FranklinWH account email
- Password: Your FranklinWH account password
- Gateway ID: Find this in the FranklinWH app under More → Site Address → SN
- Use Local API (optional): Enable for experimental local communication
- Local Host (optional): IP address of your FranklinWH gateway
-
Click Submit and your devices will be added automatically!
⚠️ Note: YAML configuration is deprecated and will be removed in a future version. Please migrate to Config Flow setup above.
Click to expand legacy YAML configuration
# This is the old configuration method - NOT RECOMMENDED
# Please use Config Flow instead
sensor:
- platform: franklin_wh
username: "email@domain.com"
password: !secret franklinwh_password
id: "100xxxxxxxxxxxx"
switch:
- platform: franklin_wh
username: "email@domain.com"
password: !secret franklinwh_password
id: "100xxxxxxxxxxxx"
switches: [1, 2, 3]
name: "All Switches"After setup, all entities will be organized under a single FranklinWH device:
| Entity | Description | Unit |
|---|---|---|
| State of Charge | Battery state of charge | % |
| Battery Use | Battery charging/discharging rate (negative = charging) | kW |
| Battery Charge | Total energy charged to battery | kWh |
| Battery Discharge | Total energy discharged from battery | kWh |
| Battery Charge from Grid | Energy charged to battery from grid (calculated) | kWh |
| Home Load | Instantaneous home power consumption | kW |
| Grid Use | Net grid power (negative = importing, positive = exporting) | kW |
| Grid Import | Total energy imported from grid | kWh |
| Grid Export | Total energy exported to grid | kWh |
| Solar Production | Instantaneous solar power generation | kW |
| Solar Energy | Total solar energy produced | kWh |
| Generator Use | Generator power output (live) | kW |
| Generator Energy | Total generator energy produced | kWh |
| Switch 1 Load | Power draw on Switch 1 | W |
| Switch 1 Lifetime Use | Total energy used by Switch 1 | kWh |
| Switch 2 Load | Power draw on Switch 2 | W |
| Switch 2 Lifetime Use | Total energy used by Switch 2 | kWh |
| V2L Use | Power via Vehicle-to-Load | W |
| V2L Import | Total energy drawn from V2L | kWh |
| V2L Export | Total energy delivered to V2L | kWh |
| Home Energy Total | Total energy consumed by home | kWh |
| Entity | Description |
|---|---|
| Switch 1 | Control smart circuit 1 |
| Switch 2 | Control smart circuit 2 |
| Switch 3 | Control smart circuit 3 |
| Grid Connection | Monitor and control grid connection status |
The integration provides custom services for advanced control:
Set the operation mode of your FranklinWH system.
Parameters:
mode: Operation mode (self_use,backup,time_of_use,clean_backup)
Example:
service: franklin_wh.set_operation_mode
data:
mode: self_useSet the minimum battery reserve percentage.
Parameters:
reserve_percent: Minimum battery charge to maintain (0-100)
Example:
service: franklin_wh.set_battery_reserve
data:
reserve_percent: 20All energy sensors are compatible with Home Assistant's Energy Dashboard:
- Go to Settings → Dashboards → Energy
- Configure your energy sources:
- Solar Production: Use "Solar Energy" sensor
- Battery: Use "Battery Charge" and "Battery Discharge" sensors
- Battery from Grid: Use "Battery Charge from Grid" sensor (calculated)
- Grid: Use "Grid Import" and "Grid Export" sensors
- Check Settings → System → Logs for errors containing
franklin_wh - Verify your credentials are correct
- Confirm your Gateway ID is correct (found in FranklinWH app)
- Ensure FranklinWH cloud services are online
- Try re-authenticating:
- Go to Settings → Devices & Services
- Find your FranklinWH integration
- Click Configure → Re-authenticate
- Verify your password is correct
- Check your internet connection
- Verify the FranklinWH cloud service is accessible
- Check the integration logs for API errors
- Try reloading the integration
If you see "Device response timed out":
- Verify gateway is online: Check the FranklinWH mobile app
- Check Gateway ID: Must be exact SN from app (More → Site Address → SN)
- FranklinWH cloud status: Service may be temporarily down
- Disable local API: If enabled, switch back to cloud polling
- Wait and retry: Gateway may be rebooting or updating
The local API is experimental and may not work:
- Most users should use cloud polling (default)
- Local API requires the gateway to support local communication
- If local API times out, disable it and use cloud polling
- Local API support depends on gateway firmware version
To get detailed diagnostic information:
- Go to Settings → Devices & Services
- Find your FranklinWH integration
- Click the device, then click Download Diagnostics
- Attach the diagnostics file when reporting issues
This integration includes experimental support for local API communication. Currently, the FranklinWH library primarily uses cloud polling, but local API support is being explored.
To enable local API (when available):
- Enable "Use Local API" during setup
- Enter your gateway's local IP address
- The integration will attempt local communication with faster polling (10 seconds vs 60 seconds)
📝 Note: Local API support depends on the underlying
franklinwhPython library and may not be fully functional yet. This is an area of active development.
Contributions are welcome! Please fork the repository and open a pull request:
👉 https://github.com/JoshuaSeidel/homeassistant-franklinwh
- Clone the repository
- Install development dependencies
- Use VS Code with Dev Containers for a consistent environment
- Test your changes thoroughly before submitting
When reporting issues, please:
- Download diagnostics from your integration
- Include Home Assistant and integration versions
- Provide relevant log entries
- Describe steps to reproduce
- ⬆️ UPGRADED: Updated to franklinwh library 1.0.0
- ✨ NEW: Full operation mode control (self_use, backup, time_of_use)
- ✨ NEW: Battery reserve percentage setting
- ✨ NEW: Grid connection switch for monitoring and control
- ✨ NEW: Home Energy Total sensor (total home consumption)
- 🐛 FIXED: Integration now properly works with franklinwh 1.0.0 API
- ♻️ IMPROVED: Updated imports to use properly exported classes
- 📝 DOCS: Updated README to reflect available features
- ⬆️ UPGRADED: Updated to franklinwh library 1.0.0
- ✨ NEW: Full operation mode control (self_use, backup, time_of_use)
- ✨ NEW: Battery reserve percentage setting
- ✨ NEW: Grid connection switch for monitoring and control
- ✨ NEW: Home Energy Total sensor (total home consumption)
- 🐛 FIXED: Integration now properly works with franklinwh 1.0.0 API
- ♻️ IMPROVED: Updated imports to use properly exported classes
- 📝 DOCS: Updated README to reflect available features
- 🐛 CRITICAL FIX: Removed Grid Connection switch (requires unreleased library version)
- 🐛 FIXED: ImportError for AccessoryType and GridStatus classes
- 🐛 FIXED: Integration now loads successfully with franklinwh 0.4.1
- ℹ️ NOTE: Smart circuit switches (1-3) still work correctly
- 🐛 CRITICAL FIX: Fixed Stats class import from franklinwh.client module
- 🐛 FIXED: "cannot import name 'Stats'" ImportError on setup
- 🐛 CRITICAL FIX: Corrected franklinwh package requirement to 0.4.1 (was incorrectly set to 0.5.0 which doesn't exist)
- 🐛 FIXED: "Requirements for franklin_wh not found" error on setup
- ✨ NEW: Battery Charge from Grid calculated sensor
- 🐛 FIXED: Entities no longer flicker unavailable during temporary failures
- 🐛 FIXED: Energy Dashboard compatibility (all sensors in kWh)
- ♻️ IMPROVED: Resilient coordinator with 3-failure grace period
- ♻️ IMPROVED: Better error logging and failure tracking
⚠️ NOTE: Grid Connection switch from this version removed in 1.0.7 (library compatibility)
- ✨ NEW: Modern config flow for UI-based setup
- ✨ NEW: DataUpdateCoordinator for efficient API polling
- ✨ NEW: Device registry integration
- ✨ NEW: Diagnostics support
- ✨ NEW: Experimental local API support
- ✨ NEW: Custom services (placeholders for future features)
- 🐛 FIXED: All typos and copy-paste errors in entity IDs
- 🐛 FIXED: Consolidated caching logic
- 🐛 FIXED: Improved error handling
- ♻️ REFACTOR: Complete code modernization
- ♻️ REFACTOR: Better entity organization
- Initial YAML-based platform configuration by @richo
- Basic sensor and switch support
This project is dual-licensed under:
- MIT License
- Apache License 2.0
You may choose either license when using or contributing to this project.
- Original Integration: @richo for the initial implementation
- Python Library:
franklinwh-pythonby @richo - Rewrite: Joshua Seidel with Anthropic Claude Sonnet 4.5
- Community: Thanks to the Home Assistant community
- Contributors: Special thanks to all contributors including @jkt628 for Grid Connection switch
This integration is not affiliated with, endorsed by, or supported by FranklinWH. Use at your own risk. The developers are not responsible for any damage to your system or equipment.
Enjoy your FranklinWH integration! 🎉
For support, please open an issue on GitHub.