Intégration domotique air-Q, gratuite et open source
Connecteur non officiel : vos capteurs de qualité de l'air air-Q, lus en local.
Publiée par LM1LC3N7
- Appareils
- Version 0.1.1
- Nécessite Gladys >=5.1.0
- ★ 0
Connecteur non officiel, sans lien avec Corant GmbH. Il amène dans Gladys les valeurs de vos capteurs de qualité de l'air air-Q, lues directement sur votre réseau local : sans cloud, sans compte, sans abonnement.
Cette intégration n'a jamais été testée avec un vrai air-Q. Elle suit aioairq, la bibliothèque Python du fabricant qu'utilise Home Assistant. Merci de signaler ce que vous constatez sur le forum Gladys.
Ce que vous obtenez
Un appareil par air-Q, au nom que vous lui avez donné dans l'application air-Q, avec les valeurs que mesure votre modèle (une valeur que l'appareil n'envoie pas n'est simplement pas créée) :
| Capteur dans Gladys | Champ air-Q | Unité |
|---|---|---|
| CO2 | co2 | ppm |
| COV | tvoc | ppb |
| COV (capteur ionique) | tvoc_ionsc | ppb |
| PM2.5, PM10 | pm2_5, pm10 | µg/m³ |
| Monoxyde de carbone | co | ppm |
| Dioxyde d'azote | no2 | µg/m³ |
| Ozone | o3 | µg/m³ |
| Dioxyde de soufre | so2 | µg/m³ |
| Formaldéhyde | ch2o_M10 | µg/m³ |
| Température | temperature | °C |
| Humidité | humidity | % |
| Pression | pressure | hPa |
| Bruit, bruit (crête) | sound, sound_max | dB(A) |
- L'air-Q donne le monoxyde de carbone en mg/m³ ; Gladys ne connaît que le ppm pour lui : la valeur est convertie (× 0,873, à 25 °C et pression normale).
- Pas encore dans Gladys, faute de catégorie pour eux : radon, oxygène, PM1, comptages de particules, humidité absolue, indices « santé » et « performance », indices virus et moisissures, point de rosée (une température qui fausserait celle de la pièce), gaz plus rares de l'air-Q Science. Voir TODO.md.
- Un capteur encore en chauffe après un redémarrage de l'air-Q n'envoie pas de valeur pendant un moment : sa fonction reste, la valeur revient seule.
- Les noms des capteurs sont en anglais ; renommez-les à la création si vous le souhaitez.
Installation
- Donnez à l'air-Q une adresse IP fixe dans votre box (réservation
DHCP) : l'intégration le joint par son adresse. Dans le conteneur de
l'intégration, les noms mDNS (
<id>_air-q.local) ne sont en général pas résolus. - Installez l'intégration depuis le catalogue Gladys (Gladys 5.1 ou plus récent).
- Dans l'écran Configuration, saisissez l'adresse et le mot de passe de l'appareil, puis enregistrez. Jusqu'à trois air-Q.
- Cliquez sur Tester les air-Q : le message affiche les principales valeurs de chacun.
- Ouvrez l'onglet Découverte et ajoutez les appareils. Leurs valeurs arrivent dès leur création.
Configuration
- Adresse : l'adresse IPv4 de l'air-Q (
192.168.1.50), avec un port si besoin, ou son nom d'hôte ; l'identifiant de 5 caractères imprimé sur l'appareil devient<id>_air-q.local, comme dans aioairq, pour un réseau qui résout les noms mDNS. Un chemin, une adresse IPv6 ou des identifiants sont refusés. - Mot de passe : le mot de passe de l'appareil défini dans l'application
air-Q (
airqsetupà la livraison : changez-le dans l'application). Il est gardé par Gladys dans sa base (en clair, comme tout champ secret de Gladys) et jamais réaffiché dans l'écran de configuration. Il ne quitte jamais l'intégration : l'air-Q protège ses réponses en AES-256 avec une clé tirée de ce mot de passe, et l'intégration s'en sert seulement pour les ouvrir. Il n'est jamais écrit dans les journaux ni sous/data. - Valeurs : moyennées (lissées par l'air-Q, le choix par défaut de son application et de Home Assistant) ou instantanées.
- Intervalle de lecture : 2 minutes par défaut, de 1 à 60.
À quel rythme l'air-Q est lu
- Une requête par air-Q à chaque intervalle :
GET /average(ou/data), précédée deGET /config(l'identifiant et le nom de l'appareil) à la première lecture et après tout échec, car l'adresse peut alors mener à un autre air-Q. - Jamais plus vite que l'intervalle, compté depuis la dernière requête envoyée : ni par le bouton de test, ni par une reconnexion à Gladys, ni par un enregistrement de la configuration, ni par un redémarrage du conteneur. Seuls une nouvelle adresse ou un nouveau mot de passe sont lus tout de suite. Avant la fin de l'intervalle, le bouton de test affiche les dernières valeurs et l'heure de la prochaine lecture possible.
- Lecture seule : l'intégration n'écrit jamais sur l'air-Q (aucun changement de configuration, aucun clignotement, aucun redémarrage).
- Les valeurs appartiennent à l'appareil qui les a mesurées : chaque réponse porte l'identifiant de l'air-Q ; si un autre air-Q répond désormais à l'adresse (deux appareils dont la box a échangé les adresses), rien n'est publié jusqu'à ce que son identifiant soit relu, puis sous son propre appareil.
- Un échec (pas de réponse, autre statut HTTP, réponse qui n'est pas celle d'un air-Q) est réessayé à l'intervalle suivant, jamais plus tôt.
- Quand l'air-Q répond 429 ou 5xx (occupé, en redémarrage), il est
laissé tranquille pendant le délai
Retry-Afterqu'il donne, sinon 5 minutes, puis 10, 20… ; toujours entre 1 minute et 6 heures, et jamais moins que l'intervalle. - Quand le mot de passe ne convient pas (la réponse ne s'ouvre pas), les lectures de cet air-Q s'arrêtent et le statut le dit ; un nouvel essai toutes les 6 heures (le bouton de test peut réessayer dès que l'intervalle est écoulé), jusqu'à ce que vous changiez le mot de passe.
- L'heure de la dernière requête, les pauses, les refus et l'identifiant, le
nom et les capteurs de chaque air-Q (rien de secret) survivent à une
reconnexion à Gladys et à un redémarrage du conteneur : ils sont gardés
dans un fichier sous
/data, jamais le mot de passe. Seulement pendant qu'un mot de passe est refusé, le fichier garde une empreinte salée (scrypt) de ce mot de passe faux, pour qu'après un redémarrage un nouveau mot de passe soit essayé tout de suite ; elle est effacée dès la première lecture réussie : rien dans le fichier ne permet de confirmer un mot de passe qui fonctionne. Un nouveau mot de passe est essayé tout de suite pendant que l'intégration tourne ; un mot de passe changé conteneur arrêté attend au plus un intervalle. Après un redémarrage, l'onglet Découverte continue d'afficher les appareils jusqu'à la lecture suivante. - Une réponse de plus de 256 Ko, ou de plus de 10 secondes, est abandonnée.
Dépannage
- « mot de passe refusé » : vérifiez le mot de passe de l'appareil dans l'application air-Q (celui de l'appareil, pas celui de votre compte air-Q).
- « pas de réponse » : vérifiez l'adresse (IP fixe), que l'air-Q est sur le même réseau que Gladys et que son Wi-Fi n'est pas coupé par le mode nuit.
- « réponse qui n'est pas celle d'un air-Q » : l'adresse mène à un autre appareil.
- « même air-Q qu'une autre adresse » : deux adresses mènent au même appareil ; n'en gardez qu'une.
- Journaux : le niveau se règle avec la variable
LOG_LEVEL.
Vie privée
Tout reste sur votre réseau local : l'intégration ne parle qu'aux adresses que vous saisissez, en HTTP (l'air-Q n'a pas de HTTPS), et ses réponses sont protégées par l'appareil lui-même. Ni cloud, ni compte.
Remerciements
Construit d'après aioairq
(Apache-2.0, Corant GmbH, le fabricant de l'air-Q), la bibliothèque de
l'intégration air-Q de Home Assistant : la protection de l'API locale, les
routes, les champs et le traitement des valeurs sont portés en JavaScript.
Sa notice est dans THIRD_PARTY_NOTICES.md. air-Q est une marque de son
propriétaire ; ce connecteur est gratuit et non officiel.
Paramètres de configuration
Voici les paramètres demandés par air-Q dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| air-Q dans Gladys | section | Non | Connecteur non officiel, sans lien avec Corant GmbH. Il lit vos capteurs air-Q directement sur votre réseau local (sans cloud ni compte) : CO2, COV, PM2.5, PM10, les gaz que mesure votre modèle (CO, NO2, O3, SO2, formaldéhyde), température, humidité, pression et bruit. Lecture seule : rien n'est jamais modifié sur l'appareil. Saisissez l'adresse IP de chaque air-Q (une adresse fixe dans votre box est préférable) et son mot de passe d'appareil. Jamais testé avec un vrai air-Q pour l'instant. |
| Adresse de l'air-Q | string | Non | Son adresse IPv4 sur votre réseau (ou son nom d'hôte, ou l'identifiant de 5 caractères imprimé sur l'appareil si votre réseau résout les noms mDNS). |
| Mot de passe de l'air-Q | secret | Non | Le mot de passe de l'appareil, défini dans l'application air-Q (« airqsetup » à la livraison). Gardé par Gladys dans sa base, jamais réaffiché ; il ne quitte jamais l'intégration : il sert seulement à ouvrir les réponses de l'air-Q. |
| Valeurs | select | Non | Moyennées (lissées par l'air-Q, comme dans son application) ou instantanées. |
| Intervalle de lecture (minutes) | number | Non | Une requête par air-Q à chaque fois (deux quand son identifiant est revérifié). Rien ne le lit plus tôt, ni le bouton de test ni un redémarrage. |
| Autres air-Q (facultatif) | section | Non | Jusqu'à trois air-Q, chacun avec son adresse et son mot de passe. |
| Deuxième air-Q : adresse | string | Non | |
| Deuxième air-Q : mot de passe | secret | Non | Gardé par Gladys dans sa base, jamais réaffiché ; il ne quitte jamais l'intégration. |
| Troisième air-Q : adresse | string | Non | |
| Troisième air-Q : mot de passe | secret | Non | Gardé par Gladys dans sa base, jamais réaffiché ; il ne quitte jamais l'intégration. |
Comment installer air-Q dans Gladys
- Dans Gladys, ouvrez Intégrations : air-Q apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
- Cliquez sur Installer. Gladys télécharge l'image Docker (
ghcr.io/lm1lc3n7/gladys-air-q:0.1.1), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration). - Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
- Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/LM1LC3N7/gladys-air-q.
air-Q nécessite Gladys >=5.1.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.
Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.
À propos des intégrations externes
air-Q est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par LM1LC3N7, et non par l'équipe cœur de Gladys.
- Parcourir toutes les intégrations, natives et communautaires
- Créer et publier votre propre intégration externe
- Code source sur GitHub — source de cette documentation