franklinwh-modbus-async

An async Python library for the FranklinWH aGate. It talks Modbus TCP and covers the SunSpec models and the vendor extension registers. It is built on modbus-connection.

This is the asyncio successor to franklinwh-modbus, which is synchronous. It aims to match that library's features and to fix its known connection and threading defects. To find out why it exists and how it compares, read docs/why.md.

Status: pre-alpha (Phase 2 of 7). Connection, SunSpec discovery, typed status reads and a read-only CLI work. Battery control comes next. See PLAN.md for the roadmap.

⚠️ Unofficial software

About this software

• Not affiliated with, endorsed or supported by FranklinWH. FranklinWH and aGate are trademarks of their owners.
• Provided as is, without warranty, for educational and informational use.

Write commands carry real risk

• This library can send write commands to grid-connected battery hardware.
• Used incorrectly, it can discharge your battery when you need it, import power you did not intend to, or leave the system in an unexpected state.
• You use it at your own risk.

Getting help

• Do not contact FranklinWH support about this library. Report problems here.

Requirements

• An aGate with Modbus TCP enabled (ask your installer), reachable on TCP port 502. A fixed IP and a wired LAN are recommended.
• Python 3.12 or later.

Try it

pip install --pre franklinwh-modbus-async   # Python 3.12+; --pre while in alpha
fwh-async -i demo --status               # built-in simulated aGate, no hardware needed
fwh-async -i 192.0.2.10 --status         # your aGate (read-only); same syntax as franklinwh-modbus
fwh-async -i 192.0.2.10 --scan           # SunSpec base address and models
echo FRANKLINWH_HOST=192.0.2.10 > .env   # then just: fwh-async --status

import asyncio
from franklinwh_modbus_async import FranklinWH

async def main() -> None:
    async with FranklinWH.tcp("192.0.2.10") as agate:   # discovers the SunSpec map; never writes
        s = await agate.snapshot()                      # one atomic read
        print(s.battery.soc_pct, s.battery.power_w)     # 55.0 -500.0  (+ = charging)
        print(s.grid.power_w, s.home.load_w)            # -2.0 498.0   (+ = import)

asyncio.run(main())

Develop

To work on the library from source:

git clone git@github.com:david2069/franklinwh-modbus-async.git
cd franklinwh-modbus-async
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install
pytest

Roadmap

Documentation

Contributing

PRs are welcome. CI runs ruff, mypy --strict, pytest and a PII guard (tools/pii_check.py).

• Placeholders only. In code, docs, examples and captured output, use:
  • 192.0.2.10 for hosts
  • FWH-SN-REDACTED for serials
  • 00:00:5E:00:53:00 for MAC addresses
• Private terms. Put anything you want blocked in a local .pii-denylist. git ignores this file.

License

MIT. See LICENSE.