Intégration domotique Airthings, gratuite et open source
Radon, CO₂, COV, particules, température et humidité de vos capteurs Airthings.
Publiée par guim31
- Appareils
- Version 1.0.1
- Nécessite Gladys >=5.1.0
- ★ 0
Fait entrer vos capteurs de qualité de l'air Airthings dans Gladys : radon, CO₂, COV, particules, température, humidité, pression, batterie et âge de la dernière mesure, lus par l'API cloud officielle d'Airthings. Un widget de tableau de bord montre l'air de chaque pièce d'un coup d'œil, avec un code couleur clair pour le radon.
Le radon est un gaz radioactif naturel, deuxième cause de cancer du poumon après le tabac, et un vrai sujet dans les régions granitiques (Bretagne, Massif central, Corse, Vosges…). En France, le niveau de référence est de 300 Bq/m³ (moyenne annuelle).
Développée sans le matériel : vos retours sont les bienvenus. Cette intégration a été écrite d'après la spécification officielle de l'API et des réponses publiées, sans capteur ni compte Airthings. Si quelque chose vous semble faux, ouvrez un ticket : https://github.com/guim31/gladys-airthings/issues
Cette intégration n'est pas affiliée à Airthings. Airthings, Wave, View et Space sont des marques d'Airthings ASA.
Prérequis
- Gladys Assistant 5.1.0 ou plus récent.
- Un ou plusieurs capteurs Airthings (Wave, Wave Plus, Wave Mini, Wave Radon, Wave Enhance, View Plus, View Radon, View Pollution, Space…) enregistrés dans l'application Airthings. Les Wave remontent leurs mesures par un Airthings Hub, un View Plus ou l'application du téléphone en Bluetooth : un Wave qui ne se synchronise qu'avec le téléphone n'est mis à jour que quand l'application est ouverte à proximité.
- Un client d'API Airthings (gratuit) : son identifiant et son secret. Un client par compte Airthings.
- Un accès Internet pour Gladys : les données viennent du cloud Airthings, pas directement des capteurs.
Configuration
- Ouvrez le tableau de bord de l'API Airthings (https://consumer-api-doc.airthings.com/dashboard) et connectez-vous avec votre compte Airthings.
- Créez un client d'API, puis copiez son identifiant client (client id) et son secret client (client secret).
- Dans Gladys, ouvrez Intégrations, installez Airthings (Intégrations → Installer depuis GitHub, ou depuis le store), puis remplissez sa configuration :
- Identifiant client et Secret client ;
- Intervalle de relève : 5 minutes recommandées (de 2 à 60 minutes) ;
- Niveau de référence du radon : à partir de ce niveau, le widget affiche le radon en rouge (300 Bq/m³ en France et dans l'UE ; 148 Bq/m³ est le seuil d'action de l'EPA américaine ; 100 Bq/m³ la recommandation de l'OMS) ;
- Langue des noms de fonctionnalités : celle des noms donnés aux nouvelles fonctionnalités (français par défaut).
- Appuyez sur Tester la connexion : le message liste les capteurs trouvés et les requêtes d'API utilisées dans l'heure.
- Ouvrez l'onglet Découverte de l'intégration et ajoutez à Gladys les capteurs voulus.
Appareils et fonctionnalités
Un appareil Gladys par capteur Airthings (le hub, qui ne mesure rien, est laissé de côté). Chaque appareil n'a que les fonctionnalités que son capteur remonte vraiment :
| Fonctionnalité (noms français) | Unité | Capteurs |
|---|---|---|
| Radon (court terme) | Bq/m³ | Wave, Wave Plus, Wave Radon, View Plus, View Radon, Corentium Home 2 |
| Radon (long terme) | Bq/m³ | quand l'API l'envoie |
| CO₂ | ppm | Wave Plus, Wave Enhance, View Plus, View CO2, Space |
| COV | ppb | Wave Plus, Wave Mini, Wave Enhance, View Plus |
| PM1 | µg/m³ | View Plus, View Pollution |
| PM2.5 | µg/m³ | View Plus, View Pollution |
| PM10 | µg/m³ | quand l'API l'envoie |
| Température | °C | la plupart des capteurs |
| Humidité | % | la plupart des capteurs |
| Pression | hPa | Wave Plus, Wave Enhance, View Plus |
| Luminosité | lux | Wave Enhance, quand l'API l'envoie |
| Bruit | dBA | Wave Enhance, quand l'API l'envoie |
| Batterie | % | capteurs à piles |
| Âge de la mesure | minutes | tous les capteurs : l'ancienneté de leur dernière mesure |
Le radon court terme est la moyenne des dernières 24 heures. Gladys n'a pas de catégorie radon : les fonctionnalités radon sont publiées comme des compteurs en Bq/m³, et le widget donne le code couleur. Gladys n'a pas non plus de catégorie PM1 : PM1 est publié comme une fonctionnalité PM2.5 nommée « PM1 ».
Toutes les fonctionnalités sont en lecture seule : rien n'est pilotable.
Widget
Qualité de l'air (tableau de bord → Modifier → ajouter un widget → Airthings) :
- Toutes les pièces (réglage laissé vide) : une ligne par capteur, sa pastille de la couleur de la pire de ses valeurs, les pièces à surveiller en premier ; plus le radon et le CO₂ les plus élevés de la maison.
- Un capteur (choisi dans le réglage) : cinq tuiles (radon, CO₂, PM2.5, température, humidité en premier), la courbe du radon de la semaine une fois l'appareil ajouté à Gladys, le verdict radon, les autres valeurs, la batterie et l'âge de la mesure.
Couleurs : radon vert sous 100 Bq/m³ (OMS), orange jusqu'au niveau de référence de la configuration, rouge au-delà. CO₂ 800 / 1000 ppm, COV 250 / 2000 ppb, particules 10 / 25 µg/m³, humidité bonne de 30 à 60 % : les seuils des applications Airthings.
Déclencheurs et actions
L'intégration ne déclare ni déclencheur ni action de scène propres : les états des appareils couvrent déjà tous les usages avec les déclencheurs de Gladys (« la valeur d'un appareil dépasse un seuil »). La seule action est le bouton Tester la connexion de l'écran de configuration.
Exemples de scènes
- Radon au-dessus de la référence : déclencheur « Radon (court terme) de Cave au-dessus de 300 », action : envoyer un message « Aérez la cave : radon au-dessus de 300 Bq/m³ » et allumer la ventilation (une prise connectée).
- Aérer la chambre : déclencheur « CO₂ de Chambre au-dessus de 1000 », condition : quelqu'un à la maison, action : une notification « Ouvrez la fenêtre de la chambre ».
- Capteur muet : déclencheur « Âge de la mesure de Salon au-dessus de 180 » (trois heures sans remontée), action : un message « Vérifiez le hub Airthings ou les piles ».
- Piles : déclencheur « Batterie de Chambre en dessous de 15 », action : un message pour acheter des piles.
Relève et quota de l'API
L'API Airthings Consumer accepte 120 requêtes par heure et par client d'API. Une relève de tout le compte coûte une requête (50 capteurs par page), plus la liste des appareils une fois par heure et un nouveau jeton toutes les quelques heures : à 5 minutes, l'intégration utilise environ 13 requêtes par heure. Elle ne dépasse jamais 100 par heure d'elle-même, et s'arrête jusqu'à l'heure donnée par l'API quand celle-ci répond « trop de requêtes ».
Les capteurs remontent leurs mesures toutes les 2,5 minutes (gamme View) à 5 minutes ou plus (gamme Wave, par un hub ou le téléphone) : relever plus souvent ne ferait que relire les mêmes valeurs. L'intégration lit le cloud avec son propre minuteur, et ne publie une valeur à Gladys que quand elle change (et au moins toutes les 6 heures). Un capteur ajouté dans Gladys reçoit ses valeurs aussitôt, depuis la dernière relève.
Conservés dans le conteneur : le jeton d'accès, l'identifiant du compte Airthings et les fonctionnalités vues par capteur (sous /data). Le secret client reste dans la configuration de Gladys.
Dépannage
- « identifiant ou secret refusé » : recopiez-les depuis le tableau de bord de l'API Airthings (sans espace) ; un client d'API supprimé doit être recréé. L'intégration réessaie toutes les 30 minutes, ou aussitôt après l'enregistrement de la configuration.
- « quota de requêtes de l'API Airthings atteint » : un autre outil utilise le même client d'API, ou l'intervalle est court. La relève reprend d'elle-même ; choisissez un intervalle plus long.
- Un capteur n'a pas de valeur récente : regardez son Âge de la mesure. Un Wave a besoin d'un hub, d'un View Plus ou de l'application du téléphone à proximité pour remonter ses mesures ; les piles sont peut-être vides.
- Un capteur manque : il doit être enregistré dans l'application Airthings avec le même compte que le client d'API ; appuyez sur Rechercher dans l'onglet Découverte.
- Plus de détails : redémarrez le conteneur avec
LOG_LEVEL=debug. Les journaux ne contiennent jamais l'identifiant client, le secret ni le jeton.
Limites
- Cloud seulement : pas de lecture locale des capteurs en Bluetooth (le conteneur de Gladys n'a pas de Bluetooth).
- Les valeurs sont celles de la dernière remontée du capteur : jusqu'à 5 minutes ou plus de retard pour un Wave.
- Les indices de risque de moisissure et de virus de certains capteurs ne sont pas lus (Gladys n'a pas de fonctionnalité pour eux), ni les commandes du purificateur Renew.
- Les noms des fonctionnalités sont figés quand l'appareil est ajouté dans Gladys.
- Développée sans le matériel : vos retours sont les bienvenus sur https://github.com/guim31/gladys-airthings/issues
Paramètres de configuration
Voici les paramètres demandés par Airthings dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| Client d'API Airthings | section | Non | Ouvrez le tableau de bord de l'API Airthings (lien ci-dessous), connectez-vous avec votre compte Airthings, créez un client d'API, puis copiez ici son identifiant et son secret. Gratuit, un client par compte. Sans lien avec Airthings. |
| Identifiant client (client id) | string | Oui | |
| Secret client (client secret) | secret | Oui | |
| Intervalle de relève | select | Non | Les capteurs remontent leurs mesures toutes les 2,5 à 5 minutes ou plus, et l'API accepte 120 requêtes par heure : 5 minutes suffisent. |
| Niveau de référence du radon | select | Non | À partir de ce niveau, le widget affiche le radon en rouge ; à partir de 100 Bq/m³ (OMS), en orange. |
| Langue des noms de fonctionnalités | select | Non | Gladys ne transmet pas votre langue aux intégrations : choisissez celle des noms donnés aux nouvelles fonctionnalités. |
Comment installer Airthings dans Gladys
- Dans Gladys, ouvrez Intégrations : Airthings 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/guim31/gladys-airthings:1.0.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/guim31/gladys-airthings.
Airthings 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
Airthings 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 guim31, 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