Zum Hauptinhalt springen

Philips Air Smart-Home-Integration, kostenlos und Open Source

Philips Air-Integration für Gladys Assistant

Philips-Luftreiniger und Luftbefeuchter im lokalen Netz: Luftqualität, Modi, Filter.

Auf GitHub ansehenAlle Integrationen

Steuere deine vernetzten Philips-Luftreiniger und Luftbefeuchter aus Gladys, in deinem lokalen Netz, ohne die Philips-Cloud: Luftqualität (PM2.5, Allergenindex, Luftfeuchtigkeit), Modi und Lüfterstufe, Zielluftfeuchtigkeit, Kindersicherung, Displaybeleuchtung und die Reststunden jedes Filters. Änderungen am Luftreiniger oder in der Philips-App erscheinen in Gladys innerhalb weniger Sekunden.

Ohne die Hardware entwickelt: Rückmeldungen willkommen („Developed without the hardware: feedback welcome“). Diese Integration wurde nach dem von der Open-Source-Community dokumentierten Protokoll geschrieben und gegen einen simulierten Luftreiniger getestet. Wenn sich dein Modell anders verhält, öffne ein Issue unter https://github.com/guim31/gladys-philips-air/issues mit der Ausgabe des Prüfskripts (siehe Fehlerbehebung).

Keine Verbindung zu Philips oder Versuni. Philips ist eine Marke der Koninklijke Philips N.V.

Voraussetzungen​

  • Gladys Assistant 5.1 oder neuer.
  • Ein Philips-Luftreiniger oder -Luftbefeuchter mit WLAN, der das lokale CoAP-Protokoll spricht (UDP-Port 5683): die AC-Serie (AC2889, AC2729, AC3829, AC3858, AC4236, Series 2000i und 3000i…), die neueren AC0850, AC0950, AC2220, AC3220, AC3420, AC4220 und die HU-Luftbefeuchter (HU1509, HU4209, HU5710…). Die vollständige Liste steht unter „Unterstützte Modelle“.
  • Der Luftreiniger einmal in der App Philips Air+ eingerichtet (dort verbindet er sich mit deinem WLAN), im selben lokalen Netz wie Gladys.
  • Seine IP-Adresse. Dein Router zeigt sie an (das Gerät erscheint oft als MXCHIP…). Gib ihm im Router eine feste Adresse (DHCP-Reservierung): Die Integration sucht den Luftreiniger unter der eingegebenen Adresse.

Konfiguration​

Öffne in Gladys Integrationen → Philips Air → Konfiguration:

FeldWozu
IP-Adressen der LuftreinigerEine oder mehrere IPv4-Adressen, durch Kommas getrennt.
AktualisierungsintervallWie oft jeder Luftreiniger gelesen wird (10 s bis 2 min, standardmäßig 30 s). Änderungen schickt der Luftreiniger meist sofort; diese Abfrage ist das Sicherheitsnetz.
Warnung zum FilterwechselWann der Wartungsauslöser für einen zu wechselnden Filter auslöst: wenn der Luftreiniger es verlangt (Standard), oder 1 Tag, 3 Tage, 1 Woche vorher. Der Vorfilter wird immer gemeldet, wenn der Luftreiniger es verlangt.
Sprache der GerätenamenSprache der Namen neuer Geräte, ihrer Funktionen, der Modusliste und der Meldungen des Auslösers. Standardmäßig Französisch.

Speichere und öffne dann den Reiter Erkennung: ein Gerät pro Luftreiniger, benannt nach seinem Namen in der Philips-App und seinem Modell, zum Beispiel Schlafzimmer (AC2729/10). Füge es zu Gladys hinzu.

Die Taste Luftreiniger prüfen (Konfigurationsseite) liest alle Adressen auf einmal und zeigt, welche Luftreiniger antworten und welches Modell nicht in der Liste der Integration steht.

Das Gerät​

Jeder Luftreiniger bekommt nur die Funktionen seines Modells:

FunktionIn Gladys
Ein/AusSchalter.
ModusListe der Modi des Modells (siehe unten).
LüfterstufeManuelle Stufe, 1 bis 2, 3 oder 5 je nach Modell. Damit gilt „Manuell“.
PM2.5Feinstaub, in µg/m³.
AllergenindexPhilips-Index für Allergene in Innenräumen, von 1 (gut) bis 12 (sehr schlecht).
LuftfeuchtigkeitRelative Luftfeuchtigkeit, in % (Modelle mit Feuchtesensor).
TemperaturIn °C (Modelle mit Temperatursensor).
ZielluftfeuchtigkeitListe der Sollwerte, die der Luftbefeuchter annimmt (40 bis 70 % oder 30 bis 70 %).
BefeuchtungSchaltet den Befeuchterteil eines 2-in-1-Luftreinigers ein oder aus.
Wassertank„Niedrig“, wenn der Tank leer oder entnommen ist, sonst „Normal“.
KindersicherungSperrt die Tasten des Luftreinigers.
DisplaybeleuchtungHelligkeit des Displays und des Luftqualitätsrings.
Vorfilter (Reststunden)Stunden bis zur nächsten Reinigung des Vorfilters.
HEPA-Filter (Reststunden)Stunden bis zum Wechsel des HEPA-Filters (oder NanoProtect).
Aktivkohlefilter (Reststunden)Stunden bis zum Wechsel des Aktivkohlefilters.
Docht (Reststunden)Stunden bis zum Wechsel des Befeuchterdochts.

Modi​

Je nach Modell: Automatik, Allergene, Bakterien und Viren, Verschmutzung, Sanft, Mittel, Hoch, Schlafmodus, Allergie-Schlafmodus, Turbo und Manuell (eine feste Lüfterstufe). Ein Modus schaltet den Luftreiniger auch ein. Ein Modell, das nicht in der Liste der Integration steht, bekommt seine Sensoren, seinen Schalter und seine Filter, aber keine Modusliste.

Dashboard-Widget​

Das Widget Philips-Luftreiniger zeigt für den in seinen Einstellungen gewählten Luftreiniger:

  • PM2.5 und Luftfeuchtigkeit, live;
  • den Modus, den Allergenindex auf der Philips-Skala (Gut, Mäßig, Schlecht, Sehr schlecht), den laufenden Boost und sein Ende, und was der Luftreiniger verlangt (oder den Filter, der am nächsten an seinem Ende ist);
  • Tasten: zwei übliche Modi (Automatik oder Verschmutzung, Schlafmodus), Boost für 15, 30 oder 60 Minuten (Widget-Einstellung) und Ein/Aus.

Szenen-Auslöser​

Wartung des Luftreinigers nötig löst einmal aus, wenn ein Luftreiniger Pflege verlangt, und erst wieder, nachdem sie erledigt ist (Filter gewechselt, Tank gefüllt):

  • Vorfilter reinigen (wenn der Luftreiniger es verlangt);
  • HEPA-Filter wechseln, Aktivkohlefilter wechseln, Docht wechseln (wenn der Luftreiniger es verlangt, oder früher: siehe die Einstellung „Warnung zum Filterwechsel“);
  • Wassertank leer (beim Befeuchten).

Filter: der Luftreiniger und die Elemente, die dich interessieren. Variablen: item, hours_left und message, ein fertiger Text wie „Schlafzimmer (AC2729/10): HEPA-Filter wechseln (noch 70 h)“ in der Sprache der Konfiguration.

Szenen-Aktion​

Luftreiniger boosten lässt den Luftreiniger 5 bis 240 Minuten im Turbo (oder auf der höchsten Stufe) laufen und stellt ihn dann auf den vorherigen Modus zurück, oder schaltet ihn aus, wenn er aus war. Ändert jemand den Luftreiniger während des Boosts, endet der Boost, ohne ihn anzufassen. Die Aktion gibt until zurück, das Ende des Boosts.

Beispielszenen​

  • Nach dem Kochen: Steigt PM2.5 in der Küche über 35 µg/m³, Luftreiniger boosten für 20 Minuten.
  • Filter-Erinnerung: Bei Wartung des Luftreinigers nötig {{triggerEvent.data.message}} an dein Handy schicken.
  • Nacht: Um 22:30 Uhr Modus Schlafmodus und Displaybeleuchtung aus für den Luftreiniger im Schlafzimmer; um 7 Uhr zurück auf Automatik.
  • Abwesenheit: Ist das Haus leer, Luftreiniger auf Automatik; kommt die erste Person heim, Luftreiniger boosten für 15 Minuten.

Fehlerbehebung​

  • „Kein Philips-Luftreiniger antwortet“: Prüfe die IP-Adresse (sie kann sich geändert haben: lege sie fest), ob der Luftreiniger eingesteckt und im WLAN ist und ob er in der Philips-App antwortet. Eine strenge Firewall auf dem Gladys-Rechner (ufw…) kann den UDP-Verkehr zwischen dem Container der Integration und deinem Netz blockieren.
  • Es lief, dann keine Antwort mehr: Die Firmware dieser Luftreiniger hört bekanntlich nach einer Weile auf, lokal zu antworten (auch mit Home Assistant beobachtet). Zieh den Stecker für 10 Sekunden; die Integration verbindet sich von selbst neu.
  • Ein Modell ohne Modusliste: Dein Modell ist noch nicht in der Liste. Starte das Prüfskript auf einem Rechner im selben Netz, node scripts/probe.mjs <IP-Adresse> (in einem Klon des Repositorys, Node.js 22+): Es liest nur und maskiert die Kennungen. Füge seine Ausgabe in ein Issue ein.
  • Mehr Details: Die Protokolle der Integration (Gladys → Integrationen → Philips Air → Protokolle) zeigen auf der normalen Stufe nur das Leben der Luftreiniger; LOG_LEVEL=debug am Container zeigt jede Abfrage.

Grenzen​

  • Nur lokale Steuerung (CoAP über UDP 5683). Ältere Modelle, die nur HTTP sprechen, und die neueste Firmware, die den lokalen Zugang geschlossen hat, werden nicht unterstützt.
  • Keine automatische Erkennung: Die Luftreiniger kündigen sich nicht so an, dass der Gladys-Container es sehen kann. Gib ihre IP-Adresse ein.
  • Die Moduslisten stammen aus Beobachtungen der Open-Source-Community: Ein Modell kann einen Modus annehmen, der in seiner Liste fehlt, oder umgekehrt. Timer, Piepton, Ambientelicht und der „bevorzugte Index“ einiger Modelle werden nicht angeboten.
  • Die gepushten Änderungen laufen durch das Docker-Netz von Gladys; kommen sie nicht durch, bringt sie die nächste Abfrage (standardmäßig 30 s).
  • Ein laufender Boost übersteht einen Neustart der Integration, endet aber bei der nächsten Antwort, wenn der Luftreiniger zur geplanten Zeit nicht erreichbar war.

Unterstützte Modelle​

  • AC-Serie, klassische Firmware: AC2729, AC2889, AC2936, AC2939, AC2958, AC2959, AC3021, AC3033, AC3036, AC3039, AC3055, AC3059, AC3259, AC3829, AC3854/50, AC3854/51, AC3858/50, AC3858/51, AC3858/83, AC3858/86, AC4231, AC4236, AC5659, AC5660.
  • AC1715 und AC0850 (Firmware „AWS_Philips_AIR“).
  • Neue Generation: AC0850 (Firmware „AWS_Philips_AIR_Combo“), AC0950, AC0951, AC2210, AC2220, AC2221, AC3210, AC3220, AC3221, AC3420, AC3421, AC4220, AC4221.
  • Luftbefeuchter: HU1509, HU1510, HU4209, HU4210, HU5710.

Andere Modelle dieser Generationen bekommen ihre Sensoren, ihren Schalter und ihre Filter.

Support und Dank​

Issues und Rückmeldungen: https://github.com/guim31/gladys-philips-air/issues

Das Protokoll wurde von Radoslav Gerganov (py-air-control) entschlüsselt und von betaboon und kongo09 umgesetzt (aioairctrl, philips-airpurifier-coap für Home Assistant); diese Integration verdankt ihnen alles. Keine Verbindung zu Philips oder Versuni.

Konfigurationseinstellungen​

Diese Einstellungen fragt Philips Air in seinem Konfigurationsbildschirm in Gladys ab.

EinstellungTypPflichtfeldBeschreibung
Luftreiniger verbindensectionNeinGladys spricht mit den Philips-Luftreinigern in deinem lokalen Netz, ohne die Philips-Cloud. Richte den Luftreiniger zuerst in der App Philips Air+ ein und gib dann unten seine IP-Adresse ein (am besten eine feste Adresse im Router). Keine Verbindung zu Philips oder Versuni.
IP-Adressen der LuftreinigerstringNeinDurch Kommas getrennt. Dein Router zeigt sie an (das Gerät heißt oft „MXCHIP“).
AktualisierungsintervallselectNeinWie oft jeder Luftreiniger gelesen wird. Änderungen kommen meist sofort an; diese Abfrage ist das Sicherheitsnetz.
Warnung zum FilterwechselselectNeinWann der Auslöser „Wartung nötig“ für einen zu wechselnden Filter auslöst (HEPA, Aktivkohle, Docht). Der Vorfilter wird gemeldet, wenn der Luftreiniger es verlangt.
Sprache der GerätenamenselectNeinNamen für neue Geräte, ihre Funktionen, die Modusliste und die Meldungen des Auslösers.

So installierst du Philips Air in Gladys​

  1. Öffne in Gladys Integrationen: Philips Air erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
  2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/guim31/gladys-philips-air:1.0.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/guim31/gladys-philips-air.

Philips Air benötigt Gladys >=5.1.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​

Philips Air 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 guim31 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 🙂
Zuletzt aktualisiert am