FranklinWH Direct Connect Bridge¶

An unofficial local REST + MQTT bridge and web UI for the FranklinWH aGate, using the gateway's Direct Connect local API. It runs as a Home Assistant add-on, in Docker, or standalone.

Unofficial software

This is an UNOFFICIAL app - NOT affiliated with, or endorsed by, FranklinWH.

It talks to FranklinWH's undocumented Direct Connect (local) API and its cloud API - technically the SAME private API the official FranklinWH mobile app (and the FleetView installer portal) use, intended for those apps and not for third parties - plus the standard SunSpec Modbus TCP API (with undocumented FranklinWH extensions). Any of these may change, break, or become unavailable without notice.

Provided AS-IS, without warranty of any kind. Use entirely at your own risk - the authors accept no liability for data loss, equipment damage, or service loss.

Do NOT contact FranklinWH support about this app. Raise issues, defects, or feature requests on GitHub instead.

Keep your system compliant with the settings your official FranklinWH app / installer configured. Using this tool to bypass safety, grid-compliance, or programme restrictions is at your own risk and is not condoned. Provided AS-IS for education/information; any use (personal or commercial) is permitted under the MIT Licence and entirely at your own risk. Please keep this notice with copies and forks (see Full terms).

Documentation · GitHub Issues · Full terms

Questions, ideas and help: GitHub Discussions¶

Join the conversation on GitHub Discussions. Everyone is welcome, technical or not; you don't need to know any code. Ask or talk about anything to do with the bridge or FranklinWH home batteries:

installing it, or getting it running in Home Assistant or Docker;
something not working, or looking wrong;
an idea or a feature you'd like;
the documentation: what's unclear or missing;
your own setup, and related topics.

Not sure whether it's a defect? Start a discussion. It can be turned into an issue later. If you already know it's a defect, you can also raise it in GitHub Issues.

Full terms¶

The bridge's licence: the MIT License and its Additional Terms. This is the repository's LICENSE file, included here as it stands, and the page the in-app Full terms link opens.

MIT License

Copyright (c) 2026 david2069

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


================================================================================
ADDITIONAL TERMS
================================================================================

These Additional Terms accompany and supplement the MIT License above. By using,
copying, modifying, or distributing the Software you accept them.

1. UNOFFICIAL — NO AFFILIATION
   This is UNOFFICIAL software, NOT affiliated with, endorsed by, or supported by
   FranklinWH. It interfaces with FranklinWH's undocumented Direct Connect (local)
   API and its cloud API — technically the same private API the official FranklinWH
   mobile app and the FleetView installer portal use, intended for those apps and not
   for third-party use — plus the standard SunSpec Modbus TCP API (with undocumented
   FranklinWH extensions). Any of these may change, break, or become unavailable
   without notice. Do
   NOT contact FranklinWH support about this Software — raise issues, defects, or
   feature requests on GitHub:
   https://github.com/david2069/franklinwh-direct-connect-bridge/issues

2. COMPLIANCE & ANTI-CIRCUMVENTION
   You agree to keep your gateway and battery settings, controls, and operation
   compliant with the configuration set through the official FranklinWH Mobile App
   and the installer/support FleetView portal.

   FranklinWH-managed settings may exist to, among other things:
     - protect the safety and longevity of the battery and gateway;
     - apply automatic software updates and restrict your ability to view or change
       battery, grid-import, or grid-export controls;
     - enforce your local electricity grid profile and any import/export limits or
       prohibitions;
     - enforce restrictions tied to contractual incentives, subsidies, or VPP/grid
       programmes.

   If you use this Software to bypass or override any such control, restriction, or
   compliance measure — deliberately or inadvertently — you do so entirely at your
   own risk. This is neither condoned nor encouraged by the authors or any other
   party.

3. INTENT & RISK
   This Software is provided for informational and educational purposes, AS-IS,
   with no warranty of fitness for any purpose. Any use — personal or commercial
   — is permitted under the MIT License above and is entirely at your own risk.

4. NOTICE
   As the MIT License above requires, the copyright notice and this permission
   notice (including these Additional Terms) shall be included in all copies or
   substantial portions of the Software. Retaining it in copies, forks, derivatives,
   and AI-assisted works keeps the unofficial-app, compliance, and support context
   travelling with the code.

Start here¶

User guide: the web UI, the scheduler, Home Assistant and MQTT, controls, energy and costs, several gateways.
Developers Guide: the REST API and OpenAPI schema, how the web UI uses it, the MQTT topics, reading Home Assistant, and an end-to-end Scheduler example.
Installing: see INSTALL.md and the add-on's DOCS.md.
What changed: the CHANGELOG.

How it is built and released¶

Test and release policy: the gates every release passes.
Feature parity with the FranklinWH Modbus Bridge and FWHAI.

Libraries and tools from the same author. Each is unofficial, like this bridge.

Project	What it is	Docs	Package
franklinwh-direct-connect-api	The Direct Connect (local) API library and CLI this bridge is built on	site	PyPI
franklinwh-cloud	The FranklinWH cloud API library, used by the bridge's cloud features	site	PyPI
franklinwh-modbus	The Modbus TCP (SunSpec) library and battery control, used by the bridge's Modbus client	site	PyPI
franklinwh-modbus-bridge	A separate bridge that reads the aGate over Modbus TCP and publishes it, with its own Discussions	site	n/a
franklinwh-gateway-emulator	An aGate emulator for testing without hardware	repo	n/a

FranklinWH Direct Connect Bridge¶

Questions, ideas and help: GitHub Discussions¶

Full terms¶

Start here¶

How it is built and released¶

Related FranklinWH projects¶