node-red-contrib-vantage-infusion-mqtt 1.0.3

Professional Vantage InFusion Host Commands to MQTT bridge for Node-RED with native TCP/Telnet connection, dual output (MQTT and raw Vantage) and optional Home Assistant Auto-Discovery

npm install node-red-contrib-vantage-infusion-mqtt

node-red-contrib-vantage-infusion-mqtt

Un bridge bidirezionale professionale, performante e affidabile tra il protocollo Vantage InFusion (Legrand) Host Commands e MQTT per Node-RED.

Progettato con zero dipendenze esterne (utilizza esclusivamente i moduli nativi Node.js net ed events) e dotato di un motore di connessione TCP/Telnet nativo ad altissima resilienza con doppia uscita:

1. Uscita 1 (MQTT): pubblica topic strutturati e payload JSON formattati per broker MQTT e controller domotici (es. Home Assistant).
2. Uscita 2 (Vantage Raw): emette la stringa di testo originale dell'evento ricevuto dal controller as-is in chiaro (es. R:LOAD 120 100), ideale per diagnostica, filtraggio o elaborazioni dedicate.

Include inoltre l'Auto-Discovery MQTT per Home Assistant opzionale, che genera e pubblica automaticamente le configurazioni persistenti (retain: true), rendendo luci, dimmer, tapparelle, sensori, variabili e lo stato di connessione immediatamente visibili in Home Assistant senza dover scrivere alcun codice YAML!

Caratteristiche Principali

• Connessione TCP/Telnet Nativa & Zero Dipendenze:

  • Socket TCP bidirezionale persistente con gestione automatica del framing di riga (terminatore CRLF / \r\n).
  • Compatibile sia con la porta standard 3001 (Standard Host in chiaro) che con la porta 23 (Telnet con filtraggio trasparente dei comandi IAC RFC 854).
  • Riconnessione automatica a backoff esponenziale (da 500 ms a 30 s) in caso di interruzione di rete o riavvio del controller.
  • Sottoscrizione asincrona automatica all'apertura del socket (STATUS LOAD, STATUS BTN, STATUS TEXT, STATUS VARIABLE, STATUS BLIND, STATUS TASK, STATUS LED, STATUS THERM, ECHO OFF, VERSION).
  • Coda di invio comandi serializzata con pacing delay configurabile (default 50 ms) per evitare congestioni e non sovraccaricare il processore del controller InFusion.
  • Watchdog heartbeat integrato tramite interrogazione periodica VERSION.

• Traduzione Completa degli Oggetti Vantage InFusion:

  • Carichi Luci & Dimmer (LOAD): Acceso (ON), Spento (OFF), regolazione luminosità proporzionale (0-255), supporto rampe di transizione personalizzate (RAMPLOAD <VID> <Level> <Sec>), interrogazione stato (GETLOAD).
  • Tapparelle, Veneziane & Coperture (BLIND): Apertura (OPEN), Chiusura (CLOSE), Stop (STOP), posizionamento percentuale (POS <0-100>), interrogazione stato (GETBLIND).
  • Pulsanti e Tastiere (BTN): Pressione (PRESS), rilascio (RELEASE), simulazione combinata tocco rapido (BTN), invio rilascio programmato all'avvio (button_sync).
  • LED Tastiere (LED): Stato LED di feedback (ON / OFF), forzatura e lettura (GETLED).
  • Variabili di Sistema (VARIABLE): Supporto per stringhe testuali, numeri decimali e stati logici booleani/binari (ON / OFF), lettura (GETVARIABLE).
  • Sensori (SENSOR): Lettura e pubblicazione valori analogici/digitali dei sensori di luminosità, vento, temperatura, ecc. (GETSENSOR).
  • Task e Scenari Globali (TASK): Esecuzione immediata dei task programmati nel Design Center (TASK <VID> BOOT).
  • Diagnostica & Versione Controller (VERSION): Rilevamento automatico e pubblicazione della versione firmware attiva.

• Doppia Uscita Indipendente:

  • Uscita 1 (MQTT): { topic: "120/load/vantage/status", payload: "{...}", qos: 0, retain: false }
  • Uscita 2 (Vantage Raw): { topic: "vantage/raw/event", payload: "R:LOAD 120 100" }

• Integrazione Home Assistant (MQTT Auto-Discovery):

  • Genera payload conformi agli standard (homeassistant/<componente>/.../config) per luci con dimmer, coperture motorizzate, sensori, switch per variabili e sensore binario di connettività.

Architettura e Schema dei Flussi

                           ┌───────────────────────────────┐
                           │   Controller Vantage InFusion │
                           │     (TCP Porta 3001 / 23)     │
                           └──────────────┬────────────────┘
                                          │ Host Commands (CRLF)
                                          ▼
 [MQTT In / Comandi Set] ──► ┌───────────────────────────┐ ──► Uscita 1: [MQTT Out / Broker]
 (es. 120/load/vantage/set)  │    vantage-infusion-mqtt  │       (JSON formattato & Discovery)
                             └───────────────────────────┘ ──► Uscita 2: [Debug / Raw as-is]
                                                               (es. R:LOAD 120 100)

Installazione

In Node-RED Locale / Standalone

Esegui il comando nella tua cartella utente di Node-RED (solitamente ~/.node-red):

cd ~/.node-red
npm install node-red-contrib-vantage-infusion-mqtt

Oppure cerca node-red-contrib-vantage-infusion-mqtt direttamente nel Gestore della Tavolozza (Palette Manager) di Node-RED.

In Home Assistant (Add-on Node-RED)

Se utilizzi l'add-on ufficiale Node-RED su Home Assistant:

1. Apri Home Assistant e vai su Impostazioni → Add-on → Node-RED.
2. Fai clic sulla scheda Configurazione.
3. Nella sezione npm packages, aggiungi:

   npm_packages:
     - node-red-contrib-vantage-infusion-mqtt
   

4. Fai clic su Salva e Riavvia l'add-on. Al riavvio il nodo sarà pronto nella palette!

Riferimento Topic MQTT

Topic di Stato (Emessi su Uscita 1)

Topic di Comando (Ricevuti in Ingresso)

Parametri di Configurazione

Config Node (vantage-controller)

• Host / IP: Indirizzo IP o hostname di rete del controller Vantage InFusion.
• Porta: Porta TCP di connessione (predefinita: 3001 per Host in chiaro, oppure 23 per Telnet).
• Keep-Alive: Intervallo in secondi per l'heartbeat periodico VERSION (predefinito: 60).
• Pacing Delay: Ritardo in millisecondi tra comandi successivi inviati sulla coda (predefinito: 50).
• Debug: Abilita la stampa dei log diagnostici nella console di Node-RED.

Bridge Node (vantage-infusion-mqtt)

• Luci / Carichi (VID): Elenco separato da virgole dei VID dei carichi luce (es. 120, 121, 122).
• Tapparelle (VID): Elenco separato da virgole dei VID delle coperture/veneziane (es. 55, 56).
• Sensori (VID): Elenco separato da virgole dei VID dei sensori (es. 141).
• Variabili (VID): Elenco separato da virgole dei VID delle variabili interne (es. 501, 502).
• Pulsanti (VID): Elenco separato da virgole dei pulsanti tastiera da resettare con RELEASE all'avvio.
• Task / Scenari (VID): Elenco separato da virgole dei VID dei task e macro globali (es. 301, 302).
• Termostati (VID): Elenco separato da virgole dei VID dei termostati/clima (es. 201, 202).
• LED Tastiere (VID): Elenco separato da virgole dei VID dei LED di feedback (es. 401, 402).
• Sincronizza all'avvio: Invia automaticamente le richieste GET... alla connessione con il controller.
• Sincronizzazione Periodica: Intervallo in secondi tra le sincronizzazioni di stato forzate (predefinito: 300).
• Watchdog: Monitora l'attività della connessione e imposta lo stato di connessione a OFF in caso di mancata risposta.
• Auto-Discovery MQTT: Attiva la configurazione automatica delle entità su Home Assistant.
• Prefisso Discovery: Prefisso MQTT (predefinito: homeassistant).

Licenza

MIT © 2026 Bruno Leonardi