HeishaMon (direkt seriell / RS232)

Der ioBroker-Adapter ermöglicht die direkte Kommunikation über das Panasonic Aquarea CN-CNT -Protokoll über eine serielle Schnittstelle, ohne HeishaMon-Modul oder MQTT-Broker. Der CN-CNT-Anschluss der Wärmepumpe verwendet 5-V-TTL-UART-Logikpegel . Für den Anschluss an eine 3,3-V-UART-Schnittstelle, wie z. B. die GPIO-UART-Schnittstelle des Raspberry Pi, ist ein geeigneter Pegelwandler erforderlich. Bei längeren Kabelstrecken kann optional ein TTL/RS485-Konverter eingesetzt werden, da das Protokoll Halbduplex ist. Die Protokolldekodierung basiert auf Erkenntnissen des HeishaMon-Projekts .

Status: Vorabversion. Protokollbibliothek, Simulator und Adapterlogik befinden sich in der Entwicklung; Feldtests an einer realen Wärmepumpe sind der nächste Schritt.

Unterstützte Wärmepumpen

Panasonic Aquarea Luft-Wasser-Wärmepumpen der Serien H, J, K und L.

Installation

Installieren Sie ioBroker über die Admin-Oberfläche aus dem offiziellen Repository: Öffnen Sie den Tab „Adapter“ , suchen Sie nach „heishamon“ und klicken Sie auf „Installieren“. Fügen Sie anschließend unter „Instanzen“ eine Instanz hinzu.

Voraussetzungen für die serielle Schnittstelle

Dies sind Schritte auf Hostseite, die die Administratoroberfläche nicht für Sie ausführen kann:

• Der ioBroker-Prozessbenutzer (iobroker (bei einer Standard-Linux-Installation) muss der Zugriff auf serielle Geräte erlaubt sein. Unter Debian/Raspberry Pi OS bedeutet das, dassdialout Gruppe:

  groups iobroker                     # must contain 'dialout'
  sudo usermod -aG dialout iobroker   # if not — then restart the whole ioBroker service
  

• Verwenden Sie einen stabilen Gerätepfad, damit der Port Neustarts und erneutes Anschließen übersteht./dev/serial/by-id/... über/dev/ttyUSB0 :

  ls -l /dev/serial/by-id/
  

  Bei einem Raspberry Pi GPIO UART ist der Pfad ohnehin statisch (z. B./dev/ttyAMA2 ).

Informationen zur Verdrahtung der Wärmepumpe finden Sie im Abschnitt „ Verdrahtung “ weiter unten.

Konfiguration

Merkmale

• Direkte serielle Kommunikation mit Panasonic Aquarea Wärmepumpen über den CN-CNT-Anschluss. Weder HeishaMon-Hardware noch ein MQTT-Broker sind erforderlich.
• 157 Datenpunkte, die als ioBroker-Zustände mit den entsprechenden Rollen, Typen und Einheiten bereitgestellt werden.
• Befehle für alle vom CN-CNT-Protokoll unterstützten beschreibbaren Parameter festlegen .
• Nur-Lese-Modus für sicheren Parallelbetrieb neben einer bestehenden HeishaMon-Installation (Phase-4-Umstellung).
• Verbindungsqualitätsstatistiken (eingehende/ausgehende Frames, CRC-Fehler, Timeouts) unter derinfo.* Kanal.
• Optionaler zusätzlicher Datenblock für Wärmepumpen der K/L-Serie (6 zusätzliche Energiedatenpunkte).

⚠️ Überlegungen zum Schreibsatz

Der interne Speichermechanismus des Panasonic Aquarea-Controllers für Einstellungen ist nicht dokumentiert. Bei normaler Nutzung – manuelle Änderungen, gelegentliche Smart-Home-Automatisierung – ist Verschleiß sehr unwahrscheinlich; die HeishaMon-Community verfügt über jahrelange Betriebserfahrung ohne gemeldete Ausfälle. Allerdings könnten häufige Schreibvorgänge (z. B. ein PID-Regler, der alle paar Sekunden einen Sollwert anpasst) theoretisch eine EEPROM-Zelle mit der Zeit erschöpfen, wenn der Controller nicht FRAM, MRAM oder ein RAM-Design mit automatischer Speicherbereinigung bei Stromausfall verwendet.

Schreiben Sie denselben Datenpunkt nicht häufiger als alle paar Minuten, es sei denn, Sie wissen genau, dass Ihre Reglerversion dies zulässt. Bei Regelungsvorgängen im geschlossenen Regelkreis ist ein langsamer äußerer Regelkreis, der die internen Regler der Wärmepumpe steuert, vorzuziehen, anstatt den Aktor direkt anzusteuern.

Was Sie benötigen

Kein HeishaMon-Gerät, kein ESP, kein MQTT-Broker erforderlich. Dieser Adapter kommuniziert direkt mit dem Panasonic CN-CNT-Protokoll. Sie müssen lediglich eine serielle Verbindung zwischen der Wärmepumpe und dem Rechner, auf dem ioBroker läuft (PC, Heimserver, NAS, Raspberry Pi usw.), herstellen.

Schwierigkeitsgrad – bitte zuerst lesen. Die Einrichtung erfordert das Öffnen der Elektronikabdeckung der Wärmepumpe und das Verbinden zweier Datenleitungen sowie der Erdung mit einem internen Stecker. Sie sollten mit dünnen Kabeln und grundlegenden Elektronikkenntnissen (Logikpegel, Masseschleifen, RS485) vertraut sein. Es handelt sich um Niederspannung (5-V-Signalisierung), nicht um Netzspannung – dennoch können ein falscher Stecker oder eine verpolte Verkabelung die Wärmepumpe beeinträchtigen. Wenn Ihnen diese Beschreibung unsicher macht, ist dies kein geeignetes erstes Elektronikprojekt.

⚠️ Betrieb auf eigene Gefahr und Haftung – keine Gewährleistung. Das Öffnen des Geräts kann zum Erlöschen der Herstellergarantie führen. Wärmepumpe vor dem Anschließen ausschalten. Zweimal messen, einmal anschließen.

Das Signal und der Baustein

Im Kern handelt es sich lediglich um eine serielle Verbindung zwischen dem ioBroker-Host und der Wärmepumpe – nichts Komplizierteres. Die Frage ist nur, wie diese Verbindung physisch realisiert werden kann.

Die Wärmepumpe verwendet an ihrem Anschluss eine einfache 5-V-TTL-UART- Schnittstelle. Am einfachsten lässt sich die Verbindung mit einem 5-V-USB-zu-TTL-UART-Adapter herstellen: Nur drei Drähte – GND ↔ GND und die beiden gekreuzten Datenleitungen (Wärmepumpe TX → Adapter RX, Wärmepumpe RX → Adapter TX) – +5 V / +12 V bleiben unverbunden. Ein vorverdrahteterPHR-4 Durch die Verwendung eines Pigtails in CN-NMODE wird dies oft lötfrei.

Galvanische Trennung ist optional – aber seien Sie sich der Risiken bewusst. Die RX/TX-Pins der Wärmepumpe können direkt mit dem Mikrocontroller verbunden sein, oft ohne oder mit nur geringem Schutz dazwischen. Überspannung oder -strom auf diesen Leitungen – beispielsweise durch eine Masseschleife, einen Kurzschluss oder wenn ein +12-V-Pin versehentlich eine Signalleitung berührt – können den Mikrocontroller zerstören und die Hauptplatine der Wärmepumpe unbrauchbar machen . Wenn Sie sich bezüglich der Masseschleife zwischen Wärmepumpe und Host unsicher sind, kann ein günstiger USB-Isolator auf der USB-Seite diesen Pfad unterbrechen. Alternativ können Sie die Leitungen auch auf andere Weise schützen (z. B. mit Vorwiderständen oder PTC-Sicherungen). Viele Installationen funktionieren problemlos ohne Trennung, aber diese Entscheidung treffen Sie bewusst.

Dieser einfache Adapter ist nur dann ausreichend, wenn der ioBroker-Host tatsächlich neben der Wärmepumpe steht – zum Beispiel bei einem Testlauf auf einem Prüfstand oder einem kleinen SBC, der direkt an dem Gerät montiert ist.

Empfohlene Konfiguration – 2-Draht-RS485 über Distanz

In der Praxis befindet sich der ioBroker-Host in einem anderen Raum oder auf einer anderen Etage, nicht 2 m von der Wärmepumpe entfernt. Die sinnvolle Verbindung in der Praxis ist daher RS485 über ein geschirmtes verdrilltes Adernpaar , was auch dem Halbduplex-Charakter des Protokolls entspricht:

heat pump (5 V TTL, CN-NMODE)
   └─ TTL↔RS485 converter        ← near the heat pump
        └─ shielded twisted pair, 120 Ω termination at BOTH ends, mind A/B
             └─ RS485↔USB adapter ← at the ioBroker host
                  └─ USB → ioBroker host  →  /dev/serial/by-id/…

Sie bauen die gleiche TTL-Frontend-Schaltung wie oben beschrieben auf, aber anstatt die gesamte Strecke über USB zu verlegen, wandeln Sie das Signal direkt an der Wärmepumpe in RS485 um und verbinden es mit dem Host über zwei Drähte. Die kleinen TTL↔RS485- Konverterplatinen kosten nur wenige Euro bei den üblichen Online-Händlern und verfügen in der Regel bereits über einen grundlegenden Leitungsschutz (TVS-Dioden/Vorwiderstände) – eine willkommene zusätzliche Sicherheitsreserve auf der Seite der Wärmepumpe. Die galvanische Trennung ist optional und lässt sich, falls verwendet, am einfachsten auf der USB-Seite des Hosts realisieren.

Egal welchen Weg Sie wählen, der Adapter sieht immer nur einen lokalen seriellen Gerätepfad – fahren Sie mit der Konfiguration fort.

Andere Varianten (fortgeschritten)

Verdrahtung

⚠️ Zweimal messen, einmal anschließen. Alle hier angebotenen Produkte werden ohne jegliche Gewährleistung bereitgestellt und die Nutzung erfolgt ausschließlich auf eigene Gefahr und Haftung.

☠️ Eine falsche Verbindung kann die Wärmepumpe zerstören. Die RX/TX-Pins CN-CNT/CN-NMODE sind möglicherweise direkt mit dem Mikrocontroller der Wärmepumpe verbunden, ohne oder mit nur geringem Schutz dazwischen. Beachten Sie die +5-V- und +12-V-Pins direkt neben den Signalleitungen in den folgenden Tabellen: Eine Berührung eines Signalpins mit +12 V, eine Verpolung oder ein Masse-/Ausgleichsstromstoß können den Mikrocontroller zerstören und die Hauptplatine unbrauchbar machen. Überprüfen Sie daher alle Pins sorgfältig, bevor Sie das Gerät einschalten.

Die Hauptplatine der Wärmepumpe verfügt über zwei gleichwertige Anschlüsse, die dieser Adapter nutzen kann: CN-CNT und CN-NMODE . Beide funktionieren – wählen Sie den, der leichter zugänglich ist.

CN-CNT ist der Anschluss, der normalerweise für das CZ-TAW1-Cloud-Modul oder die optionale Leiterplatte verwendet wird:

• Wenn ein CZ-TAW1- Modul angeschlossen ist, betreiben Sie diesen Adapter im Nur-Lese-Modus , damit er nur zuhört und den Bus niemals ansteuert.
• Mit der optionalen Leiterplatte sind zwei Busmaster vorhanden, wodurch Kollisionen auftreten können – die Funktion sollte aber in der Regel dennoch gegeben sein. Nach einem CRC-Fehler wartet der Adapter eine zufällige Zeit, bevor er erneut auf den Bus zugreift, um die Kollisionssynchronisation aufzuheben (siehe die Hinweise zum reaktionsgesteuerten Bus im Änderungsprotokoll).

Beide Anschlüsse übertragen ein 5V-TTL-UART- Signal, daher ist für 3,3V-Geräte wie den Raspberry Pi GPIO ein Pegelwandler erforderlich. Die unten aufgeführten Signalbezeichnungen beziehen sich auf die Wärmepumpe – sie müssen am Adapterende gekreuzt werden (Wärmepumpe TX → Adapter RX, Wärmepumpe RX → Adapter TX).

CN-CNT — JSTB05B-XASK-1 (Gegenstecker)PAP-05V-S )

CN-NMODE — JST PH-Serie (Gegenstecker)PHR-4 (vorverdrahtet bei den üblichen großen Online-Händlern erhältlich)

Beispiel – ein UART-zu-RS485-Konverter, der mit demCN-NMODE Anschluss (das Wärmepumpenende der RS485-Fernverbindungsvariante):

Fehlerbehebung

• EACCESauf dem seriellen Gerät – der ioBroker-Prozessbenutzer ist nicht imdialout Gruppe. Nachsudo usermod -aG dialout iobroker , den gesamten ioBroker-Dienst neu starten (sudo systemctl restart iobroker ), nicht nur die Instanz – die Gruppenzugehörigkeit wird erst in einer neuen Sitzung wirksam.
• Der Adapter startet, aber es werden keine Datenpunkte angezeigt – überprüfen Sie die Verdrahtung am CN-CNT-Anschluss (TX↔RX kreuzen, GND anschließen, 5-V-TTL-Pegel beachten, siehe Verdrahtung ). Bei einem TTL↔RS485-Konverter überprüfen Sie zusätzlich die Polarität A/B und die Abschlusswiderstände. Eine intakte Verbindung liefert ca. 157 Datenpunkte.heishamon.0.main.* innerhalb weniger Sekunden und setztheishamon.0.info.connection Zutrue Die
• Die Befehle haben keine Wirkung .readOnlyMode Dies ist eine bewusst gewählte Sicherheitsvorgabe für den ersten Start. Deaktivieren Sie sie erst, wenn der Lesevorgang fehlerfrei läuft.
• Anschluss über den CZ-TAW1-Bus – Adapter angeschlossen lassenreadOnlyMode Andernfalls kommt es zu Buskollisionen mit dem Panasonic Cloud-Modul.

Dokumentation

Die Projektdokumentation befindet sich unter docs/ :

• docs/plan/ — Phasenplan und Roadmap.
• docs/protocol/ — CN-CNT-Protokollanalyse.
• docs/decisions/ — Architekturentscheidungsdatensätze.

Gutschriften und Upstream-Lizenzierung

Die Protokolldekodierung baut auf den Arbeiten der HeishaMon-Community auf. Die CN-CNT-Registerzuordnung und viele Implementierungshinweise stammen von dort.

Zum Zeitpunkt der Erstellung dieses Dokuments enthält das HeishaMon-Repository keine explizite Lizenzdatei – keineLICENSE Kein Header in den Quelltexten, keine eindeutige Angabe in der README-Datei. Nach US-amerikanischem und EU-Urheberrecht gilt standardmäßig „Alle Rechte vorbehalten“, daher dürfen wir den Originalcode weder kopieren noch direkt portieren. Um die Einhaltung der Regeln zu gewährleisten:

• Die HeishaMon C++-Quelltexte dienen lediglich als Referenz zum Verständnis des Panasonic CN-CNT-Protokolls.
• Dieser Adapter ist eine Neuimplementierung in TypeScript : Wir haben die Upstream-Quellen gelesen, das Protokoll in docs/protocol/ destilliert und es anhand dieser Dokumentation implementiert – nicht anhand des Originalcodes.
• Die Protokolldokumentationsdateien des HeishaMon-Repositorys (MQTT-Topics.md ,OptionalPCB.md ,ProtocolByteDecrypt.md ) beschreiben ein beobachtbares physikalisches Protokoll – das sind Fakten und unterliegen nicht dem Urheberrecht; sie werden gegebenenfalls als Quellen angegeben.

Das CN-CNT-Protokoll selbst wird von Panasonic nicht veröffentlicht; HeishaMons Entdeckung beruht auf empirischen Beobachtungen. Fakten sind nicht urheberrechtlich geschützt, die konkrete C++-Implementierung dieser Entdeckungen jedoch schon.

Changelog

0.0.14 (2026-06-29)

• (Tobias Hanss) Corrected the maintainer email address in the package metadata (package.json, io-package.json)
• (Tobias Hanss) extraPollEnabled now defaults to off (opt-in) — the K/L-series extra data block is only polled when explicitly enabled, so a fresh install never polls datapoints that H/J pumps cannot provide. Existing instances keep their current setting
• (Tobias Hanss) Documentation: reworked the hardware/wiring section — clarified that only a plain serial link is needed (no HeishaMon device), made 2-wire RS485 the recommended real-world path, added a Raspberry Pi GPIO UART step-by-step, and a dead-mainboard warning at the wiring pinouts

0.0.13 (2026-06-28)

• (Tobias Hanss) Release now uses npm trusted publishing (provenance via OIDC) on Node 24 — fixes repository-checker E2008/E3019/E3022
• (Tobias Hanss) Removed the redundant mocha dev-dependency (it ships with @iobroker/testing) — E0063; the CI adapter-tests job now declares needs: check-and-lint — E3014
• (Tobias Hanss) Lint-config cleanup: dropped .prettierignore in favour of // prettier-ignore markers on the datapoint tables — W0084/W5048. No functional change

0.0.12 (2026-06-28)

• (Tobias Hanss) Resilient startup: a failed serial open no longer terminates the adapter — it stays alive, sets info.connection=false and retries
• (Tobias Hanss) Polling reworked to a setTimeout-at-end-of-tick scheme so poll ticks can never overrun or pile up in the wire queue, even under sustained communication failure
• (Tobias Hanss) validateConfig() now validates and safely clamps the user-configurable timeouts/gaps (responseTimeoutMs, setCommandGapMs, sendMaxRetries) to the Node.js timer ceiling
• (Tobias Hanss) info channel name fully translated (all 11 languages); setup help texts clarified
• (Tobias Hanss) Documentation: folded the install notes into the README and removed the separate INSTALL.md
• (Tobias Hanss) Tooling: adopted the standard ioBroker test-and-release workflow (testing-action-check / -adapter / -deploy) and migrated to @iobroker/eslint-config. No change to the heat-pump protocol

0.0.11 (2026-06-21)

• (Tobias Hanss) Object state roles for writable datapoints are now level instead of value (the value role requires write=false), fixing the repository checker's object-structure errors (E1011)
• (Tobias Hanss) State objects are now updated on upgrade (extendObject) so existing installations pick up the corrected roles
• (Tobias Hanss) Added the recommended i18n translations for the info.connection state name (W1001)

0.0.10 (2026-06-21)

• (Tobias Hanss) Published from CI with npm provenance (signed build attestation). No change to the adapter itself

0.0.9 (2026-06-21)

• (Tobias Hanss) CI: the release workflow's npm-publish step is now idempotent — it skips publishing when the version is already on npm, so a manual publish no longer makes the tagged release run fail. No change to the adapter itself

0.0.8 (2026-06-20)

• (Tobias Hanss) Maintenance for ioBroker repository acceptance: adapter-managed timers for clean shutdown, Node.js >=22 required, CI runs the adapter tests on Linux, Windows and macOS. No functional change to the heat-pump communication

0.0.7 (2026-05-30)

• (Tobias Hanss) Response-driven half-duplex bus: every send now waits for the heat pump's reply (or a timeout) before the next frame goes out, and retries up to 3 times on timeout or CRC error
• (Tobias Hanss) After a CRC error a randomised backoff precedes the next bus access to avoid lock-step collisions with a second master (Option-PCB)
• (Tobias Hanss) New "Diagnostics" setting toggles the set-command response logging (off by default)

0.0.6 (2026-05-30)

• (Tobias Hanss) Diagnostic logging to reverse-engineer the heat pump's SET acknowledgement: logs the sent frame and the heat pump's reply (frame type, timing, hexdump) at info level

0.0.5 (2026-05-30)

• (Tobias Hanss) Wire-queue gap is now enforced between every pair of sends, including across idle periods (previously the gap only applied while multiple tasks were already stacked in the queue — so polls and isolated sets bypassed it entirely)
• (Tobias Hanss) Queue is hard-capped at 100 pending entries; overflows are logged at warn level and the dropped send is skipped instead of silently piling up

0.0.3 (2026-05-26)

• (Tobias Hanss) Serialize all wire writes through a FIFO queue with a configurable inter-frame gap (default 200 ms). Fixes lost set commands when a script writes several datapoints at once
• (Tobias Hanss) Pump_Duty / Max_Pump_Duty unit removed (raw value 65-254, no physical unit)

0.0.2 (2026-05-25)

• (Tobias Hanss) Lower Node.js engine requirement to >= 20 (was 22) so the adapter installs on current ioBroker LTS hosts

0.0.1 (2026-05-25)

• (Tobias Hanss) Initial adapter release

License

MIT License

Copyright (c) 2026 Tobias Hanss t.dev@familie-hanss.de

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE DEALINGS IN THE SOFTWARE.