Nœuds distants (ESP-NOW)
Vue d'ensemble
Un nœud distant est une petite carte ESP32 équipée de ses propres modules rbAmp. Il mesure là où un câble I2C venant du hub ne peut pas aller : un garage, une pompe de piscine, un chauffe-eau au sous-sol, un sous-tableau dans une dépendance. Il envoie ses mesures au hub par radio, via ESP-NOW. Le nœud n'est pas sur votre réseau Wi-Fi et n'a pas d'adresse propre : il ne communique qu'avec son hub. Ses voies deviennent des points ordinaires du hub, avec des valeurs en direct, un historique et un coût comme tout autre point.
Cette page est la documentation complète des nœuds : la carte et les modules, le câblage, le flashage, l'appairage, la façon dont un nœud gère l'heure et l'énergie, ce que l'application affiche, l'API et les topics MQTT du hub, et que faire lorsque quelque chose ne va pas. Les nœuds distants exigent le firmware du hub v1.1.7 ou ultérieur et l'application web 1.1.7 ou ultérieure. Sur un hub équipé d'un firmware plus ancien, l'application n'affiche aucune section Nodes ; le message « Remote nodes are not available in this hub firmware. » n'apparaît que pour un hub dont l'image firmware ne peut pas exécuter les nœuds.
Un nœud est un émetteur. Il n'a ni écran, ni page web, ni historique que vous pouvez lire, et il ne se met pas à jour par voie hertzienne : vous le flashez par USB. À partir du firmware 1.5, il conserve les périodes de 15 minutes terminées dans sa propre mémoire flash tant que le hub ne les a pas reçues — c'est une file d'attente, et non un enregistrement que vous pouvez ouvrir. Le hub fait le reste.
Pour toute intervention à l'intérieur d'un tableau électrique, faites appel à un électricien qualifié.
Ce qu'il vous faut
| Requirement | |
|---|---|
| Carte du nœud | Un module ESP32 d'origine avec 4 Mo de flash. La PSRAM n'est pas nécessaire. Sur la v1.1.7, le firmware du nœud n'est compilé et testé que pour l'ESP32 d'origine : les cartes ESP32-S2, S3 et C3 ne sont ni compilées ni testées. |
| Modules rbAmp sur le nœud | Jusqu'à trois modules sur le bus I2C du nœud, aux adresses 0x50, 0x51 et 0x52 (réglage propre au module) ; SDA est sur GPIO 25 et SCL sur GPIO 26. Le hub utilise jusqu'à quatre voies de courant par nœud. |
| Une entrée de tension sur le nœud | Sur la v1.1.7, un nœud n'enregistre de l'énergie que lorsqu'un de ses modules mesure la tension. Un module de courant seul sur un nœud donne le courant en direct, mais aucune période de 15 minutes, donc pas d'historique ni de coût. Installez un jeu rbAmp monophasé avec une entrée de tension. |
| Phases | Sur la v1.1.7, un nœud ne mesure que des points monophasés. Il n'y a ni regroupement de phases sur un nœud, ni « use as the three-phase input » : cela concerne un module du hub. Un STD-U3I3 sur un nœud n'est pas testé. |
| Le hub | Firmware v1.1.7 ou ultérieur, connecté à votre Wi-Fi. La radio du hub pour les nœuds fonctionne sur le même canal que votre routeur ; un hub sans Wi-Fi ne peut pas faire tourner de nœuds. Un hub accepte jusqu'à six nœuds. |
| Emplacements d'historique | Les points des nœuds partagent les 12 emplacements d'historique existants du hub avec ses propres points ; ils ne s'y ajoutent pas. La section Nodes affiche « History: used of 12 points in use » avant l'appairage. |
| Un ordinateur avec USB | Pour flasher le nœud, et pour chaque mise à jour ultérieure du firmware du nœud. |
| Pinces de courant | Comme pour un module du hub ; le modèle de pince est réglé par voie depuis le hub (voir Node settings). |
Câbler le nœud
Un nœud se câble comme un petit hub : ses modules rbAmp sont sur le bus I2C du nœud, et les pinces de courant se posent sur les modules.
- I2C : quatre fils entre la carte ESP32 et les modules, SDA vers GPIO 25, SCL vers GPIO 26, GND et 3.3 V. Les adresses de module
0x50,0x51,0x52se règlent sur les modules ; le nœud lit celles qui sont présentes au démarrage, jusqu'à trois. Le bus est tiré vers le haut par les résistances embarquées des modules ; avec jusqu'à trois modules sur des câbles courts, laissez-les en l'état. La longueur de câble et les résistances de tirage pour les autres cas figurent dans le guide de câblage rbAmp, comme pour les modules du hub. - Entrée de tension : sur la v1.1.7, un module du nœud doit avoir son entrée de tension raccordée au réseau qu'il mesure ; sans elle, le nœud a le courant en direct mais n'enregistre aucune énergie (voir What you need). L'entrée de tension donne aussi au nœud le sens de chaque courant, import ou export.
- Pinces : une par voie de courant, sur le conducteur que vous voulez mesurer, la flèche orientée comme l'indique la documentation du module rbAmp. Le modèle de pince se règle par voie depuis le hub (voir Node settings) ; un mauvais modèle fausse l'échelle des mesures.
- Alimentation : l'alimentation habituelle de la carte ESP32, par exemple son port USB ou une alimentation 5 V sur l'entrée de la carte. Le nœud n'a ni batterie ni maintien : une coupure de courant l'arrête, et l'énergie de la période en cours est perdue.
- Emplacement : là où il vivra. Un nœud n'a pas besoin d'être près du hub pour être appairé ; la liaison est vérifiée là où il se trouve (voir Checking the link). Évitez, lorsque c'est possible, les boîtiers métalliques entre le nœud et le hub.
Pour toute intervention à l'intérieur d'un tableau électrique, faites appel à un électricien qualifié.
Flasher le firmware du nœud
Le firmware du nœud est publié avec chaque version du hub sur la page RBgrid Releases de GitHub : rbgrid-node_vX.Y.Z.bin (l'application seule) et rbgrid-node_vX.Y.Z_full.zip (chargeur de démarrage, table de partitions et application). Utilisez la version qui correspond à votre hub, ou une version plus récente.
La carte étant en mode téléchargement et esptool installé (pip install esptool), écrivez le jeu complet :
python -m esptool --chip esp32 -p <PORT> -b 460800 write_flash 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 rbgrid-node_vX.Y.Z.bin
⚠️ Mettre à jour un nœud vers le firmware 1.5 écrit les trois fichiers, et pas seulement l'application. La 1.5 ajoute la partition flash où vivent les périodes conservées. Un nœud auquel on ne donne que la nouvelle application fonctionne en 1.5 sans endroit où les garder, et retombe sur huit périodes en mémoire, sans que la carte ne le signale. Écrire les trois fichiers est aussi ce qu'il faut pour toute mise à jour ultérieure : cela ne coûte rien, et un nœud appairé sous 1.4 n'a pas besoin d'être appairé à nouveau.
Pour compiler le firmware vous-même, et connaître les broches à modifier si votre carte câble l'I2C autrement, voir node/README.md dans le dépôt RBgrid.
Le nœud n'a besoin ni de fichier de clé ni de réglage de canal. Il reçoit sa clé du hub lorsque vous l'appairez, et il trouve seul le canal du hub.
Compiler vous-même le firmware du nœud
Les sources se trouvent dans le dossier node/ du dépôt RBgrid, sous la même licence que le firmware du hub. Il se compile avec ESP-IDF 5.5.1 (5.4.1 se compile aussi) :
cd node
idf.py set-target esp32
idf.py build
idf.py -p <PORT> flash
La bibliothèque rbAmp est récupérée au moment de la compilation (dependencies.lock fixe sa version). Si votre carte câble l'I2C sur d'autres broches, compilez avec -DRBN_I2C_SDA=<n> -DRBN_I2C_SCL=<n>. Aucun fichier de clé n'est nécessaire. Les variantes de développement présentes dans les sources (RBN_ROLE_MASTER, RBN_FREERUN, RBN_OUTPUT_NODE) ne font pas partie de la version publiée et ne sont pas prises en charge.
Appairer un nœud
Les nœuds se gèrent dans Management → Points, dans la section Remote nodes (ESP-NOW). L'en-tête affiche « n of 6 nodes » et l'état de la radio pour les nœuds, « radio on » ou « radio off ». Sur un hub capable de faire tourner des nœuds, la section se trouve en haut de la page, au-dessus de rbAmp modules, et l'assistant de configuration propose une étape facultative ESP-NOW nodes (« Step 5 of 8 », après Sensors et avant Tariff).
- Placez le nœud là où il vivra, avec ses modules et ses pinces installés, mais laissez-le hors tension.
- Dans l'application, choisissez le Pairing time (en minutes) et appuyez sur Pair a node. La section affiche : « Power the node up now. It shows up below in a few seconds. » et compte à rebours : « Waiting for a node… time left ». Stop pairing ferme la fenêtre plus tôt.
- Mettez le nœud sous tension (ou réinitialisez-le). Il parcourt les canaux Wi-Fi à la recherche du hub, échange les clés avec lui et apparaît dans la liste, marqué new. Ses points sont ajoutés immédiatement : « Paired in this window: n. Their points are already added; no restart needed. »

⚠️ Tant que la fenêtre d'appairage est ouverte, tout nœud RBgrid à portée qui le demande est appairé. Il n'y a pas de code PIN. Cela comprend un nœud appartenant à quelqu'un d'autre dont le propre hub s'est tu : un nœud appairé qui ne reçoit aucune réponse pendant environ 150 secondes se met seul à demander un appairage. N'ouvrez la fenêtre que lorsque vous êtes sur le point de mettre un nœud sous tension, gardez-la brève, et fermez-la avec Stop pairing dès que votre nœud figure dans la liste ; vérifiez ensuite que la liste ne contient que les nœuds attendus.
Les clés sont conservées sur le nœud et sur le hub. Après un redémarrage, ou après une mise hors tension de la radio, le nœud se reconnecte seul ; vous ne l'appairez qu'une fois.
Avant d'appairer, vérifiez les deux lignes de capacité de la section : « n of 6 nodes » (lorsque le hub est plein, le bouton est remplacé par « The hub takes up to 6 nodes. Remove one to pair another. ») et « History: used of 12 points in use. Points beyond 12 show live values only. » (ou « History: all 12 points are in use. A new node's points will show live values only. »). Si la radio est éteinte, la section indique « Turn the radio for nodes on to pair one. »
Chaque nœud apporte jusqu'à quatre points. Ils portent le nom du nœud et de ses voies ; renommez-les et donnez-leur des rôles sur leurs propres pages, comme tout autre point (voir Points). Les points de nœud ne peuvent pas être liés ou déliés à la main : une voie désactivée dans les réglages du nœud cesse de mesurer, et supprimer le nœud supprime ses points.
La carte du nœud

Chaque nœud appairé a une carte dans la section.
| On the card | What it means |
|---|---|
| online / offline | Le hub a entendu le nœud dans les 15 dernières secondes, ou non. Un nœud désactivé (voir ci-dessous) affiche off. |
| new | Appairé dans la fenêtre d'appairage en cours. |
| Last heard | « now », « n s ago », « n min ago », « n h ago », ou « not heard since the hub started ». |
| Signal | La puissance du dernier trame du nœud, en dBm, telle que la radio du hub l'a perçue. |
| Lost packets, last minute | La part des balises temporelles du hub que le nœud a manquées sur la dernière minute, en pourcentage. Affiche « measuring (1 min) » tant qu'une minute complète ne s'est pas écoulée. |
| Clock sync | La précision avec laquelle l'horloge du nœud suit celle du hub : « ±n µs · n ppm ». |
| Firmware | La version du firmware du nœud, une fois que le nœud l'a signalée. |
| Period | « 15 min ». La période est fixe ; la boîte de réglages le précise : « Energy records: every 15 min, fixed. » |
| Waiting to send | Lorsque le hub le signale : le nombre de périodes de 15 minutes terminées que le nœud garde parce que le hub était hors de portée (voir How a node keeps time and energy). Le firmware du hub v1.1.7 ne le signale pas, donc la ligne n'apparaît pas là. |
| Channel n | Chaque voie de courant du nœud : le point qu'elle alimente (son nom, un lien vers la page du point ; « Point key » tant que le point n'a pas de nom) et son état, « receiving », « no data » ou « off (Settings) ». |
| settings not applied yet / settings not applied | Les réglages ont été envoyés au nœud, qui ne les a pas encore confirmés, ou qui les a refusés. |
| Signal, lost packets and clock sync missing | Un nœud non entendu depuis le démarrage du hub n'a aucune de ces valeurs : la carte omet les trois lignes et Last heard affiche « not heard since the hub started ». Elles apparaissent avec la première trame du nœud. |
La carte comporte trois boutons : Settings, Turn off / Turn on, et Delete.

Réglages du nœud
Settings ouvre « Node mac: settings ». Pour chaque voie, il affiche Channel n measures (activée ou désactivée) et Current clamp, le modèle de pince monté sur cette voie. « Pick the clamp actually fitted to each channel: a wrong one scales its readings wrongly. A channel turned off stops measuring. » Au moins une voie doit rester activée.
Send to the node envoie les réglages par le hub : « Sent. The node applies the settings on its next contact; the card shows «settings not applied yet» until it confirms. » Si le nœud est hors ligne, le hub conserve les réglages et les transmet à son retour (« The node is offline. It takes the settings when it's back. »).
La période d'énergie d'un nœud est fixée à 15 minutes (« Energy records: every 15 min, fixed. ») ; elle ne peut pas être modifiée.
Désactiver et réactiver un nœud
Turn off garde le nœud appairé mais fait jeter ses données par le hub. L'application demande d'abord : « The hub discards the node's data while it's off: that energy won't be in History or the totals, and turning it back on doesn't bring it back. To pause a node and keep its energy, leave it on. » Désactivé, la carte affiche off, et ses points n'affichent plus de valeurs en direct. Turn on reprend.
Utilisez-le lorsqu'un nœud mesure quelque chose que vous ne voulez pas compter pendant un moment. Pour arrêter un nœud définitivement, supprimez-le.
La radio pour les nœuds
La ligne Radio for nodes dans l'en-tête de la section affiche l'un de trois états :
- « On, channel n: the same as your Wi-Fi router's. » La radio du hub pour les nœuds est active. Elle fonctionne sur le canal Wi-Fi du hub, que votre routeur choisit ; si le routeur passe sur un autre canal, le hub et ses nœuds suivent.
- « Starts by itself when a node is paired (factory setting). » Rien ne tourne encore ; la radio démarre avec le premier appairage ou lorsqu'un nœud est déjà appairé.
- « Off. Nodes can't send data. » Vous l'avez désactivée.
La désactivation demande d'abord : « The nodes stop sending live values. They keep their 15-minute energy records and send them when the radio is on again (up to 2 hours on node firmware 1.4, about 5 days on 1.5). The hub remembers this after a restart. » Chaque nœud passe hors ligne immédiatement. Les valeurs en direct de cette période ne sont pas conservées ; les enregistrements le sont, tant que le firmware du nœud peut les garder.
Supprimer un nœud
Delete demande « Remove node mac? » : « The node and its points (channels: n) are removed, with their stored history, for good. Download the history first in History (CSV) if you need it. To use the node again, pair it again. »
⚠️ Supprimer un nœud efface ses points et tout leur historique enregistré. Si vous pourriez avoir besoin des enregistrements, téléchargez-les d'abord dans History.
Le hub cesse immédiatement d'accepter les données du nœud et le confirme : « Node removed, with its points: n. » Pour utiliser à nouveau le nœud, appairez-le de nouveau : ouvrez une fenêtre d'appairage et réinitialisez le nœud (ou attendez environ 2½ minutes : un nœud qui ne reçoit aucune réponse de son hub pendant 150 secondes se met seul à demander un appairage).
Déplacer un nœud vers un autre hub
Un nœud appairé continue de solliciter son hub ; une fois qu'il n'a eu aucune réponse pendant 150 secondes, il se marque comme non appairé et demande à nouveau un appairage, et après une réinitialisation il le fait immédiatement. Déplacer un nœud vers un autre hub, ou remettre en service un nœud d'occasion, est donc un appairage :
- Delete le nœud sur l'ancien hub (si vous y avez accès).
- Ouvrez une fenêtre d'appairage sur le nouveau hub et réinitialisez le nœud (ou attendez environ 2½ minutes). Le nœud prend la clé du nouveau hub.
Effacer d'abord la flash du nœud (python -m esptool --chip esp32 -p <PORT> erase_flash, puis flasher de nouveau le firmware) est facultatif : c'est un démarrage propre, et non une obligation.
Comment un nœud gère l'heure et l'énergie
- Horloge. Le hub est l'horloge. Le nœud demande l'heure toutes les 5 secondes tant qu'il ne l'a pas, puis toutes les minutes, et tient son propre minuteur entre-temps. La ligne Clock sync de la carte indique avec quelle précision il suit.
- Les valeurs en direct sont envoyées environ une fois par seconde et affichées sur les points du nœud. Elles ne sont pas enregistrées.
- L'énergie est enregistrée par périodes de 15 minutes, que le nœud clôt selon sa propre horloge, calée sur les limites de 15 minutes du hub, avec l'énergie des compteurs propres à ses modules. Lorsque la zone tarifaire change, le hub demande à chaque nœud de clore sa période à cet instant également, afin que le coût par zone soit exact.
- Une période atteint le hub, ou elle est conservée. Le nœud envoie une période terminée jusqu'à ce que le hub confirme l'avoir enregistrée ; les enregistrements survivent donc mieux à une liaison faible que la vue en direct. Le hub reconnaît une période qu'il possède déjà et ne la compte jamais deux fois.
- Hors de portée. Le nœud continue de clore ses périodes à l'heure et garde les périodes terminées jusqu'à ce que le hub les confirme. Lorsque la liaison revient, elles arrivent ensemble et sont classées et valorisées selon l'heure de leur mesure, et non selon l'heure de leur arrivée. La quantité qu'il peut garder dépend du firmware du nœud, et non du hub :
- Le firmware du nœud 1.5 les écrit dans sa propre flash : environ cinq jours de périodes, qui survivent à une coupure de courant du nœud.
- Le firmware du nœud 1.4 en garde huit (environ deux heures) en RAM ; une neuvième chasse la plus ancienne, et une coupure de courant du nœud fait perdre les périodes conservées ainsi que la période en cours.
Dans les deux cas, lorsque la réserve est pleine, la période la plus ancienne disparaît, et le nœud le consigne dans son journal.
- Un nœud qui démarre sans son hub ne clôt aucune période tant qu'il n'a pas entendu le hub une fois. L'énergie n'est pas perdue : sur la v1.1.7, le premier enregistrement après un démarrage couvre tout ce qui s'est passé depuis le démarrage du nœud jusqu'à la fin de sa première période complète de 15 minutes ; cette période peut donc paraître plus élevée que la charge réelle.
Vérifier la liaison
Le firmware n'a aucun seuil de réussite pour le signal ou les paquets perdus, et cette page n'en donne aucun ; le nœud est soit fiable à son emplacement, soit il ne l'est pas. Le test honnête est comportemental :
- Appairez le nœud à son emplacement définitif, avec sa charge réellement en marche.
- Surveillez la carte pendant une dizaine de minutes : le nœud doit rester online, Lost packets, last minute doit rester à 0, et Last heard doit rester à « now » ou à quelques secondes.
- Si les paquets perdus dépassent zéro, ou si le nœud bascule entre en ligne et hors ligne, la liaison est marginale. Déplacez un peu le nœud, ou le hub, et surveillez à nouveau.
Deux seuils existent dans le firmware, et ce sont les seuls : un nœud est offline après 15 secondes sans trame (le hub publie node_offline et node_online sur MQTT), et un nœud qui n'entend aucune balise pendant 8 secondes relance la recherche du canal du hub (c'est ainsi qu'il suit un routeur qui change de canal ; aucun redémarrage n'est nécessaire).
Une liaison faible se voit par des paquets perdus supérieurs à 0 et des trous dans les valeurs en direct pendant que les enregistrements continuent d'arriver ; une liaison pire fait clignoter le nœud. Un nœud hors de portée et un nœud privé de courant se ressemblent pour l'application et pour l'API. Seul l'historique de la carte avant la coupure permet de les distinguer : une liaison faible dérive d'abord (pertes croissantes, signal en baisse, clignotement), une coupure de courant est nette.
Savoir plus tard qu'un nœud s'est tu
La réserve de cinq jours ne sert qu'à condition de remarquer le problème dans les cinq jours.
À partir du firmware v1.2.0, le hub le consigne. Un nœud qui se tait et un nœud qui revient sont des lignes du journal du hub — espnow: node <MAC> offline et … online — de sorte qu'un nœud devenu silencieux pendant votre absence laisse une trace que vous retrouvez ensuite, avec son heure. → Events
Sur le firmware v1.1.8, rien dans l'application ne vient vous chercher : un nœud qui cesse de transmettre est affiché sur sa carte et dans la liste des Nodes, et nulle part ailleurs. Il n'y a aucune entrée dans le Journal de l'application et aucun élément dans Needs attention — sur ce firmware, le hub n'écrit la ligne que dans son propre journal série.
Sur aucun des deux firmwares, l'application ne déclenche d'alarme : le journal est un enregistrement à consulter, et non une notification qui vous parvient. Pour cela, utilisez Home Assistant.
Avec Home Assistant, vous disposez d'une véritable alarme, et elle ne coûte qu'une automatisation. Le hub publie une entité de connectivité Online par nœud via MQTT discovery, comme sous-appareil du hub, et elle suit le statut conservé du nœud. Automatisez sur le passage de cette entité à l'état éteint, et vous serez prévenu dans la minute. La même transition est publiée comme un événement node_offline sur le topic d'événements du hub, si vous préférez suivre les événements.
Sans MQTT, la carte est tout ce qui existe. Ouvrez de temps en temps la section Nodes — ou jetez un œil aux points du nœud dans History, où un nœud silencieux laisse un trou qui grandit.
Ce qu'est réellement la transition, pour que vous puissiez régler la patience de l'automatisation :
- le front se déclenche après 15 secondes sans trame en direct — le même seuil que celui utilisé par la carte, et un nœud envoie environ une trame par seconde ;
- il n'y a aucun anti-rebond : chaque interruption de plus de 15 s produit une paire hors ligne/en ligne, et les interruptions plus courtes ne produisent rien. Une liaison marginale vous donne une poignée de paires, pas des centaines ;
- le topic de statut est actualisé une fois par minute avec le signal et les pertes, sous forme d'état et non d'événement — un tableau de bord qui le lit n'est donc jamais en retard de plus d'une minute.
Totaux et reliquat « non mesuré »
Le total de la maison ne peut pas être compté deux fois : les totaux système sont pris à la frontière du réseau, à partir du seul point d'entrée. Les points de charge, sur le hub ou sur un nœud, ne s'y ajoutent jamais.
Le reliquat unmetered de l'Overview, lui, le peut. Il correspond à l'entrée moins la somme de tous les points de ligne, et les points de nœud sont des points de ligne. Si vous mesurez un sous-tableau sur un nœud et une charge à l'intérieur de ce sous-tableau sur une autre voie, cette charge est soustraite deux fois, et le reliquat peut devenir négatif.
À partir du firmware v1.1.8, vous pouvez le signaler au hub : marquez le point intérieur comme mesuré à l'intérieur du point extérieur, et il cesse d'être soustrait une seconde fois. C'est la bonne réponse pour une alimentation d'atelier ou de garage mesurée sur un nœud, avec ses charges mesurées en aval — vous conservez les deux chiffres, et le reliquat garde un sens. Cela ne change rien à la mesure ni au total de la maison.
Le réglage se trouve dans Management → Points → le point → Point setup → Point settings → Measured inside, où None: a line of its own est la valeur par défaut. La liste exclut l'entrée, le bus de tension, le point lui-même et tout ce qui est déjà à l'intérieur ; un choix que le hub refuse affiche « The hub refused that choice: the point is gone, is an input, or is already inside this one. Pick another. » → Points
⚠️ Cela vaut pour un niveau. B à l'intérieur de A est compté une fois. Lorsqu'une chaîne va plus loin — C à l'intérieur de B à l'intérieur de A — et que le point intermédiaire n'est pas affiché, certaines vues peuvent encore compter le point le plus interne deux fois.
Sur la v1.1.7, ce réglage n'existait pas, et le conseil était de mesurer soit le sous-tableau, soit les charges qu'il contient, mais pas les deux. Le total de la maison n'est dans les deux cas pas affecté : les totaux système sont pris à l'entrée.
Où les nœuds apparaissent ailleurs
- Points : les voies d'un nœud sont des points comme les autres, avec leurs propres pages, rôles et noms (voir Points).
- History et Economics : par point, comme pour tout point ; les points de nœud partagent les 12 emplacements d'historique (voir History).
- Events : le journal du hub enregistre l'appairage d'un nœud, les réglages qu'il confirme, et des lignes
FAILpour les trames ou enregistrements que le hub n'a pas pu compter. La mise hors ligne d'un nœud ou son retour n'est pas dans le journal — ils sont publiés sur MQTT et affichés sur la carte du nœud (voir Events). - MQTT : le hub publie un statut conservé par nœud sur
rbgrid/<mac>/node/<NODEMAC>/status(online, signal, paquets perdus, dernier signal reçu), actualisé chaque minute, et les événements de nœud surrbgrid/<mac>/event; les mêmes actions sur les nœuds sont disponibles par le canal de commandes (voir MQTT broker). - Home Assistant : un appareil par nœud, avec un capteur Online et un capteur Signal, par discovery. Les points du nœud apparaissent comme des points locaux.
- L'API du hub :
GET /api/v1/espnowliste l'état de la radio et chaque nœud avec sa santé ;POST /api/v1/espnowexécute les mêmes actions que l'application (voir ci-dessous).
L'API du hub
Tout ce que l'application fait avec les nœuds passe par un seul endpoint du hub, que vous pouvez utiliser vous-même.
GET /api/v1/espnow (le jeton de lecture, comme pour les autres lectures) renvoie la radio et le registre :
| Field | Meaning |
|---|---|
running, enabled |
la radio est active ; enabled vaut auto (démarre seule lorsqu'un nœud est appairé), on ou off |
keys, key_source |
true sur chaque image de hub à partir de la v1.1.7, et l'origine de la clé du hub (generated : créée par ce hub la première fois que la radio a démarré). Un hub sans keys ne peut pas faire tourner de nœuds |
max_nodes, max_channels_per_node |
6 et 4 |
channel |
le canal radio, celui du routeur Wi-Fi |
pairing_open, pairing_left_s, paired_count |
la fenêtre d'appairage, les secondes restantes, le nombre de nœuds appairés |
beacons_sent, rt_recv, stats_recv, periods_recv, periods_injected, periods_dropped, periods_dup |
compteurs depuis le démarrage du hub : balises temporelles envoyées, trames en direct et trames de période reçues, périodes enregistrées, abandonnées, et reconnues comme répétitions |
nodes[] |
par nœud : mac, online, disabled, last_seen_s, rssi_dbm, sync{ resid_sd_us, skew_ppm, fits, loss_pct }, channels[{ ch, ct_code, unit_id, present }], config_state (none, pending, applied, failed), config[], period_s, fw. Un nœud non entendu depuis le démarrage du hub n'a ni last_seen_s ni sync{} |
POST /api/v1/espnow (le jeton admin) avec { "action": … } :
action |
Fields | What it does |
|---|---|---|
hub_on / hub_off |
— | activer ou désactiver la radio pour les nœuds (conservé à travers les redémarrages) ; off marque immédiatement chaque nœud hors ligne |
pair |
seconds 10–600 |
ouvre la fenêtre d'appairage ; 409 ESPNOW_DISABLED tant que la radio est éteinte |
pair_cancel |
— | la ferme plus tôt |
configure |
mac, config: { channels: [ { ch, enabled, ct_code } ] } |
réglages du nœud ; le hub renvoie jusqu'à ce que le nœud confirme. 400 PERIOD_UNSUPPORTED pour tout period_s autre que 900 ; 400 BAD_REQUEST pour une voie inconnue, un ct_code hors de 1–7, ou toutes les voies désactivées |
disable / enable |
mac |
désactiver ou activer un nœud |
remove |
mac |
supprimer le nœud et ses points, avec leur historique |
latch |
— | demander à chaque nœud de clore sa période en cours immédiatement |
add |
mac, channels: [ { ch, ct_code } ] |
enregistrer un nœud à la main, sans appairage |
Les erreurs reviennent sous la forme { "ok": false, "error": "BAD_REQUEST" | "ESPNOW_DISABLED" | "ESPNOW_OFF" | "ESPNOW_START_FAILED" | "REGISTRY", "message": "…" }. Les points de nœud sont des points ordinaires dans tous les autres endpoints (src: "espnow" dans la trame en direct), et GET /api/system/provisioning renvoie nodes_paired.
Par MQTT, la même chose fonctionne sur le canal de commandes : {"cmd":"get","section":"espnow"} renvoie le GET ci-dessus, et {"cmd":"set","section":"espnow","token":"<admin>","data":{"action":"pair","seconds":60}} exécute une action et répond par la réponse du hub. Le hub publie un statut conservé par nœud sur rbgrid/<mac>/node/<NODEMAC>/status ({ "online", "rssi_dbm", "loss_pct", "last_seen_s" }, actualisé chaque minute) et les événements de nœud sur rbgrid/<mac>/event (paired, removed, node_online, node_offline). Dans Home Assistant, chaque nœud est un appareil avec un capteur Online et un capteur Signal (dBm) ; un nœud non entendu depuis le démarrage du hub affiche « no data ».
Messages
| Message | What it means |
|---|---|
| Remote nodes are not available in this hub firmware. | L'image firmware de ce hub ne peut pas faire tourner de nœuds. (Un hub antérieur à la v1.1.7 n'affiche aucune section Nodes.) |
| Turn the radio for nodes on to pair one. | La radio est éteinte ; allumez-la d'abord. |
| The hub takes up to 6 nodes. Remove one to pair another. | Les six emplacements de nœud sont occupés. |
| The radio for nodes is off. Turn it on first. | Une action nécessite la radio, et elle est éteinte. |
| The hub couldn't start the radio for nodes. Try again; if it keeps failing, restart the hub. | La radio n'a pas pu démarrer. |
| The hub couldn't change its node list (full, or the node isn't known). | Le registre des nœuds a refusé la modification. |
| The hub didn't accept the request. | Le hub a répondu que la requête était mal formée. Rechargez la page et réessayez. |
| The hub refused: message | La raison propre au hub. |
| The hub didn't answer. Check the connection and try again. | Pas de réponse du hub. |
| The hub doesn't know this node any more. Reload the page. | Le nœud a été supprimé, peut-être depuis un autre navigateur. |
| The hub takes only the 15-minute period. | Seule la période de 15 minutes est acceptée pour un nœud. |
Dépannage
J'ai appuyé sur Pair a node, mais rien n'apparaît
- Mettez le nœud sous tension, ou réinitialisez-le, pendant que la fenêtre est ouverte.
- Vérifiez que la radio pour les nœuds n'est pas éteinte, et que le hub est connecté à votre Wi-Fi.
- Un nœud appairé à un autre hub demande à nouveau une fois que cet hub ne lui a pas répondu pendant 150 secondes, ou immédiatement après une réinitialisation (voir Moving a node to another hub).
- Vérifiez l'alimentation du nœud, et que son flash s'est terminé sans erreur.
Le nœud est hors ligne, ou passe sans cesse de en ligne à hors ligne
- Rien n'a été entendu de lui depuis 15 secondes. Vérifiez d'abord son alimentation ; puis son emplacement. Voir Checking the link.
- La radio pour les nœuds du hub est peut-être éteinte : chaque nœud est alors hors ligne.
Signal, paquets perdus et synchronisation de l'horloge manquent sur la carte
- Le nœud n'a pas été entendu depuis le démarrage du hub (« Last heard: not heard since the hub started »). Les lignes apparaissent avec sa première trame.
Les points du nœud affichent des valeurs en direct mais pas d'historique
- Les 12 emplacements d'historique du hub étaient déjà occupés lors de l'appairage du nœud : « Points beyond 12 show live values only. » Supprimez un point dont vous n'avez pas besoin, puis appairez de nouveau le nœud, ou acceptez des points en direct uniquement.
- Un nœud n'enregistre de l'énergie qu'avec un module qui mesure la tension. Un module de courant seul donne le courant en direct et une puissance en direct estimée (votre tension nominale × courant, 230 V si aucune n'est réglée) — mais aucune période, aucun historique et aucun coût. À partir de la v1.1.8, le hub n'enregistre aucune énergie pour une telle entrée, plutôt que de l'inventer à partir de la tension nominale.
Tous les nœuds sont hors ligne alors qu'ils sont alimentés et appairés
GET /api/v1/espnow→inject_age_msà-1signifie que la tâche du hub qui enregistre les données des nœuds ne tourne pas. Jusqu'à la v1.1.7, le hub pouvait ne pas la démarrer silencieusement lorsque la RAM interne était insuffisante au démarrage, sans rien signaler ; la v1.1.8 réserve cette mémoire au moment de la compilation. Mettez le hub à jour.
À partir de la v1.2.0, vous n'avez pas à la chercher : la section Remote nodes affiche un avertissement lorsque la tâche s'est arrêtée, avec un bouton Restart now à côté.

Un redémarrage efface la condition sur un hub qui dispose de la mémoire ; si elle revient après le redémarrage, le hub tourne sur un firmware antérieur à la v1.1.8 et la solution est la mise à jour, non un nouveau redémarrage.
La synchronisation de l'horloge se perd sans cesse
- Un autre hub RBgrid est sur le même canal Wi-Fi, et un nœud sous firmware 1.4 a accepté les balises temporelles des deux hubs. Mettez le nœud à jour vers 1.5 : il ne suit alors que le hub auquel il est appairé, et aucun réappairage n'est nécessaire.
L'énergie manque pendant un moment
- Le nœud était hors de portée plus longtemps qu'il ne peut garder de périodes, ou il a perdu son alimentation. Sur le firmware de nœud 1.5, cela représente environ cinq jours, et une coupure de courant ne fait pas perdre ce qu'il conserve ; sur la 1.4, c'est huit périodes, soit environ deux heures, et une coupure de courant fait perdre ces périodes ainsi que la période en cours.
- Le nœud était désactivé (Turn off) pendant ce temps : le hub jette les données d'un nœud tant qu'il est désactivé.
- Le nœud a démarré alors que le hub était injoignable : sur la v1.1.7, l'énergie depuis son démarrage tombe dans sa première période complète de 15 minutes ; une période antérieure paraît donc vide et celle-ci paraît élevée. Rien n'est perdu.
Mon routeur a changé de canal Wi-Fi
- Rien à faire. La radio du hub pour les nœuds suit le routeur, et un nœud qui n'entend rien pendant 8 secondes recherche de nouveau le hub.