Metadata-Version: 2.5
Name: franklinwh-modbus-async
Version: 0.0.1
Summary: Async FranklinWH aGate Modbus TCP library (SunSpec + extension registers) built on modbus-connection
Project-URL: Homepage, https://github.com/david2069/franklinwh-modbus-async
Project-URL: Bug Tracker, https://github.com/david2069/franklinwh-modbus-async/issues
Project-URL: Changelog, https://github.com/david2069/franklinwh-modbus-async/blob/main/CHANGELOG.md
Author-email: david2069 <david2069@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agate,asyncio,battery,energy,franklinwh,modbus,sunspec
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Classifier: Topic :: System :: Hardware
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: modbus-connection[tmodbus]~=4.12.4
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Provides-Extra: pymodbus
Requires-Dist: modbus-connection[pymodbus]~=4.12.4; extra == 'pymodbus'
Description-Content-Type: text/markdown

# 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`](https://github.com/home-assistant-libs/modbus-connection).

This is the asyncio successor to [`franklinwh-modbus`](https://github.com/david2069/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](https://github.com/david2069/franklinwh-modbus-async/blob/main/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](https://github.com/david2069/franklinwh-modbus-async/blob/main/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](https://github.com/david2069/franklinwh-modbus-async/issues).

## 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:

```bash
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

| Phase | Scope | State |
|---|---|---|
| 0 | Scaffold, CI, PII guard, rationale docs | ✅ |
| 1 | Connection, SunSpec discovery, generated models, `FakeAGate` | — |
| 2 | Typed reads and snapshot | — |
| 3 | Control: M704 dispatch, watchdog, verify, native modes, safety | — |
| 4 | Virtual modes, TOU schedules, sequencer, discovery | — |
| 5 | CLI | — |
| 6 | Emulator and hardware verification | — |
| 7 | 1.0 release, migration guide | — |

## Documentation

| Page | |
|---|---|
| [Why this library](https://github.com/david2069/franklinwh-modbus-async/blob/main/docs/why.md) | Purpose, basis, why async, why modbus-connection, and how it compares with the alternatives |
| [modbus-connection findings](https://github.com/david2069/franklinwh-modbus-async/blob/main/docs/research/modbus-connection.md) | Notes from reviewing the transport library |
| [Plan](https://github.com/david2069/franklinwh-modbus-async/blob/main/PLAN.md) | Design decisions and phases |
| [Changelog](https://github.com/david2069/franklinwh-modbus-async/blob/main/CHANGELOG.md) | |

## 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](https://github.com/david2069/franklinwh-modbus-async/blob/main/LICENSE).
