Metadata-Version: 2.4
Name: husdata-h66-modbus
Version: 0.1.1
Summary: Async Modbus TCP library for the Husdata H66 heat pump gateway
Author-email: Jonny Bergdahl <bergdahl@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jonnybergdahl/Python-husdata-h66-modbus
Project-URL: Repository, https://github.com/jonnybergdahl/Python-husdata-h66-modbus
Project-URL: Documentation, https://jonnybergdahl.github.io/husdata-h66-modbus/
Project-URL: Issues, https://github.com/jonnybergdahl/Python-husdata-h66-modbus/issues
Keywords: husdata,h66,modbus,heat pump,ivt,rego,home assistant
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: modbus-connection>=4.12
Provides-Extra: cli
Requires-Dist: modbus-connection[pymodbus]>=4.12; extra == "cli"
Dynamic: license-file

# husdata-h66-modbus

Async Python library for the Modbus TCP interface of the [Husdata H66](https://husdata.se/produkt/h66-wifi-eth-gateway-styr-din-varmepump/) heat pump gateway.

It is built on [modbus-connection](https://github.com/home-assistant-libs/modbus-connection), the Modbus layer Home Assistant uses from 2026.9. The library never opens a connection itself: you give it a `ModbusUnit`, either from `modbus_connection` or from Home Assistant's `async_get_unit`. It has no Home Assistant dependency.

Tested with an H66 on firmware 360801 connected to an IVT Greenline (Rego 600 controller).

## Installation

```bash
pip install husdata-h66-modbus
```

Add the `cli` extra to get the pymodbus backend and the `husdata-h66` command line tool:

```bash
pip install "husdata-h66-modbus[cli]"
```

## Documentation

The full library documentation can be [found here](https://jonnybergdahl.github.io/husdata-h66-modbus/).

## Enable Modbus on the H66

Modbus TCP is off by default. On the H66 web page, open **Config** > **Modbus**, set `MODBUS_PORT` to `502` and restart the H66. `MODBUS_IP` can limit which client may connect. The H66 accepts only one Modbus client at a time.

## Usage

```python
import asyncio

from modbus_connection import ModbusTcpParams
from modbus_connection.pymodbus import ModbusConnection

from husdata_h66 import HusdataH66


async def main() -> None:
    connection = ModbusConnection(ModbusTcpParams(host="h66.local"))
    try:
        device = HusdataH66(connection.for_unit(1))
        await device.async_update()
        print(device.get("outdoor"))  # 3.5 (°C)
        print(device.get("compressor"))  # True
        print(device.values)  # everything, keyed by register key

        await device.async_set("room_setpoint", 21.5)
    finally:
        await connection.close()


asyncio.run(main())
```

In Home Assistant, pass the unit from `async_get_unit` instead:

```python
unit = async_get_unit(
    hass, entry, ModbusTcpParams(host=entry.data[CONF_HOST]), entry.data[CONF_UNIT_ID]
)
entry.runtime_data = HusdataH66(unit)
```

`async_update()` reads all registers in three requests and returns an `UpdateReport`. It raises `ModbusConnectionError` or `ModbusTimeoutError` when the gateway cannot be reached.

`async_set()` takes the value in the register's own unit and checks it against the register's range and step. It raises `ValueError` for an invalid value and `AttributeError` for a read-only register. `async_reset_alarm()` writes 0 to **Alarm reset**, which turns the heat pump off for 10 seconds and then on again.

From the command line (read-only):

```bash
husdata-h66 h66.local
```

## Register map

The H66 numbers its Modbus registers one per parameter, in the order its home page lists them. Read-only parameters are INPUT registers, settings are HOLDING registers, and every register is a signed or unsigned 16-bit value. The addresses depend on the heat pump controller and can move after a firmware update or when you add custom registers in the H66.

`REGO600_REGISTERS` is the default map, for a Rego 600 controller on firmware 360801. To follow the H66 instead, fetch its home page and parse it:

```python
from husdata_h66 import HusdataH66, parse_firmware_version, parse_registers

page = await (await session.get("http://h66.local/")).text()
device = HusdataH66(unit, parse_registers(page))
```

`husdata-h66 h66.local --from-web` does the same from the command line.

Each parameter has a Husdata variable ID. Its first hex digit gives the type and scaling:

| First digit | Type | Scale | Unit |
|---|---|---|---|
| 0 | Temperature | 0.1 | °C |
| 1 | Status | 1 | on/off |
| 2 | Number | 0.1 | |
| 3 | Percent | 0.1 | % |
| 5 | Energy | 0.1 | kWh |
| 6 | Hours | 1 | h |
| 7 | Minutes | 1 | min |
| B | Integer | 1 | |
| C | Power | 1 | W |

Temperatures and numbers are signed, the others unsigned. A temperature sensor that isn't connected reads `None` (the H66 shows −48.3 °C).

### Rego 600 (default map)

| Address | Type | ID | Key | Range |
|---|---|---|---|---|
| 0 | Input | 0001 | `radiator_return` | |
| 1 | Input | 0002 | `radiator_forward` | |
| 2 | Input | 0003 | `heat_carrier_return` | |
| 3 | Input | 0004 | `heat_carrier_forward` | |
| 4 | Input | 0005 | `brine_in` | |
| 5 | Input | 0006 | `brine_out` | |
| 6 | Input | 0007 | `outdoor` | |
| 7 | Input | 0008 | `indoor` | |
| 8 | Input | 0009 | `hot_water_top` | |
| 9 | Input | 000A | `hot_water_mid` | |
| 10 | Input | 000B | `hot_gas` | |
| 11 | Input | 3104 | `add_heat_status` | |
| 12 | Input | 0107 | `heating_setpoint` | |
| 13 | Input | 0111 | `hot_water_setpoint` | |
| 14 | Holding | 0203 | `room_setpoint` | 5–29 °C |
| 15 | Holding | 2204 | `room_sensor_influence` | |
| 16 | Holding | 2205 | `heat_curve` | 0–10 |
| 17 | Holding | 0207 | `heat_curve_parallel` | −10–10 °C |
| 18 | Holding | 0208 | `hot_water_stop_temperature` | 20–60 °C |
| 19 | Holding | 020B | `hot_water_difference` | 2–15 °C |
| 20 | Holding | 7209 | `extra_hot_water` | 0–1440 min |
| 21 | Holding | 1215 | `electric_heater_allowed` | on/off |
| 22 | Holding | B21B | `electric_heater_max_power` | 1 (3 kW), 2 (6 kW) or 4 (9 kW) |
| 23 | Holding | 1233 | `external_control` | on/off, write-only |
| 24 | Holding | 020A | `summer_mode` | 0–30 °C |
| 25 | Holding | 2210 | `holiday_mode` | 0–30 days |
| 26 | Holding | 12F2 | `alarm_reset` | write 0 to reset |
| 27 | Input | 1A01 | `compressor` | |
| 28 | Input | 1A02 | `add_heat_step_1` | |
| 29 | Input | 1A03 | `add_heat_step_2` | |
| 30 | Input | 1A04 | `pump_cold_circuit` | |
| 31 | Input | 1A05 | `pump_heat_circuit` | |
| 32 | Input | 1A06 | `pump_radiator` | |
| 33 | Input | 1A07 | `switch_valve_1` | off: heating, on: hot water |
| 34 | Input | 1A20 | `alarm` | |
| 35 | Input | BA91 | `alarm_code` | last alarm, see below |
| 36 | Input | 6C55 | `compressor_hours_heating` | |
| 37 | Input | 6C56 | `compressor_hours_hot_water` | |
| 38 | Input | 6C58 | `aux_heater_hours_heating` | |
| 39 | Input | 6C59 | `aux_heater_hours_hot_water` | |
| 40 | Input | CFAA | `power_consumption` | |
| 41 | Input | 5FAB | `accumulated_consumption` | |

`power_consumption` and `accumulated_consumption` are calculated by the H66 from the wattages set for each status variable on its web page. `accumulated_consumption` restarts at 0 when the H66 boots.

The meanings and ranges come from Husdata's [variable list for Rego 600/637](https://online.husdata.se/h-docs/C00.pdf). Some details from it:

- `alarm_code` is the last alarm that triggered, even if no alarm is active now. `alarm_text(code)` and `ALARM_CODES` give its description.
- `external_control` is write-only: the value read back means nothing. Husdata warns it can behave unpredictably on a Rego 600.
- `electric_heater_allowed` takes effect the next time the electric heater would start.
- `holiday_mode` is in days. While it is active, set it to 0 before setting a new value.

Not yet verified: `room_sensor_influence` is read unscaled because the H66 web page shows it that way, and `holiday_mode` is assumed to be stored ×10 like the other 2xxx numbers.

### Alarm codes

| Code | Alarm |
|---|---|
| 1 | Sensor radiator return (GT1) |
| 2 | Outdoor sensor (GT2) |
| 3 | Sensor hot water (GT3) |
| 4 | Mixing valve sensor (GT4) |
| 5 | Room sensor (GT5) |
| 6 | Sensor compressor (GT6) |
| 7 | Sensor heat fluid out (GT8) |
| 8 | Sensor heat fluid in (GT9) |
| 9 | Sensor cold fluid in (GT10) |
| 10 | Sensor cold fluid out (GT11) |
| 11 | Compressor circuit switch |
| 12 | Electrical cassette |
| 13 | Pump circuit switch (MB2) |
| 14 | Low pressure switch (LP) |
| 15 | High pressure switch (HP) |
| 16 | High return HP (GT9) |
| 17 | Heat carrier out max (GT8) |
| 18 | Brine in under limit (GT10) |
| 19 | Brine out under limit (GT11) |
| 20 | Compressor superheat (GT6) |
| 21 | 3-phase incorrect order |
| 22 | Power failure |
| 23 | Heat delta exceeded |

## Development

```bash
uv sync
uv run pytest
uv run ruff check src tests
```

`build.sh` publishes a release: it converts this README to `README.rst`, builds the documentation, copies it to the `jonnybergdahl.github.io` repository and pushes it, then builds the package and uploads it to PyPI.

## License

MIT
