Qingping Smart-Home-Integration, kostenlos und Open Source
Qingping-Luftmonitore und Thermometer über die Qingping-Cloud: CO₂, Feinstaub, VOC, Temperatur.
Veröffentlicht von guim31
- Geräte
- Version 1.0.1
- Erfordert Gladys >=5.1.0
- ★ 0
Überblick
Diese Integration bringt deine Qingping-Luftmonitore und Thermometer in Gladys, über die offizielle Qingping-Cloud-API — die Cloud, die auch die Qingping+-App nutzt. Jedes Gerät deines Qingping-Kontos wird ein Gladys-Gerät mit allem, was es misst: Temperatur, Luftfeuchtigkeit, CO₂, PM2,5, PM10, VOC, Lärm, Luftdruck, Batterie und das Alter der letzten Messung.
Zusätzlich zu den Werten bekommst du eine verständliche Luftqualitätsstufe (Gut, Mäßig, Schlecht, Sehr schlecht) mit dem verantwortlichen Schadstoff, ein Dashboard-Widget, Szenen-Auslöser, wenn sich die Luftqualität ändert oder ein Gerät verstummt, und eine Szenen-Aktion, die die Luftqualität in Worten liefert.
Gedacht für: Qingping Air Monitor Lite, Air Monitor 2, CO₂ Temp & RH Monitor, die WLAN-Thermo-Hygrometer (mit oder ohne Fühler), das Lee-Guitars-Hygrometer und die Bluetooth-Sensoren, die über ein Qingping-Gateway oder die App synchronisiert werden. Jedes Gerät, das die API liefert, wird unterstützt: Die Funktionen folgen den Messwerten, die es sendet.
Developed without the hardware: feedback welcome — ohne die Hardware entwickelt: Rückmeldungen sind willkommen. Die Integration wurde anhand der Qingping-API-Dokumentation und der Open-Source-Clients der Community geschrieben und gegen eine simulierte Cloud getestet. Wenn mit deinem Gerät etwas nicht stimmt, eröffne bitte ein Ticket auf github.com/guim31/gladys-qingping/issues.
Diese Integration ist nicht mit Qingping verbunden (Qingping Technology / ClearGrass). Qingping ist deren Marke.
Voraussetzungen
- Gladys Assistant 5.1.0 oder neuer.
- Deine Geräte in der Qingping+-App eingebunden, im Qingping-Modus (ein im HomeKit-Modus gekoppeltes Gerät sendet nichts an die Qingping-Cloud).
- Ein kostenloser Entwicklerzugang auf developer.qingping.co, mit demselben Konto wie die App.
- Gladys braucht Internetzugang (
oauth.cleargrass.comundapis.cleargrass.com, HTTPS).
Konfiguration
App Key und App Secret besorgen
- Füge deine Geräte in der Qingping+-App hinzu und prüfe, dass sie dort Werte anzeigen.
- Melde dich auf developer.qingping.co mit dem Konto der App an (gleiche Region).
- Öffne Access Management (direkter Link) und kopiere App Key und App Secret. Das ist kostenlos.
Einstellungen
- App Key und App Secret: aus Access Management kopiert. Das Secret wird von Gladys gespeichert und nie in die Protokolle geschrieben.
- Abfrage der Cloud: Automatisch (empfohlen) liest die Cloud direkt nach jeder erwarteten Übertragung der Geräte, anhand ihres Sendeintervalls. Stattdessen kannst du ein festes Intervall wählen (5 Minuten bis eine Stunde).
- Sprache der Gerätefunktionen: die Namen der Funktionen beim Hinzufügen eines Geräts (danach unveränderlich) und die Sprache der Texte für Szenen. Standard: Französisch.
Klicke auf Verbindung testen: Das Ergebnis listet deine Geräte und das Alter ihrer letzten Messung. Öffne dann den Tab Erkennung und füge die gewünschten Geräte hinzu.
Wie oft sich die Werte ändern. Die Cloud kennt nur, was die Geräte gesendet haben. Ein Luftmonitor im Akkubetrieb sendet standardmäßig alle 15 Minuten (das Sendeintervall der Qingping+-App); am Netzteil kann er jede Minute senden. Ein Bluetooth-Thermometer sendet, wenn die App oder ein Gateway es synchronisiert. Häufigere Abfragen der Cloud bringen keine frischeren Werte: Im automatischen Modus liest die Integration sie einmal pro erwarteter Übertragung — nie öfter als alle 2 Minuten, nie seltener als einmal pro Stunde. Eine Anfrage liest alle Geräte des Kontos.
Kontingente. Qingping veröffentlicht kein Anfragekontingent für seine offene API. Die Integration fordert etwa alle 2 Stunden ein Token an (es wird in /data gespeichert, ein Neustart fordert kein neues an) und stellt eine Anfrage pro Abfrage — etwa 100 pro Tag bei einem Sendeintervall von 15 Minuten. Antwortet die Cloud mit „zu viele Anfragen“, wartet sie mindestens 15 Minuten, oder länger, wenn die Cloud das verlangt.
Geräte
Ein Gladys-Gerät pro Gerät deines Qingping-Kontos, benannt wie in der Qingping+-App. Seine Identität ist seine MAC-Adresse: Ein Umbenennen in der App behält es in Gladys.
Funktionen
Jedes Gerät erhält die Funktionen der Messwerte, die es sendet, alle nur lesbar:
| Funktion | Einheit | Modelle |
|---|---|---|
| Temperatur | °C | alle |
| Fühlertemperatur | °C | Thermometer mit externem Fühler |
| Luftfeuchtigkeit | % | alle |
| CO₂ | ppm | Luftmonitore, CO₂-Monitor |
| PM2,5 | µg/m³ | Luftmonitore |
| PM10 | µg/m³ | Luftmonitore |
| VOC | ppb | Air Monitor (erste Generation) |
| VOC-Index | 1–500 | Air Monitor 2 (100 = die übliche Luft des Raums) |
| Lärm | dB | Air Monitor 2 |
| Luftdruck | kPa | Thermometer mit Barometer |
| Batterie | % | Akkugeräte |
| Alter der Messung | min | alle: Minuten seit der letzten Übertragung |
Das Alter der Messung unterscheidet einen stabilen Wert von einem eingefrorenen: Steigt es über das Doppelte des Sendeintervalls, sendet das Gerät nicht mehr (Akku, WLAN, außer Reichweite). Das Abzeichen des Geräts wechselt dann auf „nicht erreichbar“.
Ein Messwert, den ein Gerät erst später sendet (ein Sensor, der sich nach einem Neustart aufwärmt), fügt seine Funktion hinzu: Gladys bietet dann im Tab Erkennung Aktualisieren an. Ein Sensor, der sich als defekt oder in der Aufwärmphase meldet, veröffentlicht nichts statt eines falschen Werts.
Luftqualitätsstufe
Jeder Monitor erhält eine Luftqualitätsstufe, die schlechteste seiner Schadstoffe:
| Stufe | CO₂ (ppm) | PM2,5 (µg/m³) | PM10 (µg/m³) | VOC (ppb) | VOC-Index |
|---|---|---|---|---|---|
| Gut | unter 800 | unter 15 | unter 45 | unter 220 | unter 150 |
| Mäßig | 800–999 | 15–34 | 45–99 | 220–659 | 150–249 |
| Schlecht | 1000–1999 | 35–54 | 100–199 | 660–2199 | 250–399 |
| Sehr schlecht | ab 2000 | ab 55 | ab 200 | ab 2200 | ab 400 |
Die Schwellen folgen den Leitwerten des Umweltbundesamts für Innenraumluft (CO₂, VOC), den WHO-Leitlinien 2021 und den Grenzen der US-EPA (Feinstaub). Gegen Hin-und-her-Springen sinkt eine Stufe erst, wenn der Wert 5 % unter der überschrittenen Schwelle liegt. Temperatur, Luftfeuchtigkeit und Lärm zählen nicht: Das ist Komfort, keine Luftqualität. Ein Thermometer hat keine Luftqualitätsstufe.
Dashboard-Widget
Qingping-Luftqualität: Füge es einem Dashboard hinzu und wähle ein Gerät, oder lass das Gerät leer, um alle zu sehen.
- Ein Gerät: sein Name, bis zu sechs Kacheln (CO₂, PM2,5, Temperatur, Luftfeuchtigkeit, PM10, VOC…) nach Stufe eingefärbt, dann die Luftqualität in Worten mit ihrer Ursache (zum Beispiel Schlecht · CO₂), das Alter der letzten Messung und die Batterie.
- Alle Geräte: eine Zeile pro Gerät mit seiner Luftqualität, oder Temperatur und Luftfeuchtigkeit bei einem Thermometer.
Ein Gerät, das nicht mehr sendet, zeigt Keine aktuelle Messung statt einer eingefrorenen Stufe. Das Widget funktioniert schon, bevor die Geräte in Gladys hinzugefügt sind.
Szenen-Auslöser
- Luftqualität geändert: Die Stufe eines Monitors hat sich geändert. Filter: der Monitor, die neue Stufe, die Richtung (Wird schlechter oder Wird besser). Variablen: Name des Monitors, Stufe, vorherige Stufe, Hauptschadstoff, Richtung, CO₂ und PM2,5.
- Gerät meldet nichts mehr: seit zwei Sendeintervallen (mindestens 30 Minuten) keine neue Messung, oder die Qingping-Cloud meldet das Gerät als offline. Variablen: Gerätename, Minuten seit der letzten Messung, offline laut Qingping.
- Gerät meldet wieder: Ein verstummtes Gerät hat eine neue Messung gesendet. Variable: Minuten ohne Messung.
Um auf einen Wert zu reagieren, der eine Schwelle überschreitet (CO₂ über 1200 ppm, Temperatur unter 5 °C), nutze den üblichen Gladys-Auslöser auf der Gerätefunktion: Er vergleicht Werte bereits.
Szenen-Aktion
Luftqualität abrufen: liest die Luftqualität eines Monitors aus seiner letzten Messung (ohne Anfrage an die Cloud) und gibt den nächsten Aktionen der Szene: die Stufe (Code, Zahl von 1 Gut bis 4 Sehr schlecht, und Bezeichnung), den Hauptschadstoff, CO₂, PM2,5, die Minuten seit der Messung und ob die Messung aktuell ist. Nutze sie in einer Nachricht („Luft im Schlafzimmer: {Stufe}“) oder in einer Bedingung „nur fortfahren, wenn“.
Konfigurationsaktionen
- Verbindung testen: liest sofort die Cloud und listet die Geräte mit dem Alter ihrer Messung.
- Sendeintervall einstellen: ändert, wie oft ein Luftmonitor sendet (1 Minute bis 1 Stunde). Das Gerät übernimmt es bei der nächsten Übertragung, und die Integration folgt dem neuen Takt. Ein kurzes Intervall leert den Akku viel schneller: Bleib im Akkubetrieb bei 15 Minuten. Die anderen Geräte (Thermometer) stellst du in der Qingping+-App ein.
Szenenbeispiele
- Schlafzimmer lüften: Auslöser Luftqualität geändert, Monitor Schlafzimmer, neue Stufe Schlecht und Sehr schlecht, Richtung Wird schlechter → Nachricht „Öffne das Schlafzimmerfenster: {Hauptschadstoff} ist hoch“ senden, oder die Lüftung einschalten.
- Die Luft ist wieder gut: Auslöser Luftqualität geändert, neue Stufe Gut, Richtung Wird besser → Lüftung ausschalten.
- Monitor prüfen: Auslöser Gerät meldet nichts mehr → Nachricht „{Gerätename} sendet seit {Minuten} min nichts: Akku oder WLAN?“ senden.
- Morgenbericht: täglich um 7:00 → Luftqualität abrufen für das Schlafzimmer → „Luft im Schlafzimmer: {Stufe}, CO₂ {co2} ppm“ senden.
Fehlerbehebung
- „App Key oder App Secret von Qingping abgelehnt“: Kopiere beide erneut aus Access Management, ohne Leerzeichen, und speichere. Prüfe, dass du dich auf developer.qingping.co mit dem Konto der App angemeldet hast.
- Verbunden, aber kein Gerät: Die Geräte müssen in der Qingping+-App desselben Kontos sein, im Qingping-Modus (nicht HomeKit). Ein nur in HomeKit gekoppeltes Gerät erreicht die Qingping-Cloud nicht.
- Die Werte bewegen sich nicht: Sieh dir das Alter der Messung an. Steigt es, sendet das Gerät nicht (Akku, WLAN, Gateway). Bleibt es niedrig, sind die Werte einfach stabil.
- Eine Funktion fehlt: Warte auf eine Messung, in der der Sensor sie sendet (ein CO₂-Sensor wärmt sich nach einem Neustart einige Minuten auf), und klicke dann im Tab Erkennung beim Gerät auf Aktualisieren.
- Mehr Details: Setze
LOG_LEVEL=debugfür die Integration, um jede Abfrage in ihren Protokollen zu sehen. App Secret und Token erscheinen dort nie.
Einschränkungen
- Nur Cloud: Die Integration liest die Qingping-Cloud, nie die Geräte in deinem Netzwerk. Ohne Internet stoppen die Werte (die Geräte behalten ihren Verlauf in der Cloud).
- Die Werte sind so frisch wie die Übertragungen der Geräte: im Akkubetrieb standardmäßig 15 Minuten.
- Nur lesend: Die einzige Einstellung, die die Integration ändert, ist auf Wunsch das Sendeintervall der Luftmonitore.
- Eine Verlaufslücke, während Gladys aus war, wird nicht nachgeholt: Nur die letzte Messung wird gelesen.
- Geräte, die die Qingping-Cloud nicht bereitstellt (HomeKit-Modus, manche reine Bluetooth-Sensoren ohne Gateway), können nicht erscheinen.
- Ohne Hardware und ohne Konto entwickelt: Die API-Antworten wurden aus der Qingping-Dokumentation und Community-Clients rekonstruiert. Melde Auffälligkeiten auf github.com/guim31/gladys-qingping/issues.
Konfigurationseinstellungen
Diese Einstellungen fragt Qingping in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Dein Qingping-Konto | section | Nein | Kostenlos. Melde dich mit dem Konto der Qingping+-App auf developer.qingping.co an, öffne Access Management und kopiere App Key und App Secret. Die Geräte müssen in der Qingping+-App eingebunden sein (Qingping-Modus, nicht HomeKit). |
| App Key | string | Ja | Der App Key aus Access Management auf developer.qingping.co. |
| App Secret | secret | Ja | Das App Secret neben dem App Key. Von Gladys gespeichert, nie in die Protokolle geschrieben. |
| Abfrage der Cloud | select | Nein | Automatisch: direkt nach jeder erwarteten Übertragung der Geräte (ihr Sendeintervall aus der Qingping+-App). Häufigere Abfragen bringen keine frischeren Werte. |
| Sprache der Gerätefunktionen | select | Nein | Namen der Funktionen beim Hinzufügen eines Geräts und Sprache der Szenentexte. |
So installierst du Qingping in Gladys
- Öffne in Gladys Integrationen: Qingping erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/guim31/gladys-qingping: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-qingping.
Qingping 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
Qingping 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