Aller au contenu principal

Intégration domotique Aqara, gratuite et open source

Intégration Aqara pour Gladys Assistant

Hubs Aqara et leurs appareils par l’API ouverte Aqara (cloud).

Amène dans Gladys les appareils de votre compte Aqara : les hubs (M2, M3, M1S…) et ce qui leur est appairé — capteurs de température, d’humidité et de pression, capteurs de porte et de fenêtre, détecteurs de fuite, de présence, de fumée et de CO, prises, lumières et rideaux. Par l’API ouverte Aqara officielle (le cloud), avec un projet développeur à vous. Intégration non officielle, sans lien avec Aqara, jamais testée avec un vrai appareil : dites-nous ce qui marche et ce qui ne marche pas.

1. Créer un projet développeur​

  1. Connectez-vous sur https://developer.aqara.com/ avec un compte Aqara (celui de votre app Aqara Home convient).
  2. Console, Project Management, New project ; attendez son approbation.
  3. Dans le détail du projet : l’App ID ; dans Key Management : le Key ID et l’App Key.

Copiez ces trois valeurs dans la configuration et choisissez le serveur de votre compte Aqara (Europe, États-Unis, Chine continentale, Corée du Sud, Russie, Singapour : celui choisi dans l’app Aqara Home). L’App Key est gardée par Gladys dans sa base, jamais réaffichée ; elle sert seulement à signer les requêtes (signature MD5 de la documentation) et ne sort jamais elle-même de l’intégration.

2. Autoriser votre compte Aqara​

  1. Saisissez l’adresse e-mail ou le numéro de téléphone du compte Aqara qui possède les appareils, et enregistrez.
  2. Cliquez sur Envoyer le code de vérification : Aqara envoie un code de vérification à ce compte (e-mail ou SMS), valable 10 minutes. Un code n’est demandé que sur votre clic, jamais au démarrage ni par une lecture, et jamais deux fois en moins d’une minute.
  3. Saisissez le code dans le bouton Autoriser et cliquez. Les deux jetons (accès et renouvellement) sont remplis dans la configuration par l’intégration.

Le jeton d’accès est demandé pour 7 jours et renouvelé avec le jeton de renouvellement un jour avant son expiration (ou quand Aqara le dit expiré) ; les jetons renouvelés sont enregistrés dans la configuration de Gladys. Si Aqara refuse le renouvellement (jeton expiré 30 jours de plus sans lecture, ou révoqué), le statut dit « autorisez à nouveau » : plus rien n’est envoyé avec ces jetons tant que vous n’avez pas autorisé à nouveau.

Les clés, les jetons, le compte et le code ne sont jamais écrits dans les journaux, le statut ni /data.

Appareils​

La Découverte propose chaque appareil qui a au moins une des valeurs ci-dessous, d’après la description « trait » qu’Aqara donne de son modèle :

Trait AqaraGladysCommandé
OnOff d’une lumièremarche/arrêt de lumièreoui
CurrentLevel d’une lumière (%)luminosité 0-100oui
OnOff d’une prise ou d’un interrupteurinterrupteur marche/arrêtoui
CurrentPositionPercentageposition de rideau (lecture seule, sens à confirmer)non
CurrentTemperature (°C), CurrentHumidity (%), CurrentPressure (kPa)capteursnon
CurrentIlluminance (lux), CO2Density (ppm), PM2.5Density (µg/m³), VOCDensity (ppb)capteursnon
BatPercentRemaining (%)batterienon
CurrentPower (W), CurrentVoltage (V), CircuitCurrent (A)puissance, tension, intensiténon
ContactSensorStatecapteur d’ouverturenon
LeakState, Occupancy, SmokeDetected, CODetectedfuite, présence, fumée, COnon

Une valeur dans une autre unité que celle listée, hors de sa plage, ou un texte, est inconnue : elle n’est jamais publiée (jamais comme 0). Un appareil hors ligne (Reachable faux) ne publie rien. Une mesure est publiée une fois par date source, jamais si elle a plus de 2 heures (une valeur sans date source est publiée tant que l’appareil est en ligne) ; marche/arrêt, positions et détecteurs sont publiés comme l’état courant.

En lecture seule dans cette version : positions de rideaux (pour tout type d’appareil), serrures, caméras, sonnettes, portes de garage, vannes, pompes, ouvre-fenêtres, chauffage (cheminée comprise), climatisation et appareils de cuisson : un appareil de l’un de ces types n’est jamais écrit, même ses autres valeurs (une serrure n’est jamais ouverte). Le compteur d’énergie (CumulativeEnergyConsumption), couleurs et température de couleur, boutons et cubes (événements seulement) ne sont pas encore gérés.

Sens à confirmer sur un vrai appareil (la documentation Aqara n’en définit aucun ; HomeKit, dont Aqara reprend les noms, et Matter sont opposés) :

  • position de rideau : affichée telle qu’Aqara la donne, supposée 0 = fermé, 100 = ouvert (HomeKit) ; jamais écrite tant qu’un testeur ne l’a pas confirmée ;
  • capteur d’ouverture : « vrai » est pris pour ouvert (HomeKit « contact non détecté »), sauf si la description Aqara du modèle nomme les valeurs (Open / Close).

Commandes​

  • Éteindre (marche/arrêt 0, luminosité 0) part tout de suite, pendant une pause demandée par Aqara, au-delà du budget quotidien, pendant qu’un renouvellement de jeton est dû ou en cours (avec le jeton courant), avant que la liste des appareils soit relue (juste après un redémarrage, les paramètres d’appareil de Gladys disent où écrire), et quand /data est illisible. Une lecture en cours est coupée pour lui. Refus d’une extinction : pas encore de configuration (gardée 2 minutes, envoyée dès qu’elle est lue), clés ou jetons absents, clés ou autorisation refusées par Aqara pendant cette exécution, jeton de renouvellement refusé par Aqara (jamais renvoyé), valeur en lecture seule, valeur pas encore connue (aucune lecture depuis le démarrage et pas de paramètres d’appareil dans Gladys). Elle est confirmée par les lectures 5 s et 20 s plus tard ; contredite (ancienne valeur avec une date source plus ancienne), elle est renvoyée, deux fois au plus ; changée après elle (date source plus récente : l’app Aqara, un interrupteur mural, une automatisation), elle n’est pas renvoyée ; sans date source, ou si aucune lecture n’a pu la montrer, elle n’est pas renvoyée et le statut dit « Non confirmé ». Un envoi qui n’a pas pu partir (réseau, 429, 5xx, appareil hors ligne, jeton refusé juste après son renouvellement) est réessayé toutes les 10 s, 6 fois en 2 minutes. Seule une extinction est gardée au redémarrage (2 minutes au plus).
  • Allumer, une luminosité sont refusés pendant une pause, au-delà du budget, quand la liste des appareils a plus de 15 minutes (ou deux intervalles de lecture s’ils sont plus longs), quand l’appareil est hors ligne ou la valeur en lecture seule. Ils sont revérifiés juste avant de partir ; un ordre pas encore parti à la réponse de 3 s (« rien envoyé ») est coupé et ne part jamais plus tard. Envoyés, ils sont confirmés de la même façon (lectures 5 s et 20 s plus tard). Une commande en file avant une extinction du même point d’accès ne part jamais après elle : une extinction coupe tout allumage de son point d’accès pas encore parti (connexion en cours comprise, revérifié au premier octet) ; un allumage déjà parti qui arrive chez Aqara après elle ne compte jamais comme un changement plus récent : l’extinction est renvoyée.

Lectures et quota​

Chaque lecture coûte un appel par tranche de 50 valeurs, plus la liste des appareils toutes les 10 minutes et les descriptions des nouveaux modèles. Par défaut toutes les 120 s (60 s au moins). Le budget quotidien (3000 appels par défaut, jour UTC) est compté avant chaque appel et gardé au redémarrage : une fois épuisé, les lectures s’arrêtent jusqu’au lendemain ; éteindre part toujours. Réglez-le sous le quota de votre projet. Un 429, ou un serveur occupé pendant une lecture (codes 100, 104, 5xx), met tout en pause sauf les arrêts (un 5xx en réponse à une commande ne met rien en pause), 1 minute doublée jusqu’à 6 heures (ou le Retry-After s’il est plus long), gardée au redémarrage. Une seule requête de lecture à la fois.

Refus : les clés refusées (codes 106 signature invalide, 107 App Key illégale, 2002 App ID ou App Key illégaux) arrêtent tout jusqu’à ce que vous les changiez ou cliquiez sur Tester la connexion (qui les essaie toujours) ; une permission refusée sur une route (403, 2008, 2012, 2013, 2014, 2022…) n’est jamais prise pour un refus des clés. Un renouvellement refusé (2006, 2007) met fin à l’autorisation : autorisez à nouveau. Un jeton d’accès refusé juste après qu’Aqara l’a renouvelé est « non lu », espacé (doublé jusqu’à une heure), jamais une fin d’autorisation ; pendant cet espacement, aucun renouvellement n’est demandé (une extinction part avec le jeton courant et est réessayée plus tard).

Dépannage​

  • « a refusé les clés du projet » : vérifiez App ID, Key ID, App Key et le serveur ; un projet pas encore approuvé est refusé aussi. Code 106 (signature) : vérifiez l’App Key, et le Key ID tel que la console l’affiche.
  • « Aqara a refusé la date de la requête » : l’horloge de l’hôte de Gladys est fausse.
  • « une autorisation refusée (restriction d’adresse IP du projet ?) » : les réglages IP du projet n’autorisent que d’autres adresses.

Paramètres de configuration​

Voici les paramètres demandés par Aqara dans son écran de configuration dans Gladys.

ParamètreTypeObligatoireDescription
Pour commencersectionNonLit les appareils de votre compte Aqara (capteurs, prises, lumières, rideaux derrière un hub M2, M3…) par l’API ouverte officielle d’Aqara, avec un projet développeur que vous créez sur developer.aqara.com. Éteindre n’est jamais bloqué. Positions de rideaux, serrures, caméras, vannes, portes de garage et chauffage restent en lecture seule. Non officielle, sans lien avec Aqara ; jamais testée avec un vrai appareil.
Serveur AqaraselectNonLe serveur de votre compte Aqara (celui choisi dans l’app Aqara Home).
Projet développeursectionNonSur developer.aqara.com, créez un projet (Console, Project Management) ; une fois approuvé, son détail donne l’App ID, et Key Management le Key ID et l’App Key.
App IDstringNon
Key IDstringNon
App KeysecretNonGardé par Gladys dans sa base, jamais réaffiché, utilisé seulement pour signer les requêtes envoyées à Aqara (la clé elle-même ne sort jamais).
AutorisationsectionNonSaisissez l’adresse e-mail ou le numéro de téléphone de votre compte Aqara et enregistrez. Cliquez ensuite sur « Envoyer le code de vérification » : Aqara envoie un code à ce compte (valable 10 minutes). Saisissez-le avec le bouton « Autoriser » : les deux jetons ci-dessous sont remplis par l’intégration. Un code n’est envoyé que sur votre clic.
Compte Aqara (e-mail ou téléphone)stringNon
Jeton d’accès (rempli par « Autoriser »)secretNonGardé par Gladys dans sa base, jamais réaffiché, envoyé seulement à Aqara.
Jeton de renouvellement (rempli par « Autoriser »)secretNonGardé par Gladys dans sa base, jamais réaffiché, envoyé seulement à Aqara.
Lectures et quotasectionNonChaque lecture coûte un appel par tranche de 50 valeurs (plus la liste des appareils toutes les 10 minutes). L’intégration cesse de lire quand le budget quotidien ci-dessous est épuisé (jour UTC) ; éteindre est toujours envoyé.
Intervalle de lecture (s)numberNonFréquence de lecture des valeurs : 60 s au moins.
Budget quotidien d’appels d’APInumberNonRéglez-le sous le quota de votre projet développeur.

Comment installer Aqara dans Gladys​

  1. Dans Gladys, ouvrez Intégrations : Aqara apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
  2. Cliquez sur Installer. Gladys télécharge l'image Docker (ghcr.io/lm1lc3n7/gladys-aqara: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).
  3. Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
  4. Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/LM1LC3N7/gladys-aqara.

Aqara 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​

Aqara 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.

Inscrivez-vous à la newsletter Gladys Assistant

Quelques emails par mois sur les nouveautés et l'actualité du projet. Envoyés par Pierre-Gilles Leymarie, le fondateur du projet. Désinscription possible à tout moment 🙂