Zum Hauptinhalt springen

Heatmiser neoHub Smart-Home-Integration, kostenlos und Open Source

Heatmiser neoHub-Integration für Gladys Assistant

Heatmiser neoStat thermostats through the neoHub, locally: zones, setpoints, standby, away.

Info

Die Dokumentation dieser Integration wird von ihrem Autor geschrieben und ist bisher nur auf Englisch verfügbar.

Brings the thermostat zones of a Heatmiser neoHub into Gladys, on your local network, through the official local API of the hub (a secure WebSocket on port 4243, authenticated by an API token of the hub). Unofficial, not affiliated with Heatmiser. Never tested with a real device yet: written from the official "neoHub API" document of IMI Heatmiser; your feedback is welcome.

What you get​

  • One device per thermostat zone (neoStat, neoAir): the room temperature, the setpoint, and the mode: Schedule (the zone follows its program) or Standby (frost protection: the zone holds its frost temperature).
  • One device for the hub: the away mode (Home / Away). Away puts every thermostat in standby and turns the time clocks and neoPlugs off (PDF of Heatmiser): it acts on everything the hub drives.
  • Time clocks, plugs and the time clock half of a combined neoAir are not shown in this version.

Setup​

  1. In the Heatmiser Neo app: Settings > API Access > Tokens, create a token.
  2. In Gladys, open the integration: type the IP address of the hub (shown in your router; give the hub a fixed address there) and the token, save.
  3. Click Test the connection once, from your home network: it reads the certificate the hub shows and learns its fingerprint (shown in the answer and in the status). It is learnt, not verified: the hub makes its own certificate, there is no authority to check it against. Someone who controls your local network at that very click could have his own certificate learnt instead and receive the token. To verify, compare the fingerprint shown with the one of your hub, read from a computer of your network: openssl s_client -connect \<hub address>:4243 \</dev/null 2>/dev/null | openssl x509 -noout -fingerprint -sha256. You may also type the fingerprint yourself instead of clicking. From then on, the token goes to that certificate only.
  4. Open the Discovery tab and add the zones and the hub.

The token is kept by Gladys in its database, never shown again, and sent only to the hub at the address you typed, over the learnt certificate. It does not appear in the logs, the status nor the files of the integration.

Commands​

Standby on a zone and Away on the hub need no option. Standby only lowers the heating of its zone; away puts every thermostat in standby and turns the time clocks and neoPlugs off. They are sent at once, before any other command waiting (a read of the hub stuck for 1 s is cut for them), addressed by the device number of the zone; the standbys of a scene leave together in one command. A hub that refuses device numbers gets the zone at once by the name its last read gave (one command per zone); one that answers numbers without doing anything gets it by name when the stop is sent again (about 90 s later, see below). Once the hub refused a number and then took the name, it is sent names from then on, also after a restart; a zone whose name holds a quote or a backslash still goes by its number. On a hub that ignores numbers, such a zone cannot get a standby from Gladys (the status and the badge say "not applied"): rename it in the Heatmiser Neo app. Gladys gets its answer within about 3.4 s; a stop that could not leave by then stays in line and leaves as soon as the hub is free. A stop is done as soon as a read of the hub shows it, and a change you make later in the app wins (never sent again). The hub refreshes its data about every 90 s: a stop it answered is "not yet visible" until a read sent at least 90 s after its answer; if that read does not show it, or the hub did not answer, the stop is sent again with the next reads (by number, and by name when the name can be sent), 3 times at most, and the status and the badge of the zone say so. That window lasts until the first read made 90 s or more after the answer, so up to the refresh interval when it is longer (600 s at most). A change made in the app during that window cannot be told from a stop not applied: it may be overwritten, 3 times at most. A newer Schedule (or Home) that left lifts the stop: it is not sent again, not even after a restart. A Schedule (or Home) refused before leaving (option off, pause, too late) leaves the stop to be sent. A command asked before a standby on the same zone (before an away, on any zone) that has not left yet is cancelled. What a stop needs all the same: the address, the token and the learnt certificate (without them nothing can be sent to the hub); it is refused when another hub answers at the address, and it is not sent again by itself after the hub refused the token (a click sends it, or a new token).

These commands are off by default and need the option Allow heating commands:

  • the setpoint of a zone (5 °C to the ceiling, 24 °C by default, rounded down to 0.5 °C, by steps of 0.5 °C);
  • Schedule on a zone (leaves the standby);
  • Home on the hub (leaves the away mode).

Each is decided on a fresh read of the hub (a read sent after the command arrived; the hub, the zone at its device number and its name at the previous read checked), addressed by the device number of the zone, sent within 2.8 s or refused unsent, then read back; Gladys gets its answer within about 3.4 s. As for the stops, a value the data of the hub does not show yet is "not shown yet", and is told as not applied only by a read made 90 s or more after it left (a follow-up read is made 95 s after). The same setpoint (or Schedule) asked of several zones at once leaves in one command; different setpoints leave one after the other, each within its own 2.8 s, the others refused unsent ("too late"). A setpoint is refused:

  • when the option is off, or the value is outside 5 °C to the ceiling or not a multiple of 0.5 °C;
  • while the zone is in standby, away or on holiday, or the hub is away or on holiday (choose Schedule or Home first);
  • for 10 minutes after a standby of the zone or an away of the hub, unless Schedule or Home has left since;
  • when the hub is set to °F (only °C is supported), or its unit is not read yet (again after any change of the system of the hub);
  • when the zone is offline, gone, or renamed since the previous read (try again); right after a restart, the name kept at the Scan and a read of the unit within the command are used;
  • when 8 commands already wait, during a pause after failed reads, after a refused token, or when its turn does not come in time (nothing sent).

Schedule and Home are refused when /data cannot keep that they lift a stop (nothing sent).

A command that may have reached the hub is never told "not sent": you get "sent, without confirmation" and the next reads show the result. No command goes through a switch: a "turn everything off" never reaches the heating.

Reads and pace​

The hub is read every 60 s by default (30 to 600 s; the hub refreshes its own data about every 90 s); the button, the Discovery tab or a restart never read it sooner than the interval. A command adds its own reads: one before it, one right after it, then 5 s and 20 s later. After a failure the integration waits 1, 2, 5, 10 then 15 minutes. A token refused by the hub stops the automatic reads until you type a new token or click Test the connection.

If the hub is replaced or reset, its certificate changes: nothing is sent and the status shows the new fingerprint; type it in the configuration once you have checked it is your hub.

Data​

/data/heatmiser-neohub-state.json keeps the time of the last read, the pause, the learnt certificate fingerprints, the stop commands still to send, and, for a refused token, an 8-bit tag (never the token).

Konfigurationseinstellungen​

Diese Einstellungen fragt Heatmiser neoHub in seinem Konfigurationsbildschirm in Gladys ab.

EinstellungTypPflichtfeldBeschreibung
Your Heatmiser neoHubsectionNeinBrings the thermostat zones of your Heatmiser neoHub into Gladys, on your local network, through the official local API of the hub (secure WebSocket, port 4243): the temperature, the setpoint and the mode (schedule or standby) of each zone, and the away mode of the hub. Create an API token in the Heatmiser Neo app (Settings > API Access > Tokens), type it below with the address of the hub, save, then click "Test the connection" once, from your home network: it learns the fingerprint of the certificate of the hub (learnt, not verified: the guide tells how to compare it). Standby and away need no option; setpoints and the return to the schedule stay off until allowed below. Never tested with a real device yet. Unofficial, not affiliated with Heatmiser.
Address of the neoHubstringJaThe local IP address of your neoHub, like 192.168.1.40 (shown in your router). Port 4243 unless you add ":port".
API token of the hubsecretJaCreated in the Heatmiser Neo app: Settings > API Access > Tokens. Kept by Gladys in its database, never shown again, and sent only to the hub at the address above, over its learnt certificate.
Certificate fingerprint (optional)stringNeinThe SHA-256 fingerprint of the certificate of the hub (the hub makes its own certificate). Empty: learnt on your first click of "Test the connection" (learnt, not verified: do it from your home network and compare it as the guide shows), then checked on every connection; the token never goes to another certificate. If the hub is replaced or reset, type here the fingerprint the status shows.
Heating commands (off by default)sectionNeinStandby of a zone (frost protection) and the away mode of the hub need no option: standby only lowers the heating of its zone; away puts every thermostat in standby and turns the time clocks and neoPlugs off. Without the option below, Gladys sends nothing else. Setpoints, Schedule and Home are decided on a fresh read of the hub. No command goes through a switch: a "turn everything off" never reaches the heating.
Allow heating commandsbooleanNeinThe dashboard, the scenes and the voice assistants may change the setpoint of a zone, put a zone back on its schedule and leave the away mode.
Setpoint ceiling (°C)numberNeinA setpoint above this value is refused (16 to 35 °C).
Refresh interval (s)numberNeinSeconds between two reads of the hub (30 to 600). The hub refreshes its own data about every 90 s.
Language of the namesselectNeinUsed for the names of the devices, features and options added from now on.

So installierst du Heatmiser neoHub in Gladys​

  1. Öffne in Gladys Integrationen: Heatmiser neoHub erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
  2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/lm1lc3n7/gladys-heatmiser-neohub:0.1.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
  3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
  4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/LM1LC3N7/gladys-heatmiser-neohub.

Heatmiser neoHub benötigt Gladys >=5.3.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.

Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.

Über externe Integrationen​

Heatmiser neoHub ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von LM1LC3N7 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂