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 0 of 7). The tooling and docs are in place, but there is no device API yet. 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.

Install

The library is not on PyPI yet. To work on it 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.