Node-RED : relais Cerbo GX selon le SoC avec hystérésis

Avant de commencer

Node-RED activé. Cerbo GX avec Venus OS Large et Node-RED activé ; l’éditeur s’ouvre à l’adresse https://venus.local:1881. Procédure : première mise en service de Node-RED.
Moniteur de batterie visible sur le GX. Le SoC provient d’un moniteur de batterie ou d’un BMS connecté au GX, par exemple un SmartShunt, un BMV ou un Lynx Shunt. Si le GX n’affiche pas l’état de charge, Node-RED ne le recevra pas non plus.
Relais en mode manuel. Chez Victron, un relais ne peut être commandé depuis Node-RED qu’après son passage en commande manuelle. Pour les relais du Cerbo GX : Settings → Integrations → Relays, fonction « Manual ». Ce menu permet aussi de définir la polarité du relais (normalement ouvert ou normalement fermé).

Cerbo GX : bornes Relay 1 et Relay 2 (NO, COM, NC) en bas, à côté de l’alimentation. Dans Node-RED, Relay 1 correspond à « Venus relay 1 state », chemin /Relay/0/State. — Cerbo GX : les bornes Relay 1 et Relay 2 (NO, COM, NC) se trouvent en bas, à côté de l’alimentation. Dans Node-RED, Relay 1 correspond à « Venus relay 1 state », chemin /Relay/0/State.

D’autres relais peuvent aussi être commandés depuis Node-RED, mais chacun doit d’abord être configuré : sur le BMV, régler l’option du relais sur REM (dans VictronConnect) ; sur le Lynx Shunt VE.Can, sélectionner la fonction « Manual control » (dans le menu GX) ; sur les régulateurs MPPT de plus grande taille et les appareils de la série RS, sélectionner le mode manuel (dans VictronConnect). Le relais du Lynx Smart BMS ne peut pas être commandé depuis Node-RED. Il en va de même pour le relais d’alarme et le contacteur AC-out 2 des MultiPlus et Quattro.

Vous souhaitez démarrer un groupe électrogène ? Le GX dispose d’une fonction intégrée de démarrage et d’arrêt automatiques par relais, avec ses propres conditions de démarrage (chapitre « Generator auto start/stop » du manuel GX) : Node-RED n’est donc pas nécessaire. L’exemple Victron avec groupe électrogène (ci-dessous) ne commande pas directement le relais, mais utilise le nœud Generator.

Fonctionnement de ce flow

messages (msg) entre les nœuds

Survolez un élément du schéma ou touchez-le.

Battery (entrée)État de charge fourni par le moniteur de batterie — à chaque changement et, sans « only changes », également toutes les 5 s.
hystérésis (function)SoC ≤ 30% → 1, SoC ≥ 50% → 0, état inchangé entre les deux. Envoie uniquement les changements d’état.
Relay (sortie)1 ferme le relais 1 du Cerbo GX, 0 l’ouvre (/Relay/0/State).
debugAffiche dans le panneau Debug chaque valeur envoyée au relais.

Création étape par étape

Nouvel onglet. Dans l’éditeur Node-RED, ajoutez un nouvel onglet de flow (bouton « + » au-dessus de l’espace de travail) pour ne pas mélanger cet exemple avec les autres flows.
Nœud Battery. Depuis la section des nœuds Victron de la palette, faites glisser le nœud d’entrée Battery. Dans ses paramètres, sélectionnez votre moniteur de batterie et la mesure « State of charge (%) ». Laissez « only changes » décoché : le nœud envoie alors le SoC à chaque changement et toutes les 5 secondes, ce qui permet à la fonction de recevoir rapidement une valeur, même après un redémarrage.
Nœud function. Ajoutez un nœud function standard, nommez-le « hystérésis » et collez le code de la section « Code de l’hystérésis ». Reliez la sortie du nœud Battery à l’entrée de la fonction.
Nœud Relay. Ajoutez un nœud de sortie Relay, sélectionnez « Venus device » et « Venus relay 1 state » (chemin /Relay/0/State — la numérotation du chemin commence à 0, donc l’indice 0 correspond au relais 1). Le nœud applique la valeur reçue dans msg.payload : 0 — Open, 1 — Closed. Reliez la sortie de la fonction à ce nœud.
Nœud debug. Reliez également un nœud debug à la sortie de la fonction. Les valeurs apparaissent dans le panneau Debug, à droite de l’éditeur ; le SoC actuel et l’état du relais s’affichent sous le nœud « hystérésis ».
Deploy et test. Cliquez sur Deploy. Pour ne pas attendre la décharge de la batterie, ajoutez temporairement un nœud inject avec une valeur numérique (type « number », par exemple 25, puis 55), relié à la fonction, et vérifiez que le relais change d’état dans le menu Relays. Supprimez ensuite inject et cliquez à nouveau sur Deploy.

Code de l’hystérésis

Si le relais devait s’activer et se désactiver à un seul seuil, par exemple 40%, il commuterait sans cesse lorsque le SoC fluctue autour de cette valeur. L’hystérésis sépare ces seuils : le relais se ferme à 30% ou moins et ne s’ouvre qu’à 50% ou plus. Entre les deux, il conserve son état précédent. La fonction mémorise cet état dans le contexte du nœud et n’envoie un message qu’en cas de changement : le relais ne reçoit donc pas la même valeur toutes les 5 secondes.

// Hystérésis: fermez le relais à SoC <= 30 %, ouvrez-le à SoC >= 50 %.
// Les seuils sont des exemples - définissez les vôtres.
const PROG_ZAL = 30;
const PROG_WYL = 50;

const soc = msg.payload;
if (typeof soc !== 'number' || isNaN(soc)) return null;  // aucune lecture: ne rien faire

const poprzedni = context.get('stan');
let stan = (poprzedni === undefined) ? 0 : poprzedni;
if (soc <= PROG_ZAL) stan = 1;       // 1 = Closed
else if (soc >= PROG_WYL) stan = 0;  // 0 = Open
// entre les seuils, l’état ne change pas

node.status({fill: stan ? 'green' : 'grey', shape: 'dot',
             text: 'SoC ' + soc.toFixed(1) + ' %, relais ' + (stan ? 'fermé' : 'ouvert')});

if (stan === poprzedni) return null;  // envoyer uniquement les changements
context.set('stan', stan);
msg.payload = stan;
return msg;

SoC	Action de la fonction	Relais
60%	première lecture, 50% ou plus → envoie 0	ouvert
40%	entre les seuils — n’envoie rien	ouvert
30%	30% ou moins → envoie 1	fermé
45%	entre les seuils — n’envoie rien	fermé
50%	50% ou plus → envoie 0	ouvert

Logique inversée. Vous souhaitez déconnecter un appareil lorsque le SoC est faible, plutôt que l’allumer ? Inversez 1 et 0 dans les deux lignes du code contenant les seuils, ou raccordez le circuit à l’autre contact du relais — NC au lieu de NO.
Absence de lecture. Si msg.payload n’est pas un nombre (par exemple, si le moniteur de batterie n’est plus détecté), la fonction n’envoie rien et le relais conserve son état.
Après un redémarrage. Par défaut, le contexte du nœud est stocké dans la mémoire RAM de l’appareil GX et disparaît lors d’un redémarrage ou d’une coupure d’alimentation. La première lecture après un redémarrage définit toujours l’état du relais : si le SoC est entre les seuils, il passe à 0 (ouvert), même s’il était fermé avant le redémarrage. La section « Points de vigilance » explique comment conserver le contexte.

Flow prêt à importer

Le même flow au format JSON. Les nœuds Victron sont construits comme dans les exemples de la documentation de la palette node-red-contrib-victron.

Copiez tout le bloc ci-dessous, y compris les crochets [ et ].
Importation. Dans l’éditeur, ouvrez le menu (bouton en haut à droite) → Import, ou appuyez sur Ctrl-I, collez le texte et cliquez sur Import. Le flow apparaît dans un nouvel onglet « Relais selon SoC ».
Sélectionnez votre moniteur de batterie. Ouvrez le nœud « SoC batterie » et sélectionnez dans la liste votre moniteur de batterie ainsi que « State of charge (%) ».
Vérifiez le relais dans le nœud « Relais 1 GX », modifiez les seuils dans la fonction si nécessaire, puis cliquez sur Deploy.

Après l’importation, sélectionnez votre appareil

Le nœud Battery pointe vers un SmartShunt utilisé comme exemple dans la documentation Victron (com.victronenergy.battery/277). Le numéro final diffère d’une installation à l’autre : il dépend de l’appareil et du mode de raccordement. Tant que vous n’avez pas sélectionné votre moniteur de batterie dans le nœud, la fonction ne reçoit pas le SoC et le relais ne commute pas.

[
{"id":"c24a5c0f10000001","type":"tab","label":"Relais selon SoC","disabled":false,"info":"Hystérésis 30/50 % - exemple de cpv24.pl"},
{"id":"c24a5c0f10000002","type":"victron-input-battery","z":"c24a5c0f10000001","service":"com.victronenergy.battery/277","path":"/Soc","serviceObj":{"service":"com.victronenergy.battery/277","name":"SmartShunt (exemple - sélectionnez le vôtre)"},"pathObj":{"path":"/Soc","type":"float","name":"State of charge (%)"},"initial":"","name":"SoC batterie","onlyChanges":false,"x":150,"y":120,"wires":[["c24a5c0f10000003"]]},
{"id":"c24a5c0f10000003","type":"function","z":"c24a5c0f10000001","name":"hystérésis","func":"// Hystérésis: fermez le relais à SoC <= 30 %, ouvrez-le à SoC >= 50 %.\n// Les seuils sont des exemples - définissez les vôtres.\nconst PROG_ZAL = 30;\nconst PROG_WYL = 50;\n\nconst soc = msg.payload;\nif (typeof soc !== 'number' || isNaN(soc)) return null;  // aucune lecture: ne rien faire\n\nconst poprzedni = context.get('stan');\nlet stan = (poprzedni === undefined) ? 0 : poprzedni;\nif (soc <= PROG_ZAL) stan = 1;       // 1 = Closed\nelse if (soc >= PROG_WYL) stan = 0;  // 0 = Open\n// entre les seuils, l’état ne change pas\n\nnode.status({fill: stan ? 'green' : 'grey', shape: 'dot',\n             text: 'SoC ' + soc.toFixed(1) + ' %, relais ' + (stan ? 'fermé' : 'ouvert')});\n\nif (stan === poprzedni) return null;  // envoyer uniquement les changements\ncontext.set('stan', stan);\nmsg.payload = stan;\nreturn msg;","outputs":1,"noerr":0,"initialize":"","finalize":"","libs":[],"x":370,"y":120,"wires":[["c24a5c0f10000004","c24a5c0f10000005"]]},
{"id":"c24a5c0f10000004","type":"victron-output-relay","z":"c24a5c0f10000001","service":"com.victronenergy.system/0","path":"/Relay/0/State","serviceObj":{"service":"com.victronenergy.system/0","name":"Appareil Venus"},"pathObj":{"path":"/Relay/0/State","type":"enum","name":"État du relais 1 Venus","enum":{"0":"Open","1":"Closed"},"writable":true},"initial":"","name":"Relais 1 GX","onlyChanges":true,"x":600,"y":120,"wires":[]},
{"id":"c24a5c0f10000005","type":"debug","z":"c24a5c0f10000001","name":"état du relais","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"payload","targetType":"msg","statusVal":"","statusType":"auto","x":610,"y":180,"wires":[]}
]

Exemples intégrés Victron

La palette Victron comprend une bibliothèque d’exemples : menu (en haut à droite) → Import → Examples → node-red-contrib-victron. Les mêmes flows sont également disponibles sur le wiki de la palette, ce qui permet de les consulter sans l’éditeur. Trois d’entre eux se rapprochent de cet exemple :

Exemple	Fonctionnement	Différences avec le flow de cette page
Threshold Control	La sortie s’active lorsque la valeur d’entrée dépasse le seuil ON et se désactive lorsqu’elle descend sous le seuil OFF. Avant chaque commutation, elle attend la temporisation définie (ON/OFF delay). Les seuils et la commande manuelle sont accessibles sur le tableau de bord.	Commande le même relais 1 (`/Relay/0/State`), mais utilise comme entrée la tension de la batterie provenant du nœud System (`/Dc/Battery/Voltage`), et non le SoC, avec des temporisations supplémentaires. Nécessite les modules complémentaires node-red-dashboard, node-red-contrib-ui-led et node-red-contrib-countdown.
Run generator at certain time when SOC is below 50%	Vérifie chaque jour à 18.00 le SoC mémorisé. S’il est faible, démarre le groupe électrogène pendant 45 minutes : le nœud trigger envoie 1, puis 0 après 45 minutes. Le SoC est enregistré dans le contexte `flow.SOC` par un nœud change.	Commande le nœud Generator (Manual Start), et non le relais. Attention : la description indique « inférieur à 50% », mais le nœud switch de ce flow vérifie « inférieur ou égal à 50 » (nom : « Start if SOC is <= 50% »).
Only messages at regular intervals	Le nœud change enregistre la dernière valeur dans le contexte, et le nœud inject la lit à intervalles réguliers.	Utile si vous avez besoin de la dernière valeur à intervalles réguliers, indépendamment du moment où le nœud d’entrée l’envoie.

Description de tous les nœuds d’entrée et de sortie Victron : nœuds Victron dans Node-RED.

Points de vigilance

Contexte après redémarrage. Pour conserver le contexte après un redémarrage, Victron décrit dans sa FAQ le fichier /data/home/nodered/.node-red/settings-user.js avec le paramètre contextStorage (module localfilesystem, enregistrement toutes les 300 s, soit toutes les 5 minutes). Si ce stockage de contexte est défini par défaut, le code de la fonction fonctionne sans modification. Victron déconseille les écritures trop fréquentes, car elles usent la mémoire flash.
Mode sans échec. Si, après des modifications, un flow surcharge le GX ou fonctionne mal, activez Node-RED en mode sans échec (safe mode) dans le menu GX. Node-RED démarre sans exécuter les flows : vous pouvez les corriger, puis les lancer en cliquant sur Deploy.
Redémarrage de Node-RED. Dans le menu GX, désactivez puis réactivez Node-RED sous Venus OS Large Features → Node-RED.
Heure dans les flows. Dans les exemples pilotés par l’heure, comme celui du groupe électrogène à 18.00, Node-RED utilise le fuseau horaire défini dans Remote Console. Après toute modification de ce fuseau, redémarrez Node-RED.

Automatisation, pas protection

Un flow Node-RED ne remplace ni le BMS, ni les fusibles, ni les disjoncteurs : lors d’un redémarrage du GX ou d’une erreur dans le flow, le relais peut rester dans un état inattendu. Le circuit raccordé au relais doit être sûr dans les deux états. Victron n’assure pas d’assistance pour les installations utilisant Node-RED pour des solutions avancées.

Appareils concernés

Cerbo GXCentre de commande du système et passerelle vers le portail VRM.

Sources

À suivre : Node-RED sur Cerbo GX — tous les articles · première mise en service · nœuds Victron · Cerbo GX