Metadata-Version: 2.5
Name: pydimplex-nwpm
Version: 0.2.0
Summary: Asynchronous client for the Dimplex NWPM Touch heat pump gateway (MQTT and Modbus TCP)
Project-URL: Homepage, https://github.com/p-atr/pydimplex-nwpm
Project-URL: Repository, https://github.com/p-atr/pydimplex-nwpm
Project-URL: Issues, https://github.com/p-atr/pydimplex-nwpm/issues
Project-URL: Changelog, https://github.com/p-atr/pydimplex-nwpm/blob/main/CHANGELOG.md
Author: patr_
License-Expression: MIT
License-File: LICENSE
Keywords: dimplex,heat pump,home-assistant,modbus,mqtt,nwpm
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: aiomqtt<3,>=2.3
Requires-Dist: paho-mqtt<3,>=2.1
Requires-Dist: pymodbus<4,>=3.10
Provides-Extra: dev
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# pydimplex-nwpm

Asynchronous Python client for the **Dimplex NWPM Touch** heat pump gateway
(also built into Dimplex *System M* heat pumps). The gateway exposes the heat
pump manager (WPM) over a local MQTT broker and optionally over Modbus TCP;
this library wraps both transports with an asyncio-native API and no cloud
dependency.

It is the protocol layer of the Home Assistant `dimplex_nwpm` integration but
has no Home Assistant dependency and can be used on its own.

## Features

- `DimplexHeatPump`: a model of the heat pump manager with a table of about
  200 named values (`DATAPOINTS`) including scaling, message tables, write
  limits and the equipment flag each value depends on.
- Push updates (changed values, device twin, fault and lock history) merged
  with periodic polling of everything the gateway does not push.
- Composite energy counters that never jump because of partial push updates.
- MQTT v5 request/response (response topic and correlation data) on top of
  [aiomqtt](https://pypi.org/project/aiomqtt/), with automatic reconnect and
  a distinct authentication error.
- Optional Modbus TCP for values the MQTT interface does not expose.
- Fully typed (`py.typed`).

## Installation

```bash
pip install pydimplex-nwpm
```

Requires Python 3.12 or newer.

## Usage

```python
import asyncio
from datetime import datetime, timezone

from pydimplex_nwpm import DATAPOINTS, DimplexHeatPump, Equipment


async def main() -> None:
    heat_pump = DimplexHeatPump("192.168.1.42", "80B56598", use_modbus=True)
    heat_pump.subscribe(
        lambda: print("outdoor:", heat_pump.value("outdoor_temperature"))
    )

    twin = await heat_pump.connect()
    print("serial:", twin.appliance_serial, "software:", twin.appliance_version)

    await heat_pump.update()  # poll; repeat periodically, e.g. once a minute
    print("hot water installed:", heat_pump.has(Equipment.HOT_WATER))
    for key in DATAPOINTS:
        if heat_pump.supports(key):
            print(key, heat_pump.value(key))

    await heat_pump.set("operating_mode", "auto")
    await heat_pump.set("hot_water_setpoint", 50)
    await heat_pump.set_time(datetime.now(timezone.utc).astimezone())

    await heat_pump.disconnect()


asyncio.run(main())
```

`value()` returns scaled numbers, booleans, message option strings (e.g.
`"heating"`) or energy counter totals, and `None` while a value is unknown.
`supports()` is `False` for values of equipment that is not installed and for
Modbus-only values when Modbus TCP is disabled.

## Datapoint naming

Datapoints are addressed by the pCO variable index followed by a type suffix:

| Suffix | Type | Value |
| --- | --- | --- |
| `d` | digital | `True` / `False` |
| `i` | signed 16 bit integer | `int` |
| `u` | unsigned 16 bit integer | `int` (same variable as `i`) |
| `a` | analog | `float`, already scaled by the gateway |

Ranges such as `1500-1502d` read several consecutive variables in one request.
`u` and `i` names are normalised to `i`, which is also the key used in
`DimplexHeatPump.values`.

The gateway password is shown on the heat pump display under
*Analytics → Hardware and software → Network → Gateway access*; the MQTT user
name is always `mqtt`.

## Development

```bash
pip install -e ".[dev]"
ruff check . && ruff format --check .
mypy
pytest
```

## References

- [Dimplex Wiki: MQTT Anbindung](https://dimplex.atlassian.net/wiki/spaces/DW/pages/3021930597/MQTT+Anbindung)
- [Dimplex Wiki: Modbus TCP Anbindung](https://dimplex.atlassian.net/wiki/spaces/DW/pages/3303571457/Modbus+TCP+Anbindung)

## License

MIT — see [LICENSE](LICENSE).
