Pluggit AP310 in Home Assistant: Modbus direkt oder HACS-Integration?
Zwei lokale Wege zur AP310
Wer eine Pluggit AP310 im Haus stehen hat – ein Lüftungsgerät mit Wärmerückgewinnung – möchte sie früher oder später auch im Smart Home sehen: Filterstatus im Dashboard, Betriebsmodus per Automation umschalten, Temperaturen mitloggen. Home Assistant bietet dafür grundsätzlich zwei Wege. Der erste ist die native Modbus-Integration von Home Assistant, bei der man Register-Adressen von Hand in einer YAML-Konfiguration einträgt. Der zweite ist eine fertige Custom-Integration aus HACS, die diese Arbeit bereits erledigt hat und eine grafische Einrichtung über die Oberfläche anbietet. Beide Wege führen zum Ziel, unterscheiden sich aber deutlich in Aufwand, Robustheit und Pflegeaufwand. Dieser Artikel vergleicht beide Ansätze auf Basis der verfügbaren Dokumentation und Community-Erfahrungen.
Vorab eine Einschränkung zur Transparenz: Die AP310 wird im Pluggit-Sortiment mit dem UNI-3-Controller ausgeliefert, der über sein offizielles Modbus-TCP/IP-Protokoll angesprochen werden kann (Dokument „pluggit_uvc_controller_modbus_tcp_ip.pdf" von pluggit.com, referenziert im Home-Assistant-Community-Forum). Die häufig kolportierte Aussage, Pluggit- und Dantherm-Geräte würden sich denselben Controller teilen, stammt aus der README des HACS-Projekts Tvalley71/pluggit und ist dort selbst mit „appear to share" (scheinen zu teilen) formuliert. Es handelt sich also um eine Einschätzung des Integrations-Entwicklers, nicht um eine vom Hersteller bestätigte Tatsache – das lässt sich an dieser Stelle nicht als gesichert bestätigen.
Aufwand
Die native Modbus-Anbindung ist der Weg mit dem größten Einstiegsaufwand. Man benötigt die statische IP-Adresse des Geräts, muss die relevanten Modbus-Register selbst zusammentragen oder aus Community-Quellen übernehmen, und jede zusätzliche Größe – etwa Feuchtigkeit, VOC-Wert oder Filterresttage – ist eine weitere Zeile YAML mit Adresse, Datentyp und gegebenenfalls Byte-Reihenfolge. Im Home-Assistant-Forumsthread „Pluggit ventilation unit (modbus)" berichten mehrere Nutzer von typischen Stolpersteinen: falsch gelesene Werte durch die Byte-/Wortreihenfolge; Home Assistant verwendet dafür aktuell den Schlüssel swap, Anpassungsbedarf bei Datentyp-Bezeichnungen nach Home-Assistant-Versionswechseln (aus float/uint wurde float32/uint16) und vor allem Schreibzugriffe, die beim Urheber des Threads zunächst gar nicht funktionierten und erst über den Service modbus.write_register in eigenen Automationen nachgebaut werden mussten. Ein Nutzer fasst die Erfahrung dort sinngemäß mit „Modbus ist eine Zicke" zusammen – die Konfiguration ist machbar, aber fehleranfällig und pflegeintensiv.
Die HACS-Integration reduziert die manuelle Registerarbeit, dafür ist man von Qualität, Funktionsumfang und Pflege des jeweiligen Community-Projekts abhängig. Für die AP310 kommen aktuell im Wesentlichen zwei Projekte infrage, Tvalley71/pluggit und Goemon64/Pluggit-HA. Beide sind reine HACS-Integrationen ohne Cloud-Anbindung, die lokal per Modbus TCP/IP mit dem Gerät sprechen.
Schritt für Schritt
Für die native Modbus-Variante sieht der typische Weg laut Forumsdokumentation so aus: Zunächst wird in der configuration.yaml ein Modbus-Hub vom Typ TCP mit der Geräte-IP und Port 502 angelegt, inklusive eines Scan-Intervalls (in den Beispielen aus dem Forum meist 10 Sekunden). Anschließend werden Sensoren für die gewünschten Werte ergänzt, etwa Außenluft-, Zuluft-, Abluft- und Fortluft-Temperatur über die im Forum dokumentierten Register 133, 135, 137 und 139 (Datentyp float, zwei Register breit), der Bypass-Status über Register 198, die Lüfterstufe über Register 324 sowie die Ventilatordrehzahlen über die Register 101 und 103. Ergänzend haben Community-Mitglieder weitere Register zusammengetragen, etwa für Luftfeuchte (196), VOC-Wert (430), Betriebsmodus (472) und Filterresttage (555); eine gesammelte Übersicht pflegt der Nutzer gersilex in einem GitHub-Wiki. Wer auch schreiben möchte – etwa um den Betriebsmodus per Automation zu wechseln –, ergänzt eigene Skripte oder Buttons, die den Service modbus.write_register aufrufen, da der direkte Schreibzugriff über die Sensor-Konfiguration in den geschilderten Fällen nicht zuverlässig funktionierte. Nach jeder Änderung genügt je nach Änderung ein Neuladen über modbus.reload; andernfalls ist ein Neustart nötig, und bei Versionswechseln von Home Assistant lohnt ein Blick in die Modbus-Dokumentation, da sich Schlüsselbezeichnungen wie Datentypen in der Vergangenheit geändert haben.
Vor jeder HACS-Installation sollte ein Home-Assistant-Backup erstellt und auf ein anderes Gerät kopiert werden. Tvalley71/pluggit ist zum Prüfzeitpunkt über die HACS-Suche auffindbar; bei einem nicht gelisteten Projekt wird die dokumentierte Repository-URL als benutzerdefiniertes Repository ergänzt. Danach wird die Integration installiert, Home Assistant neu gestartet und Pluggit unter „Einstellungen → Geräte & Dienste" mit der reservierten Geräte-IP eingerichtet. Tvalley71/pluggit verlangt aktuell Home Assistant 2025.8.0 oder neuer und nennt AP190 sowie AP310 als bekannte unterstützte Geräte; das Projekt bringt danach eine große Zahl fertiger Entitäten mit, darunter Temperatur- und Feuchtesensoren, Schalter für Betriebsmodi wie Away, Boost, Eco, Home, Night, Sommer und Kamin, eine Auswahl für Lüfterstufe und Wochenprogramm sowie eine Cover-Entität für die Bypass-Klappe. Goemon64/Pluggit-HA deckt laut eigener Beschreibung zusätzlich die Modelle AP190 und AP460 ab und wurde nach Angaben des Projekts mit AP310 und Firmware 3.14 getestet.
Praxisbeispiel aus einem laufenden Setup
Wie das in der Praxis aussieht, zeigt ein reales, produktiv laufendes Setup mit AP310 und nativer Modbus-Anbindung. Der Modbus-Hub und die Sensoren stecken dort in einer eigenen Package-Datei, ausgelagert aus der configuration.yaml:
modbus:
- name: pluggitAP310
type: tcp
host: 192.168.X.X
port: 502
delay: 0
message_wait_milliseconds: 30
timeout: 5
sensors:
- name: Pluggit_Outdoor_T1
slave: 1
address: 133
unit_of_measurement: "°C"
data_type: float32
- name: Pluggit_Fan1_Speed
slave: 1
address: 101
unit_of_measurement: rpm
data_type: float32
Auffällig: Die Lüfterstufe wird hier zum Lesen über Register 323 abgefragt, das Umschalten der Stufe im Dashboard erfolgt aber über Register 324 – Lese- und Schreibadresse liegen also einen Registerplatz auseinander. Das deckt sich nicht exakt mit den im Forum kursierenden Angaben (dort wird für beides Register 324 genannt) und zeigt, dass sich Register-Listen aus dem Netz nicht blind übernehmen lassen, sondern am eigenen Gerät verifiziert werden müssen.
Das Dashboard dahinter ist eine custom:html-template-card, die per Jinja-Template direkt auf die Sensor-Zustände zugreift und den Luftstrom als Flow-Grafik mit Ein- und Austrittstemperaturen sowie Drehzahlen darstellt. Darunter sitzt eine custom:stack-in-card mit einer Buttonreihe, die den Betriebsmodus direkt per Service-Aufruf setzt, ganz ohne Umweg über ein Script:
- type: button
icon: mdi:fan-speed-2
name: "Fan 2"
show_state: true
tap_action:
action: call-service
service: modbus.write_register
service_data:
address: 324
unit: 255
value: [2, 0]
hub: pluggitAP310
Die „Stromversorgung"-Zeile darunter ist bewusst kein Modbus-Wert, sondern ein separater Smart-Plug-Schalter, der die Anlage stromseitig trennt – ein Beispiel dafür, dass ein Dashboard für ein Gerät durchaus mehrere Integrationen mischen kann. Diese Lösung bestätigt in der Praxis, was oben aus der Dokumentation zusammengetragen wurde: Der Aufwand steckt in der einmaligen Registerarbeit, danach lässt sich das Dashboard exakt auf eigene Bedürfnisse zuschneiden. Die HACS-Integration gibt zwar die verfügbaren Entitäten vor, beschränkt aber nicht die freie Gestaltung eigener Home-Assistant-Dashboards.
Alternativen
Wer nicht bei Home Assistant bleibt oder zusätzliche Systeme im Einsatz hat, findet auch dort fertige Bausteine: Für ioBroker existiert eine Modbus-Vorlage im ioBroker-Forum („[Vorlage] [ModBus] [Pluggit]"), für SmartHomeNG ein eigenes Pluggit-Plugin im offiziellen Plugin-Repository. Innerhalb von Home Assistant selbst bleibt neben den beiden genannten HACS-Projekten die von Grund auf selbst gepflegte YAML-Lösung eine gültige Alternative – etwa für Nutzer, die nur einzelne Messwerte auslesen wollen und auf den vollen Funktionsumfang einer fertigen Integration verzichten können, oder für Geräte, die von keiner der bestehenden Integrationen offiziell unterstützt werden. Einzelne Nutzer berichten zudem von Erfolgen mit weiteren, nicht offiziell zugesicherten Geräten wie Bosch Vent 5000 C oder Fränkische Profi-Air, die über dieselbe Controller-Basis laufen sollen – hierzu liegt jedoch keine Herstellerbestätigung vor, sondern nur Nutzerberichte aus der jeweiligen Projekt-Dokumentation.
Vorteile und Nachteile im Überblick
Die native Modbus-Konfiguration bietet volle Kontrolle: Man liest und schreibt genau die Register, die man braucht, ist an kein Drittprojekt gebunden und bleibt auch dann funktionsfähig, wenn ein HACS-Projekt eines Tages nicht mehr gepflegt wird. Der Preis dafür ist Handarbeit bei jeder Änderung, ein höheres Fehlerrisiko bei Datentyp und Byte-Reihenfolge und laut den Forumsberichten ein zusätzlicher Aufwand, sobald Schreibzugriffe benötigt werden.
Die HACS-Integration punktet mit schneller Einrichtung, einer strukturierten Entitäten-Übersicht, vorbereiteten Bedienelementen wie Boost- oder Away-Schaltern und einer im Fall von Tvalley71/pluggit sichtbar aktiven Weiterentwicklung. Der Nachteil ist die Abhängigkeit von einem Community-Projekt einzelner Maintainer, eine engere Kopplung an bestimmte Home-Assistant-Mindestversionen sowie eine gewisse Unsicherheit, wie vollständig einzelne Firmware-Stände oder Zusatzmodule (etwa das HAC-Modul, das laut Tvalley71-Projekt aktuell nur eingeschränkt getestet ist) unterstützt werden.
Kurz gegenübergestellt:
- Einrichtungsdauer: nativer Modbus hoch (Register manuell zusammentragen) / HACS gering (wenige Minuten)
- Kontrolle über Register und Entitäten: nativer Modbus vollständig / HACS durch das jeweilige Projekt vorgegeben
- Abhängigkeit von einem Drittprojekt: nativer Modbus keine / HACS ja, vom jeweiligen Maintainer
- Vorbereitete Bedienelemente: nativer Modbus nein, selbst gebaut / HACS ja, etwa Switches, Selects, Cover
- Fehlerrisiko bei der Konfiguration: nativer Modbus höher, wegen Datentyp und Byte-Reihenfolge / HACS geringer
- Weiterentwicklung und Pflege: nativer Modbus in eigener Verantwortung / HACS abhängig von der Aktivität des Projekts
Fazit
Für die meisten Nutzer dürfte die HACS-Integration der pragmatischere Einstieg sein: Sie liefert in kurzer Zeit ein vollständiges Set an Sensoren und Bedienelementen und erspart die Fehlersuche bei Registeradressen, die andere bereits durchlaufen haben. Wer dagegen sehr genau wissen möchte, was im Hintergrund passiert, nur wenige Werte braucht oder auf Nummer sicher gehen will, falls ein Community-Projekt irgendwann nicht mehr gepflegt wird, ist mit der nativen Modbus-Konfiguration und den im Forum dokumentierten Registern gut beraten. Für beide Wege existieren dokumentierte AP310-Anwendungen. Welche Variante im eigenen System funktioniert, hängt zusätzlich von Firmware, Zusatzmodulen und dem aktuellen Softwarestand ab.
Nachtrag: Kälteproblem am Lufteinlass
Im laufenden Betrieb hat sich bei diesem Gerät gezeigt, dass die AP310 mit sehr kalter Außenluft nicht gut zurechtkommt: Sobald die Außentemperatur auf etwa -2 bis -3 °C oder darunter fällt, macht der Lufteinlass Probleme. Das ist eine eigene Beobachtung an diesem konkreten Gerät, keine offiziell dokumentierte Herstellerangabe.
In der vorhandenen Installation wurde die Anlage versuchsweise zusätzlich über einen Zwischenstecker geschaltet. Daraus lässt sich keine allgemeine Empfehlung ableiten: Eine zentrale Lüftungsanlage besitzt eigene Frostschutz- und Nachlaufstrategien. Eine externe Netztrennung kann diese Schutzfunktionen umgehen, Fehlermeldungen erzeugen oder die notwendige Gebäudelüftung unterbrechen. Ursache und zulässige Gegenmaßnahme müssen deshalb mit Pluggit beziehungsweise einem qualifizierten Lüftungsfachbetrieb geklärt werden; die Herstellerunterlagen gehen vor.
Eine kurzzeitige Abschaltung wurde außerdem genutzt, wenn vorübergehend Gerüche von außen auftraten. Auch dabei sind Mindestlüftung, Feuchteschutz und die Herstellervorgaben zu beachten: In ländlicher Umgebung mit Feldern in unmittelbarer Nähe, die kurz vor Regen gegüllt werden, oder wenn der Nachbar grillt, lässt sich die Lüftung darüber ebenfalls kurzzeitig abschalten, sodass diese Gerüche gar nicht erst über den Lufteinlass ins Haus gelangen.
Ein Außentemperatursensor allein macht eine solche Abschaltautomation nicht sicher. Zulässige Grenzwerte, Mindestlüftung, Frostschutz und Wiederanlauf müssen aus Hersteller- beziehungsweise Fachplanung hervorgehen.
Quellen
- Tvalley71/pluggit (GitHub, HACS-Integration)
- Goemon64/Pluggit-HA (GitHub, HACS-Integration)
- Home Assistant Community Forum – Pluggit ventilation unit (modbus), Seite 1
- Home Assistant Community Forum – Pluggit ventilation unit (modbus), Seite 2
- gersilex/pluggit-avent-home-assistant Wiki (Register-Sammlung)
- Loxforum – Pluggit Avent P310 Modbus TCP/IP
- SmartHomeNG Pluggit-Plugin
- ioBroker-Forum: Vorlage ModBus Pluggit
- Eigene, produktiv laufende Home-Assistant-Konfiguration (nicht öffentlich prüfbar; persönliche Betriebserfahrung)
- Home Assistant: Modbus
- Home Assistant: HACS – Hinweise zu Community-Code