pyhelty

Async Python client for Helty Flow VMC (mechanical ventilation / MVHR) units equipped with the smart Wi-Fi interface, such as the Flow Plus.

It speaks the unit's reverse-engineered TCP protocol (default port 5001) and exposes a small, fully typed asyncio API. It is the device-communication layer behind the Home Assistant helty integration; it has no Home Assistant dependency and can be used standalone.

The protocol has no official specification. Behaviour is reverse-engineered from a real Helty FlowPlus; your mileage may vary on other models.

Install

pip install pyhelty

Usage

import asyncio
from pyhelty import HeltyClient, FanMode

async def main() -> None:
    client = HeltyClient("192.168.1.50")  # port defaults to 5001

    data = await client.async_get_data()
    print(data.name, data.fan_mode, data.indoor_temperature, data.indoor_humidity)

    await client.async_set_fan_mode(FanMode.NIGHT)
    await client.async_set_led(False)

asyncio.run(main())

API

• HeltyClient(host, port=5001, *, timeout=10.0)
• async_get_name() -> str — the user-assigned name (also used as a stable id)
• async_get_data() -> HeltyData — name, fan mode, LED state, indoor/outdoor temperature, indoor humidity, plus co2, filter_hours and light_level (model-dependent — see below), and the raw VMGI/VMGO integer fields
• async_set_fan_mode(mode: FanMode) — OFF, LOW, MEDIUM, HIGH, MAX, BOOST, NIGHT, FREE_COOLING
• async_set_led(on: bool)
• async_reset_filter()
• async_set_light(level: int) — front-light brightness 0-100 (0 = off)

Model-dependent fields

co2, filter_hours and light_level are only meaningful on models that have the corresponding hardware. A Helty FlowPlus, for example, reports co2 == 0 (no sensor) and accepts the light command without a physical light. The consuming application should decide whether to surface them (e.g. only when co2 > 0).

Errors derive from HeltyError: HeltyConnectionError, HeltyResponseError, HeltyCommandError.

Protocol notes

The unit serves one command per TCP connection and then closes it; the client serialises commands with a lock.

Development

pip install -e ".[test,dev]"
pytest
ruff check .
mypy src

Acknowledgements

The TCP protocol has no official specification; it was reverse-engineered with the help of the prior work of @MatteoManzoni and @DanRobo76. Thanks to both.

License

MIT