Aller au contenu principal

Intégration domotique Ubiquiti airOS, gratuite et open source

Intégration Ubiquiti airOS pour Gladys Assistant

Radios Ubiquiti airMAX (airOS 8) : signal, débits, capacité, lien, redémarrage.

Voir sur GitHubToutes les intégrations

Les radios airMAX de Ubiquiti (NanoBeam, NanoStation, LiteBeam, PowerBeam, Rocket, LiteAP… sous airOS 8) dans Gladys, par l'API JSON de l'interface web locale de la radio. Pratique pour surveiller un lien sans fil vers une grange, un bureau au fond du jardin ou un voisin :

  • la radio devient un appareil Gladys (onglet Découverte) : lien sans fil établi (oui / non), stations connectées, signal et signal distant (dBm), bruit de fond, débits émis et reçus, capacités descendante et montante, distance du lien, fréquence, largeur de canal, charge CPU, mémoire utilisée, temps de fonctionnement, température (si la radio a un capteur), port LAN connecté et sa vitesse, mode sans fil, firmware ;
  • un bouton Redémarrer la radio, inactif tant que vous ne l'autorisez pas ;
  • deux déclencheurs de scène : Lien sans fil perdu et Lien sans fil revenu.

Sur un point d'accès avec plusieurs stations (PtMP), les signaux sont ceux de la station la plus faible. Sans station connectée, les signaux (et sur certaines radios les capacités) ne sont pas lus : Gladys garde leur dernière valeur, avec sa date. Lisez de préférence la radio du côté de Gladys : si la radio lue est celle qui devient injoignable, « lien perdu » ne peut pas se déclencher (la radio est alors affichée injoignable).

Cette intégration n'a jamais été testée avec une vraie radio. Cette première version a été portée depuis python-airos, la bibliothèque qu'utilise Home Assistant, et testée seulement contre une fausse radio. Dites sur le forum Gladys ce qui marche et ce qui ne marche pas, avec le modèle et la version d'airOS.

Intégration non officielle, sans lien avec Ubiquiti.

Avant de commencer​

  1. La radio doit être sous airOS 8 (affiché dans son interface web). airOS 6 et antérieurs ne sont pas pris en charge.
  2. Gladys a besoin d'un compte de l'interface web (ubnt par défaut). Son mot de passe est gardé par Gladys dans sa base, jamais réaffiché, et envoyé seulement à la radio.
  3. Ajoutez une intégration par radio (les deux bouts d'un lien si vous voulez les deux).

Réglages​

  • Adresse de la radio : son adresse IP ou son nom d'hôte, avec :port si son interface n'est pas sur 443. Le HTTP simple est refusé (airOS 8 sert du HTTPS).
  • Nom d'utilisateur, Mot de passe.
  • Empreinte du certificat (facultatif) : voir plus bas.
  • Rafraîchissement : 30 s, 1 min (par défaut), 2 ou 5 min. Le bouton de test, l'enregistrement du formulaire et un redémarrage de Gladys ou du conteneur ne lisent pas plus tôt (l'heure du dernier essai est gardée, écrite avant chaque lecture, au plus une fois par minute à partir du rafraîchissement de 1 min : à 30 s elle est écrite avant chaque lecture, donc un redémarrage ne lit jamais plus tôt). Un appui sur Redémarrer la radio fait sa propre lecture fraîche (avec une connexion si besoin), hors rafraîchissement.
  • Autoriser le redémarrage de la radio : désactivé par défaut.

Le certificat HTTPS​

La radio a un certificat auto-signé, qu'aucune autorité ne peut garantir. Gladys le vérifie par son empreinte SHA-256, juste après la négociation TLS et avant d'envoyer le mot de passe :

  • champ vide, à la première connexion : Gladys écrit le certificat rencontré dans son stockage, puis envoie le mot de passe. Si son stockage ne peut être ni lu ni écrit, rien n'est appris et rien n'est envoyé : saisissez l'empreinte (l'état affiche celle rencontrée) ;
  • ensuite, un autre certificat arrête tout (rien n'est envoyé) et l'état affiche son empreinte. Réenregistrer le formulaire ne change rien. Si vous avez remplacé ou réinitialisé la radio, saisissez dans Empreinte du certificat l'empreinte que montre votre navigateur pour la radio (cadenas, certificat, SHA-256) : elle devient celle de confiance. Si la radio en présente alors une autre, rien n'est envoyé et l'état affiche celle qu'elle présente. Vider le champ plus tard ne fait pas réapprendre de certificat.

Le redémarrage​

Le bouton Redémarrer la radio est un bouton, jamais un interrupteur : un « tout éteindre » d'un assistant vocal ou d'une scène ne l'atteint jamais. Un appui est refusé, rien n'est envoyé, dans ces cas :

  • Autoriser le redémarrage de la radio est désactivé (revérifié juste avant l'écriture de la requête) ;
  • la radio n'est pas connectée, Gladys est dans une pause demandée par la radio (HTTP 429 ou 5xx), l'identifiant ou le certificat a été refusé ;
  • un redémarrage a été envoyé il y a moins de 10 minutes (gardé au redémarrage), ou ce délai ne peut pas être écrit dans le stockage de l'intégration (/data) ;
  • un redémarrage est déjà en cours d'envoi ;
  • après un redémarrage de l'intégration, jusqu'à sa première lecture (au plus un intervalle de rafraîchissement), ou la configuration a été enregistrée pendant l'appui ;
  • la radio ne répond pas à la lecture faite juste avant en 2,5 s, ou une autre radio répond (autre MAC), ou sa MAC est illisible ou pas encore lue ;
  • la requête n'a pas pu être écrite dans les 3,5 s qui suivent l'appui.

Quand la requête a été écrite mais que la radio n'a pas répondu, Gladys dit « envoyé, sans réponse » : la radio redémarre peut-être. Le lien tombe 1 à 2 minutes ; l'état dit alors que la radio redémarre.

Erreurs​

  • Identifiants refusés : plus rien n'est envoyé tant que le nom d'utilisateur ou le mot de passe ne change pas ; le bouton Tester la connexion essaie une fois de plus. Gladys garde un marqueur de 8 bits du mot de passe refusé (commun à 1 mot de passe sur 256, jamais le mot de passe) : un nouveau mot de passe qui le partage est tenu pour refusé jusqu'à ce que le bouton de test l'essaie.
  • HTTP 429 ou 5xx : une pause de toutes les requêtes (1 min à 6 h), gardée au redémarrage.
  • Pas de réponse : nouvel essai après 1 minute, ou l'intervalle de rafraîchissement s'il est plus long, puis deux fois plus long à chaque fois, jusqu'à 30 minutes.
  • Une autre radio à l'adresse (autre MAC) : rien n'est publié ; enregistrez le formulaire pour la prendre comme la nouvelle.

Ni le mot de passe, ni la session, ni les adresses MAC ou IP des stations ne sont journalisés ou publiés. Le stockage garde l'empreinte du certificat, le marqueur de 8 bits ci-dessus et une empreinte salée de la MAC de la radio (pas la MAC en clair ; une MAC n'est pas un secret, la radio la diffuse).

Pas (encore) fait​

Un appareil par station d'un point d'accès, la déconnexion d'une station, la mise à jour du firmware, airOS 6, l'AirCube et les appareils UniFi : dites-le sur le forum si vous en avez besoin.

Paramètres de configuration​

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

ParamètreTypeObligatoireDescription
FonctionnementsectionNonGladys lit une radio Ubiquiti airMAX (NanoBeam, NanoStation, LiteBeam, PowerBeam, Rocket, LiteAP… sous airOS 8) par l'API JSON de son interface web locale, en HTTPS, avec un compte d'administration. La radio devient un appareil : lien sans fil établi, stations connectées, signal et signal distant, bruit de fond, débits émis et reçus, capacités descendante et montante, distance du lien, fréquence, largeur de canal, charge CPU, mémoire utilisée, temps de fonctionnement, température, port LAN, mode sans fil, firmware, et un bouton Redémarrer, inactif tant que vous ne l'autorisez pas plus bas. Déclencheurs de scène : lien sans fil perdu, lien sans fil revenu. airOS 6 et antérieurs ne sont pas pris en charge. Ajoutez une intégration par radio. Intégration non officielle, sans lien avec Ubiquiti.
Adresse de la radiostringOuiL'adresse IP (ou le nom d'hôte) de la radio sur votre réseau local, celle de son interface web, avec son port s'il n'est pas 443.
Nom d'utilisateurstringOuiUn compte de l'interface web de la radio (ubnt par défaut sur airOS).
Mot de passesecretOuiLe mot de passe de ce compte. Gardé par Gladys dans sa base, jamais réaffiché, envoyé seulement à la radio, sur une connexion dont le certificat a été vérifié avant.
Empreinte du certificat (facultatif)stringNonLa radio a un certificat HTTPS auto-signé. Vide : Gladys épingle le certificat rencontré à la première connexion (écrit dans son stockage avant l'envoi du mot de passe) puis refuse tout autre, en donnant son empreinte. Pour faire confiance à un nouveau certificat (radio remplacée ou réinitialisée), ou pour l'épingler vous-même, saisissez ici son empreinte SHA-256 (telle que votre navigateur l'affiche).
RafraîchissementselectOuiFréquence de lecture de la radio. Le bouton de test, l'enregistrement du formulaire ou un redémarrage ne lisent pas plus tôt ; un appui sur Redémarrer fait sa propre lecture fraîche.
CommandesectionNonLecture seule par défaut. La seule commande est le redémarrage, un bouton (jamais un interrupteur : un « tout éteindre » ne l'atteint jamais), refusé tant qu'il n'est pas autorisé ici, au plus un toutes les 10 minutes. Le lien tombe pendant le redémarrage (1 à 2 minutes).
Autoriser le redémarrage de la radiobooleanNonDésactivé : le bouton Redémarrer est refusé et rien n'est envoyé.

Comment installer Ubiquiti airOS dans Gladys​

  1. Dans Gladys, ouvrez Intégrations : Ubiquiti airOS 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-airos:0.1.2), 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-airos.

Ubiquiti airOS 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​

Ubiquiti airOS 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 🙂
Dernière mise à jour le