Aller au contenu principal

Intégration domotique Visual Crossing, gratuite et open source

Intégration Visual Crossing pour Gladys Assistant

Non officiel : météo, prévisions à 15 jours et alertes Visual Crossing, avec votre clé API.

Connecteur non officiel, sans lien avec Visual Crossing Corporation. Il fait de Visual Crossing le fournisseur météo de Gladys : conditions actuelles, prévisions sur 24 heures et 8 jours (Visual Crossing en donne 15, Gladys en garde 8), et les alertes en cours du lieu. Le widget météo, l'assistant et les déclencheurs de scène d'alerte météo de Gladys s'en servent directement.

Cette intégration n'a jamais été testée avec un vrai compte : elle est écrite d'après la documentation officielle de la Timeline Weather API de Visual Crossing. Les retours sont les bienvenus.

Ce qu'il faut​

  • Votre propre compte Visual Crossing et sa clé API (inscription sur visualcrossing.com, la clé est sur la page Account).
  • Gladys 5.1 ou plus récent.

Coûts​

Visual Crossing compte des enregistrements (records). Une requête de prévision (celle qu'envoie cette intégration) coûte 1 enregistrement, quels que soient ses jours, ses heures et ses alertes ; l'intégration lit le queryCost de chaque réponse et le compte.

  • Offre gratuite : 1 000 enregistrements par jour. Au-delà, Visual Crossing répond 429 jusqu'au lendemain.
  • Offre à l'usage (pay-as-you-go) : les enregistrements au-delà des gratuits sont facturés par Visual Crossing (0,0001 USD l'enregistrement au moment de l'écriture, voir les offres).
  • Autres offres : voir votre compte.

L'intégration a son propre plafond quotidien (500 enregistrements par défaut), compté avant chaque appel et gardé dans /data au redémarrage : atteint, plus rien n'est envoyé avant minuit UTC. Un appel qui a pu être facturé n'est pas réessayé : après un délai dépassé, une erreur réseau ou une 5xx, le lieu attend 15 minutes ; après une 401, la clé n'est plus utilisée. Avec la lecture par défaut toutes les 60 minutes, un lieu coûte au plus 24 enregistrements par jour.

Configuration​

ChampRôle
Clé APIGardée par Gladys dans sa base, jamais réaffichée, envoyée seulement à Visual Crossing. Elle n'apparaît ni dans les journaux, ni dans le statut, ni dans les erreurs, ni dans /data.
Alertes météoActives par défaut. Même coût (les alertes arrivent dans la même réponse).
Intervalle de lecture60 minutes par défaut (60 à 180). Un lieu est lu chez Visual Crossing au plus une fois par intervalle ; Gladys reçoit la copie gardée entre-temps.
Plafond quotidien500 enregistrements par défaut (10 à 100 000), par jour UTC. Visual Crossing compte tous les usages de votre clé dans le même compte : gardez de la marge pour vos autres usages.

Tester Visual Crossing fait un appel (les conditions actuelles à Greenwich, 1 enregistrement, aucune donnée personnelle) : il indique si la clé est acceptée et les enregistrements comptés aujourd'hui. Il fonctionne au plus une fois par minute, ni pendant une pause (après une 429, une erreur ou un délai dépassé), ni une fois le plafond atteint.

Rythme, pauses et erreurs​

  • Gladys demande la météo quand un tableau de bord l'affiche, quand l'assistant répond, et toutes les 30 minutes pour les alertes quand une scène utilise le déclencheur d'alerte météo. L'intégration répond avec sa copie tant qu'elle est plus récente que l'intervalle.
  • Un seul appel à la fois vers Visual Crossing, quel que soit le nombre de lieux.
  • HTTP 429 : pause aussi longue que le dit Retry-After (comparé à l'en-tête Date du serveur), entre 60 s et 6 heures ; sans l'en-tête, 60 s puis doublée jusqu'à 6 heures.
  • Délai dépassé (10 s), erreur réseau, erreur serveur, 403, réponse illisible ou trop grosse (plus de 1 Mo) : pause de 60 s pour tous les lieux (ou le Retry-After de la réponse, de 60 s à 1 heure), doublée à chaque échec jusqu'à 1 heure (le palier survit à un redémarrage et revient à zéro après un succès), et ce lieu n'est pas redemandé avant 15 minutes (l'appel en échec a pu être facturé).
  • HTTP 400 ou 404 : le lieu n'est pas servi ; seul ce lieu est retenu pendant un intervalle de lecture.
  • Gladys attend 15 s une réponse : un appel qui ne peut pas finir à temps ne part pas.
  • Une horloge qui saute en avant puis revient ne fige jamais le plafond : un compte rangé sous un jour au-delà de demain est gardé, par prudence, mais rangé sous aujourd'hui et remis à zéro au prochain minuit UTC.
  • Une requête qui n'a même pas pu être préparée (erreur locale avant l'envoi) ne compte aucun enregistrement, ne retient aucun lieu et ne met rien en pause.
  • Si le comptage d'un appel ne peut pas être écrit dans /data en 1 s, l'appel ne part pas (le plafond doit survivre à un redémarrage).
  • Pendant une pause ou une panne, Gladys reçoit la dernière copie si elle a moins de 4 heures, avec sa propre date (jamais présentée comme neuve) ; sinon une erreur, et Gladys passe à son fournisseur suivant.
  • La pause, les lieux retenus, le compteur et les copies sont gardés dans /data : un redémarrage ou une reconnexion ne déclenchent pas d'appel. Une configuration enregistrée demande à Gladys de relire la météo, servie par la copie tant qu'elle est plus récente que l'intervalle.

Clé refusée​

Un HTTP 401 est un refus de la clé (Visual Crossing : problème de clé, de compte ou d'abonnement) : plus aucune requête ne part avec elle, et elle n'est pas réessayée. /data ne garde qu'un octet d'une empreinte salée de la clé : rien qui permette de vérifier une supposition (une sur 256 correspond). Enregistrer une autre clé pendant que l'intégration tourne lève le refus aussitôt. Après un redémarrage, seul cet octet est connu : une nouvelle clé dont l'octet tombe pareil (1 chance sur 256) reste retenue jusqu'à un succès de Tester Visual Crossing, qui essaie même une clé refusée. Un 403 n'est pas pris pour un refus (il peut venir d'un proxy ou d'un pare-feu) : il met en pause.

Ce qui est envoyé à Visual Crossing​

Les coordonnées de la maison arrondies à 3 décimales (environ 100 m) et la clé API (dans l'adresse de la requête, comme Visual Crossing le demande ; cette adresse n'est jamais journalisée). Ni la langue ni le système d'unités ne sont envoyés : la réponse est demandée en métrique et convertie ici, un seul appel sert donc tous les utilisateurs. /data/state.json contient le compteur du jour, la pause, les lieux retenus, un octet marquant une clé refusée, et les dernières réponses. Les réponses ne contiennent pas de coordonnées, mais chacune est rangée sous une empreinte salée du lieu arrondi : avec le sel à côté, le lieu peut être retrouvé par force brute. /data reste sur votre Gladys.

Correspondances​

Icône Visual Crossing (jeu icons2)Gladys
clear-day, clear-nightclear
partly-cloudy-day/night / cloudypartly-cloudy / cloud
fog / windfog / wind
rain, showers-day/nightrain ; pouring dès 7,6 mm en une heure ; freezing-rain ou sleet selon le type
snow, snow-showers-day/nightsnow ; sleet quand pluie ou glace s'y mêlent
thunder-rain, thunder-showers-day/nightthunderstorm (snow-thunderstorm avec neige seule)
toute autre icôneunknown

Le jour ou la nuit viennent des heures de lever et de coucher du soleil, sinon de l'icône (-day/-night). Unités : le métrique est converti en m/s (vent) et km, ou en °F, mph, pouces et miles (US) ; la pression reste en hPa ; humidité, couverture nuageuse et probabilité de précipitation en pourcentage. Une valeur absente reste absente, jamais 0.

Alertes : Visual Crossing ne donne pas de niveau. Il est lu dans le titre : « watch », jaune ou modéré → moderate (même une « Extreme ... Watch ») ; rouge, extrême, urgence, avertissement de tornade ou d'ouragan → extreme ; orange, sévère ou « warning » → severe ; sinon → minor (l'alerte est gardée). Le phénomène (orage, vent, neige...) est lu dans le titre en anglais, français, allemand ou espagnol. Les alertes terminées selon l'horloge du serveur sont retirées.

Attribution​

Données météo fournies par Visual Crossing (https://www.visualcrossing.com/). Le widget météo de Gladys ne peut pas encore afficher d'attribution : elle figure sur l'écran de configuration et ici.

Statuts​

  • « Saisissez la clé API... » : rien n'est configuré.
  • « Configuration invalide : ... » : nomme les champs erronés (jamais leur valeur) ; rien n'est envoyé.
  • « Prêt », puis « Visual Crossing répond ».
  • « Visual Crossing a refusé cette clé API... », « a demandé de ralentir... », « n'a pas répondu correctement... », « Plafond quotidien atteint... ».
  • « /data/state.json est illisible » : relu toutes les 10 s, rien n'est envoyé en attendant (un fichier illisible n'est pas pris pour vide).
  • « La configuration n'a pas pu être lue » : nouvel essai après 5 s, puis doublé jusqu'à 5 minutes.

Paramètres de configuration​

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

ParamètreTypeObligatoireDescription
Visual Crossing dans GladyssectionNonConnecteur non officiel, sans lien avec Visual Crossing. Il fait de Visual Crossing le fournisseur météo de Gladys : conditions actuelles, 24 heures, 8 jours et les alertes données pour votre zone. Il faut votre propre compte Visual Crossing et sa clé API. L'offre gratuite inclut 1 000 enregistrements par jour ; une prévision coûte 1 enregistrement. Avec l'offre à l'usage, les enregistrements au-delà des gratuits sont facturés par Visual Crossing (0,0001 USD pièce au moment de l'écriture) : le plafond quotidien ci-dessous arrête les appels avant. Chaque lieu est lu au plus une fois par intervalle (une heure par défaut). Données météo fournies par Visual Crossing.
Clé APIsecretOuiLa clé de votre compte Visual Crossing (page Account). Gardée par Gladys dans sa base, jamais réaffichée, envoyée seulement à Visual Crossing.
Alertes météobooleanNonDemande à Visual Crossing les alertes en cours du lieu (même coût), affichées par le widget météo et utilisées par les déclencheurs de scène d'alerte météo de Gladys.
Intervalle de lecture (minutes)numberNonUn lieu est lu chez Visual Crossing au plus une fois par intervalle ; Gladys reçoit la copie gardée entre-temps. 60 minutes font au plus 24 enregistrements par jour et par lieu.
Plafond quotidien (enregistrements)numberNonEnregistrements permis par jour (UTC), comptés par cette intégration avant chaque appel et gardés au redémarrage. Atteint : aucun appel avant minuit UTC. Visual Crossing compte tous les usages de la clé dans le même compte.

Comment installer Visual Crossing dans Gladys​

  1. Dans Gladys, ouvrez Intégrations : Visual Crossing 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-visual-crossing: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-visual-crossing.

Visual Crossing 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​

Visual Crossing 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 🙂