Metadata-Version: 2.4
Name: aio-remeha-modbus
Version: 1.0.0b4
Summary: Async I/O modbus API for Remeha appliances
Author: houthacker
License-Expression: LGPL-3.0-or-later
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Dist: pydantic>=2.13.4
Requires-Dist: modbus-connection>=4.12.1
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/houthacker/aio-remeha-modbus
Project-URL: Issues, https://github.com/houthacker/aio-remeha-modbus/issues
Project-URL: Funding, https://buymeacoffee.com/houthacker
Project-URL: Documentation, https://aio-remeha-modbus.readthedocs.io
Description-Content-Type: text/markdown

# Async I/O  modbus API for Remeha appliances

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="./assets/dark_logo.png">
  <img alt="Remeha logo" src="./assets/logo.png">
</picture>

![GitHub License](https://img.shields.io/github/license/houthacker/aio-remeha-modbus)
[![ci](https://github.com/houthacker/aio-remeha-modbus/actions/workflows/ci.yaml/badge.svg)](https://github.com/houthacker/aio-remeha-modbus/actions/workflows/ci.yaml)
[![badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/houthacker/ab326b4825c5466a103921f42bf79ba9/raw/86a287f059442adaca5578e5c3a80b07239eb501/aio-remeha-modbus-cov-badge.json)](https://github.com/houthacker/aio-remeha-modbus/actions/workflows/coverage.yaml)

`aio-remeha-modbus` is an async python API for Remeha appliances.

## Installation
Add this library to your project from [PyPI](https://pypi.org) using
```bash
$ uv add aio-remeha-modbus>=1.0.0beta4
```

or build it locally by checking out the source of this project and
```bash
$ uv build
...
$ uv pip install dist/*.whl
```

## Exposed API
The API is documented at [readthedocs](https://aio-remeha-modbus.readthedocs.io/en/latest/). A short textual description of the most important classes and their hierarchy is shown below.

## cli tool
This library also includes a cli tool to query your Remeha appliance. After installing this library, you can use `remeha-query` or if you prefer, you can run it from the cli yourself using `python src/query.py`.

### Examples
Query the 2nd zone of an appliance that uses an RTU over TCP connection at `192.168.1.2` and port 8899:
```bash
$ remeha-query --transport serial socket://192.168.1.2:8899 --zone 2
```

Query all components
```bash
$ remeha-query --transport serial socket://192.168.1.2:8899 --all
```

#### Caching
To retrieve fetch data from modbus, call `await RemehaApi.async_update()` explicitly. After that, the values are retained until the next update call.

The discovery table in `RemehaApi.discovery_table` is read only at the first call to `async_update()`. To re-read the discovery table, restart the process running this API.

#### Error handling
All errors raised by this library are intended to be translated.
To facilitate that, the base error class contains a `translation_key` field to look up the translation
and a `translation_placeholders` field. This is a `dict` to be used when extrapolating the error message.

### Configuration
`aio-remeha-modbus` uses [modbus-connection](https://pypi.org/project/modbus-connection/) to talk
to your appliances, and is agnostic to the way a connection is obtained.

To create a new api instance, you need to obtain a `ModbusUnit` first. See [the modbus-connection docs](https://home-assistant-libs.github.io/modbus-connection/connection/connections-and-units/)
on how to do that.

### RemehaApi
To create a new API instance, provide the `ModbusUnit` instance to the `RemehaApi` constructor.

### Appliance
The connected Remeha appliance can be retrieved using `RemehaApi.appliance`.

### ClimateZone
Zones, as they are configured in the Remeha appliance are exposed as `ClimateZone` instances
and can be retrieved using `RemehaApi.zones`.

### Zone schedules
When a `ClimateZone` is read from the appliance and its `mode` is `ClimateZoneMode.SCHEDULING`,
the schedules for each `Weekday` are available through `ClimateZone.current_schedule` as
instances of `api.schedule.ZoneSchedule`.