RBgrid

Données en direct sans interrogation répétée

⚠️ Cette page concerne le firmware autonome du hub. Un hub qui exécute le package ESPHome n'a pas d'API REST, pas de WebSocket et pas de MQTT — c'est un appareil ESPHome, et Home Assistant lui parle par le panneau RBgrid et l'action rbgrid_cmd. Tout ce qui suit suppose que le hub sert sa propre application web. → Lancer-le dans Home Assistant

Le hub pousse. Ouvrez un seul WebSocket vers /ws-telemetry et les valeurs arrivent au fur et à mesure que le hub les produit — au lieu de les demander sans cesse et d'obtenir une copie toujours un peu périmée.

C'est ce qu'utilise l'application elle-même. Si vous construisez un tableau de bord, un flux Node-RED ou tout ce qui veut un chiffre en direct sur un écran, c'est ce transport ; pour tout ce qui veut un enregistrement plutôt qu'une valeur, utilisez l'historique via HTTP.

La liste des routes et la référence des champs en direct se trouvent dans la référence API générée, un fichier du dépôt, produit à partir du schéma du hub lui-même à chaque version. Cette page ne les répète pas : une liste de champs copiée à la main se périme discrètement, et une liste périmée est pire que pas de liste, parce qu'elle paraît crédible.

Entrer depuis un navigateur, sans mettre de jeton dans l'URL

Une adresse WebSocket ne transporte aucun en-tête ; la solution évidente serait donc de mettre le jeton dans la chaîne de requête — et c'est ainsi que des jetons finissent dans l'historique du navigateur, les journaux serveur et les captures d'écran.

Le hub vous offre une alternative :

  1. POST /api/v1/ws-ticket en HTTP, avec votre jeton.
  2. Vous obtenez un ticket : usage unique, valable 30 secondes.
  3. Ouvrez le socket avec le ticket.

Trente secondes est volontairement court, et l'usage unique signifie qu'un ticket capturé est déjà consommé. Demandez-en un par connexion — y compris à chaque reconnexion — plutôt que de le garder en réserve.

⚠️ Un ticket n'est pas une session. Il n'autorise que l'ouverture d'un seul socket. Si vous le mettez en cache, votre reconnexion échouera au pire moment, c'est-à-dire justement au moment où vous vous reconnectez : après un incident.

Pour un client côté serveur qui n'est pas un navigateur, ce mécanisme est inutile — envoyez le jeton de la manière habituelle.

Les lectures exigent le jeton de lecture dès que le hub a défini les deux jetons. → Settings

Démarrer et arrêter le flux

Le socket n'est pas un tuyau auquel on se contente de se raccorder. Il accepte trois messages :

Message Action
get_telemetry une trame, maintenant
start_telemetry commencer à pousser
stop_telemetry arrêter de pousser, garder le socket

Arrêtez lorsque votre page est masquée et redémarrez lorsqu'elle est affichée. Un onglet de navigateur laissé ouvert toute la nuit avec un flux actif coûte du travail réel au hub, pour le bénéfice de personne, et le hub sert aussi l'application, la connexion au broker et la boucle de mesure.

Un seul socket par client. Plusieurs sockets depuis une même page est un bogue qui ressemble à un problème de performance : chacun est un flux que le hub doit remplir.

Quelle quantité le hub envoie

La télémétrie a deux profils, lean et full, réglés sur le hub (/api/system/telemetry-config). Lean est la trame la plus petite ; full contient tout ce que le hub peut signaler. La trame a aussi un plafond de taille que le hub ne dépasse pas.

Choisissez lean, sauf si vous utilisez des champs que seul full contient. Un tableau de bord qui affiche la puissance et le coût par point n'a pas besoin de full, et la différence représente des octets sur votre réseau toutes les quelques secondes, aussi longtemps que le client fonctionne.

Lire ce qui arrive

Trois choses à faire, et les deux premières sont celles que les intégrations oublient :

Conservez la qualité. Les trames en direct comme les enregistrements disent ce que le hub pense de ses propres chiffres : partiel, estimé, recalculé, issu d'une coupure. Un tableau de bord qui abandonne ces indications ne peut pas expliquer plus tard un chiffre étrange, et l'explication se trouve généralement justement dans cette indication. → History

Faites confiance à l'heure du hub, pas à la vôtre. Les périodes, les jours et les zones tarifaires sont placés par l'horloge et le fuseau horaire du hub. Un client qui réestampille à la réception ne sera pas d'accord avec le hub sur l'heure à laquelle appartient une mesure — et ce désaccord est invisible jusqu'au changement de jour. → Time

Traitez un champ manquant comme manquant, pas comme zéro. Un point sans module de tension ne signale aucune énergie plutôt qu'une énergie calculée à partir d'une tension nominale ; le hub refuse de l'inventer, et vous devriez faire de même.

Reconnexion

Le socket finira par se fermer : le hub redémarre pour une mise à jour, le Wi-Fi tombe, un routeur redémarre. Prévoyez-le plutôt que d'en être surpris :

  • Demandez un nouveau ticket à chaque tentative. L'ancien est consommé ou expiré.

  • Temporisez entre les tentatives, et continuez d'espacer. Un client qui réessaie en boucle serrée contre un hub en cours de redémarrage arrive exactement au moment où il est le moins capable de répondre.

  • Renvoyez start_telemetry. Un nouveau socket ne diffuse rien tant que vous ne le demandez pas.

  • Supposez que vous avez manqué des choses. Le flux contient des valeurs en direct, pas une file d'attente ; rien n'est rejoué. Si ce que vous avez manqué compte, c'est dans l'historique, qui est conservé, et dans le journal des prix, conservé pendant 40 jours.

Quand utiliser autre chose

Vous voulez Utilisez
un chiffre en direct sur un écran ceci
Home Assistant, ou tout ce qui est déjà sur un broker MQTT — découverte incluse
« l'énergie est-elle bon marché maintenant ? » la notification de prix retenue sur MQTT : un état, pas un flux → Knowing when energy is cheapest
les périodes closes, les coûts, un mois de données HTTP ou export.csv

Pour la notification de prix en particulier, ne la construisez pas sur ce socket. C'est un état que le hub republie à chaque limite de période de 15 minutes et chaque fois que quelque chose change, et sur MQTT il est retenu — donc un client qui se connecte tard reçoit tout de même l'état actuel. Un client WebSocket qui était hors ligne pendant une transition a simplement manqué celle-ci.

Quand ça ne fonctionne pas : que vérifier

Le socket s'ouvre puis se ferme aussitôt. Le ticket a déjà été utilisé ou date de plus de 30 secondes. Demandez-en un par connexion.

Le socket reste ouvert et rien n'arrive. Aucun start_telemetry n'a été envoyé. Un socket neuf reste silencieux tant qu'on ne le lui demande pas.

Ça a marché, puis ça s'est arrêté après une mise à jour du hub. Le hub a redémarré et le socket a suivi. Reconnectez-vous avec un nouveau ticket et relancez le flux.

Les valeurs arrivent mais pas les montants. Aucun tarif n'est défini, ou le hub utilise encore le plan d'exemple d'usine. → Tariffs

Un point envoie du courant mais jamais d'énergie. Il n'a pas de tension derrière lui. Le hub affiche la puissance en direct comme une estimation à partir de la tension nominale et n'enregistre aucune énergie, par conception. → Remote nodes

Mes totaux horaires diffèrent de ceux de l'application d'une heure. Vous horodatez les lectures avec votre propre horloge. C'est le hub qui décide dans quelle heure se trouve une lecture. → Time

Un client navigateur est refusé alors qu'un script sur la même machine fonctionne. Le navigateur applique des règles d'origine que le script n'a pas. Autorisez votre origine sur le hub. → Talking to the hub over HTTP

⚠️ Pour tout travail à l'intérieur d'un tableau électrique, faites appel à un électricien qualifié.