AirGradient Smart-Home-Integration, kostenlos und Open Source
AirGradient-Luftqualitätsmessgeräte im lokalen Netzwerk: CO₂, PM2,5, VOC, Temperatur, Feuchte.
Veröffentlicht von guim31
- Geräte
- Version 1.0.1
- Erfordert Gladys >=5.1.0
- ★ 0
Diese Integration bringt die Luftqualitätsmessgeräte von AirGradient in Gladys: den AirGradient ONE (innen), den Open Air (außen), die DIY-Kits und den AirGradient Go. Die Integration liest die Geräte in deinem lokalen Netzwerk über die lokale API ihrer Firmware: kein Konto, keine Cloud, kein API-Schlüssel.
Ohne die Hardware entwickelt: Rückmeldungen sind willkommen. Die Integration wurde anhand des Quellcodes der AirGradient-Firmware, der Dokumentation ihrer lokalen API und der echten Antworten geschrieben, die mit der Python-Bibliothek
airgradientund der Home-Assistant- Integration veröffentlicht sind. An einem echten Messgerät wurde sie noch nicht ausprobiert: Sag uns im Gladys-Forum, was funktioniert und was nicht.
Diese Integration steht in keiner Verbindung zu AirGradient.
Was du bekommst
- Ein Gerät pro Messgerät, automatisch in deinem Netzwerk gefunden (mDNS) oder über seine IP-Adresse hinzugefügt.
- Seine Messwerte, jede Minute aktualisiert: PM1, PM2,5, PM10, CO₂, Temperatur, Luftfeuchtigkeit, TVOC-Index, NOx-Index, Partikelzahl 0,3 µm, WLAN-Signal (und der Akku des Go). Nur was dein Modell misst: Ein Open Air ohne CO₂-Sensor bekommt keine CO₂-Funktion.
- Die korrigierten Werte, wenn die Firmware sie liefert (PM2,5 mit EPA-Korrektur, Temperatur und Luftfeuchtigkeit des Open Air): Es sind die, die das Messgerät anzeigt.
- Optional die Einstellungen des Messgeräts aus Gladys: Display-Helligkeit, Helligkeit der LED-Leiste, Modus der LED-Leiste und Temperatureinheit des Displays (AirGradient ONE, DIY-Kits).
- Ein Dashboard-Widget „Luftqualität“: die Live-Messwerte und die Luftqualität in Farbe.
- Einen Szenen-Auslöser, wenn ein Messgerät nicht mehr antwortet, und eine Szenen-Aktion zum Kalibrieren des CO₂-Sensors (standardmäßig deaktiviert).
Voraussetzungen
- Gladys Assistant 5.1.0 oder neuer.
- Ein AirGradient-Messgerät mit Firmware 3.1 oder neuer (3.0.10 für die lokale API, 3.1.4 für das korrigierte PM2,5), im selben Netzwerk wie Gladys oder in einem Netzwerk, das Gladys erreicht.
- Sonst nichts: Die lokale API braucht kein Passwort.
So findest du die IP-Adresse eines Messgeräts: in der Liste der verbundenen Geräte deines Routers
(das Messgerät heißt airgradient_<Seriennummer>) oder im AirGradient-Dashboard, in den Details
des Messgeräts.
Konfiguration
Installiere die Integration über Integrationen → Aus dem Store installieren (oder Von GitHub installieren) und öffne dann ihren Tab Konfiguration.
Einstellungen
| Einstellung | Standard | Was sie bewirkt |
|---|---|---|
| IP-Adressen der Messgeräte | leer | Optional. Adressen, die die automatische Erkennung nicht findet, durch Kommas getrennt (192.168.1.50). |
| Aktualisierungsintervall | 1 Minute | Wie oft jedes Messgerät gelesen wird: 30 Sekunden, 1, 2 oder 5 Minuten. |
| Einstellungen der Messgeräte aus Gladys | Nein | Fügt den Geräten die Einstellungen von Display und LED-Leiste hinzu (siehe unten). |
| CO₂-Kalibrierung aus Szenen | Nicht erlaubt | Erlaubt die Szenen-Aktion „CO₂-Sensor kalibrieren“. |
| Sprache der Funktionsnamen | Französisch | Namen, die den Funktionen neuer Geräte gegeben werden. |
Die Messgeräte finden
Die Messgeräte melden sich im Netzwerk an (mDNS, Dienst _airgradient._tcp). Die Integration
läuft in einem Container, der diese Meldungen nicht hört: Gladys horcht für sie und gibt sie
weiter. Öffne den Tab Entdecken und füge die gewünschten Messgeräte hinzu.
Fehlt ein Messgerät (anderes Netzwerk, VLAN, vom Router gefiltertes mDNS), gib seine IP-Adresse unter IP-Adressen der Messgeräte ein. Die Schaltfläche Messgeräte suchen sucht erneut und listet die gefundenen auf. Ein Messgerät, das seine Adresse wechselt (DHCP), wird über seine Seriennummer verfolgt: Sein Gerät bleibt dasselbe. Eine feste Adresse im Router ist trotzdem am zuverlässigsten.
Einstellungen der Messgeräte aus Gladys
Steht Einstellungen der Messgeräte aus Gladys auf Ja, bekommen die Geräte des AirGradient ONE und der DIY-Kits zusätzliche Funktionen:
- Display-Helligkeit und Helligkeit der LED-Leiste (0 bis 100 %, die LED-Leiste nur beim ONE);
- Modus der LED-Leiste: aus, CO₂ oder PM2,5 (nur ONE);
- Temperatureinheit des Displays: °C oder °F, nur für das Display des Messgeräts — Gladys bekommt die Temperatur immer in °C und zeigt sie in deiner Einheit an.
Klicke nach dem Ändern dieser Einstellung im Tab Entdecken beim Messgerät auf Aktualisieren.
Ein im AirGradient-Dashboard eingerichtetes Messgerät nimmt seine Einstellungen eventuell nur aus der Cloud. Gladys kann sie dann nicht ändern: Starte Lokale Einstellungen im Tab Konfiguration und wähle das Messgerät. Ab dann nimmt es Einstellungen nur noch aus dem lokalen Netzwerk an, und die des AirGradient-Dashboards gelten für es nicht mehr.
Geräte
Jedes Messgerät ist ein Gerät, benannt nach seinem Modell und dem Ende seiner Seriennummer (zum Beispiel „AirGradient ONE 12f5“): Benenne es nach Belieben um.
| Funktion | Einheit | Hinweise |
|---|---|---|
| PM1 | µg/m³ | Gladys hat keine PM1-Kategorie: Es wird mit dem Symbol von PM2,5 angezeigt. |
| PM2,5 | µg/m³ | Korrigierter Wert, wenn die Firmware ihn liefert. |
| PM10 | µg/m³ | |
| CO₂ | ppm | ONE, Open Air mit CO₂-Sensor, Go, die meisten DIY-Kits. |
| Temperatur | °C | Korrigierter Wert beim Open Air. |
| Luftfeuchtigkeit | % | Korrigierter Wert beim Open Air. |
| TVOC-Index | 1 bis 500 | Sensirion-Index: 100 ist der Mittelwert des letzten Tages, mehr ist schlechter. |
| NOx-Index | 1 bis 500 | Sensirion-Index: 1 ist der Normalwert, mehr bedeutet Stickoxide. |
| Partikel 0,3 µm | pro Deziliter | Rohe Partikelzahl des Feinstaubsensors. |
| Akku | % | Nur AirGradient Go. |
| WLAN-Signal | dBm | -30 ist ausgezeichnet, -80 ist schwach. |
Die Werte werden gerundet (Temperatur auf 0,1 °C, Luftfeuchtigkeit auf 1 %, Partikel auf 0,1 µg/m³) und nur bei einer Änderung an Gladys gesendet; ein gleichbleibender Wert wird alle 12 Stunden erneut gesendet. Das Gerät zeigt ein Abzeichen „lokal“, oder „nicht erreichbar“, wenn das Messgerät nicht antwortet.
Dashboard-Widget
Füge einem Dashboard das Widget Luftqualität (AirGradient) hinzu und wähle in seinen Einstellungen ein Messgerät. Es zeigt CO₂, PM2,5, Temperatur und Luftfeuchtigkeit live und einen farbigen Status:
| Stufe | CO₂ (ppm) | PM2,5 (µg/m³) |
|---|---|---|
| Gut | bis 800 | bis 9 |
| Mäßig | bis 1000 | bis 35 |
| Schlecht | bis 1500 | bis 55 |
| Sehr schlecht | über 1500 | über 55 |
Das sind die Farben der AirGradient-LED-Leiste (für PM2,5 die Grenzwerte der US-EPA; der 24-Stunden-Richtwert der WHO, 15 µg/m³, liegt in der Stufe „mäßig“). Die gesamte Luftqualität ist die schlechtere der beiden.
Szenen-Auslöser
AirGradient-Messgerät antwortet nicht: Ein Messgerät antwortet nicht mehr (drei Messungen hintereinander, drei Minuten mit dem Standardintervall). Filtere auf ein Messgerät oder lass das Feld leer für jedes Messgerät. Variablen: der Name des Messgeräts und seine IP-Adresse. Er wird einmal ausgelöst, wenn das Messgerät verloren geht; seine letzten Werte bleiben in Gladys.
Es gibt keinen Auslöser „CO₂ über 1000“: Nutze den üblichen Geräte-Auslöser von Gladys auf der CO₂-Funktion, mit deinem eigenen Schwellenwert.
Szenen-Aktion
AirGradient-CO₂-Sensor kalibrieren: Der Sensor nimmt seinen aktuellen Messwert als 400 ppm, den Wert frischer Außenluft. Gladys lehnt sie ab, solange CO₂-Kalibrierung aus Szenen nicht auf Erlaubt steht. Starte sie nur, wenn das Messgerät seit einigen Minuten draußen ist (oder an einem weit geöffneten Fenster): Drinnen wären alle späteren Messwerte zu niedrig. Der CO₂-Sensor kalibriert sich auch selbst über einige Tage (automatische Basislinien-Kalibrierung): Die meisten brauchen diese Aktion nie.
Szenen-Beispiele
- Lüften: Wenn das CO₂ im Schlafzimmer über 1200 ppm steigt, sende die Nachricht „Mach das Fenster auf“ — und wenn es wieder unter 800 ppm fällt: „Du kannst es schließen“.
- Rauch oder Luftverschmutzung: Wenn das PM2,5 des Open Air über 35 µg/m³ steigt, schließe die Rollläden und schalte den Luftreiniger ein.
- Messgerät verloren: Mit dem Auslöser „AirGradient-Messgerät antwortet nicht“ eine Nachricht
mit
{{triggerEvent.data.name}}und seiner Adresse senden. - Nachtmodus (mit den Einstellungen): Um 22 Uhr Display-Helligkeit und Helligkeit der LED-Leiste des ONE auf 0 setzen, um 7 Uhr wieder auf 80.
Fehlerbehebung
- Kein Messgerät im Tab Entdecken: Prüfe, ob das Messgerät mit dem WLAN verbunden ist (sein Display zeigt die Messwerte, keine Einrichtungsmeldung), gib dann seine IP-Adresse unter IP-Adressen der Messgeräte ein und klicke auf Messgeräte suchen. Der Bericht sagt, ob die automatische Erkennung verfügbar ist.
- „antwortet nicht“: Das Messgerät ist aus, außer WLAN-Reichweite oder hat eine neue Adresse.
Öffne
http://<IP-Adresse>/measures/currentin einem Browser im selben Netzwerk: Die Messwerte sollten als JSON erscheinen. Eine Firmware vor 3.0.10 hat keine lokale API: Aktualisiere sie am Messgerät. - Eine Einstellung wird abgelehnt, „nimmt nur Einstellungen aus der AirGradient-Cloud an“: Starte Lokale Einstellungen.
- Ein Wert fehlt direkt nach einem Neustart des Messgeräts: Die Sensoren brauchen bis zu einer Minute bis zum ersten Messwert; der Wert kommt bei der nächsten Aktualisierung.
- Protokolle: Die Seite Supervision von Gladys zeigt die Protokolle der Integration. Diese sind
absichtlich ruhig: eine Zeile, wenn ein Messgerät gefunden, verloren oder wieder da ist, und eine
pro Aktion. Setze die Variable
LOG_LEVEL=debug, um jede Messung zu sehen.
Grenzen
- Die Integration liest nur die lokale API. Die Cloud-API von AirGradient (mit Token) wird nicht unterstützt: Ein Messgerät muss von Gladys aus im Netzwerk erreichbar sein.
- Die lokale API hat kein Passwort: Jeder in deinem Netzwerk kann ein Messgerät lesen und seine Einstellungen ändern, wenn es lokale Einstellungen annimmt. So funktioniert die Firmware.
- Die Einstellungen des AirGradient Go (neuere API) und des Open Air (ohne Display) werden nicht angeboten; ihre Messwerte schon.
- TVOC- und NOx-Index erscheinen mit der Kategorie „Sensirion-VOC-Index“: Gladys hat keine NOx-Kategorie. PM1 nutzt die Kategorie PM2,5.
- Die Messwerte sind vom Messgerät berechnete Mittelwerte; öfter als alle 30 Sekunden zu lesen, würde sie nur wiederholen. Die lokale API hat kein Kontingent, aber das Messgerät ist ein kleines Gerät: Eine Messung pro Minute macht auch Home Assistant.
- Im AirGradient-Dashboard geänderte Einstellungen sieht Gladys erst bei der nächsten Messung.
Konfigurationseinstellungen
Diese Einstellungen fragt AirGradient in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Deine Messgeräte finden | section | Nein | AirGradient-Messgeräte (ONE, Open Air, DIY-Kits, Firmware 3.1 oder neuer) im selben Netzwerk wie Gladys werden automatisch gefunden (mDNS): Öffne den Tab „Entdecken“. Fehlt eines, gib unten seine IP-Adresse ein. |
| IP-Adressen der Messgeräte | string | Nein | Optional, durch Kommas getrennt. Nur für Messgeräte nötig, die die automatische Erkennung nicht findet. |
| Aktualisierungsintervall | select | Nein | Wie oft jedes Messgerät gelesen wird. Die Messgeräte mitteln ihre Sensoren über etwa eine Minute. |
| Einstellungen der Messgeräte aus Gladys | select | Nein | Fügt den Geräten die Helligkeit von Display und LED-Leiste, den Modus der LED-Leiste und die Temperatureinheit des Displays hinzu (ONE und DIY-Kits). Klicke danach im Tab „Entdecken“ auf „Aktualisieren“. |
| CO₂-Kalibrierung aus Szenen | select | Nein | Die Kalibrierung nimmt den aktuellen Messwert als 400 ppm: Starte sie nur, wenn das Messgerät an frischer Außenluft ist, sonst sind alle späteren Messwerte falsch. |
| Sprache der Funktionsnamen | select | Nein | Namen, die den Funktionen neuer Geräte gegeben werden (CO₂, Temperatur, Luftfeuchtigkeit…). |
So installierst du AirGradient in Gladys
- Öffne in Gladys Integrationen: AirGradient erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/guim31/gladys-airgradient:1.0.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/guim31/gladys-airgradient.
AirGradient 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
AirGradient 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.
- Alle Integrationen durchsuchen, native und aus der Community
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation