Skip to content

v0.1.0

Choose a tag to compare

@ebaschiera ebaschiera released this 04 Sep 13:21

First release.

Async client for the hcloud backend of Helty, used by the recent control
panels of Helty Flow VMC units and by the "Helty Home" app. Those panels expose
no listening port, so control necessarily goes through the manufacturer's cloud;
this is the counterpart to pyhelty,
which speaks the local protocol of the previous generation.

The API is undocumented and was reconstructed by observing the app and the
traffic of a single unit, then checked against the manufacturer's own answers to
a technical enquiry. What is verified and what is guesswork is marked as such in
the README.

What it does

  • Cognito (USER_SRP_AUTH) login and REST access to the installation.
  • Reads the last telemetry the panel pushed to the cloud, without waking the
    panel: mode, indoor and outdoor temperature, humidity, CO2 and VOC when the
    optional sensors are fitted, and the two filter counters.
  • Sets the ventilation mode, and asks the panel to report back so the change can
    be confirmed.
  • Decodes the alarm word into named flags, keeping unknown bits rather than
    rejecting them, and tells a fault apart from automatic free cooling.

Known limits

  • CO2 and VOC are passed on unscaled: the manufacturer has not given a unit.
  • Panel state and the Auto flag cannot be read on this generation of machines.
  • The factory filter threshold (90,000 m3) is not readable over the API.
  • Commands taking an argument, and the filter reset, are not mapped.

Requires Python 3.12+.