MQTT Home Assistant - IoT

Il bridge normalizza i telegrammi KNX in messaggi strutturati per trasporti IoT (MQTT, REST, Modbus) e accetta input dal flow per riscrivere sul bus. Qui trovi una guida rapida e i collegamenti consigliati ai nodi di trasporto di Node-RED.

Modalità di funzionamento

Il nodo ha un selettore Modalità:

• Bridge IoT (predefinito) — il comportamento descritto qui sotto: una lista di mappature che trasforma i telegrammi KNX in messaggi di output MQTT/REST/Modbus e viceversa.
• MQTT / Home Assistant (nativo) — il nodo si connette direttamente a un broker MQTT e fa da ponte KNX ↔ MQTT in entrambe le direzioni, pubblicando il discovery MQTT di Home Assistant così KNX compare automaticamente in Home Assistant. Non serve cablare nodi mqtt in/mqtt out.

Modalità MQTT / Home Assistant

Requisiti: un broker MQTT raggiungibile sia da Node-RED che da Home Assistant, con l’integrazione MQTT attiva in HA. Tutte le entità sono raggruppate sotto un unico dispositivo HA con il nome del nodo.

Tapparelle e Termostati

Tapparelle e termostati combinano più indirizzi di gruppo in un’unica entità HA, quindi non possono essere dedotti da un singolo DPT - aggiungili nella lista:

• Tapparella: GA su/giù (1.008), GA stop opzionale (1.007), GA posizione comando/stato opzionale (5.001). Inverti posizione mappa KNX (0% = aperto) su Home Assistant (100% = aperto).
• Termostato: GA temperatura attuale (9.001), GA setpoint comando/stato (9.001), GA on/off opzionale (1.001 → off/heat), più temperatura min/max e step.

I tipi di datapoint vengono letti dall’import ETS se disponibili, altrimenti dai default KNX. Per uno stato affidabile, gli indirizzi usati da tapparelle/termostati dovrebbero essere presenti nell’import ETS.

Integrazione KNX nativa vs bridge MQTT. Se Home Assistant comunica già con KNX tramite la sua integrazione KNX nativa, tapparelle/clima si configurano lì con i group address e questo bridge MQTT non serve. Usa questa modalità quando è Node-RED a possedere il bus KNX e Home Assistant vede tutto via MQTT.

Riepilogo mappatura

Trasporti tipici

MQTT broker

• Pubblicazione: collega l’uscita 1 al nodo core mqtt out. Il bridge imposta msg.topic e msg.payload già pronti per il broker.
• Sottoscrizione: collega un nodo mqtt in all’ingresso del bridge. I payload sono convertiti secondo il DPT e scritti su KNX; l’ack sul pin 2 conferma la scrittura.

  REST API

• Invita l’uscita 1 nel nodo core http request (o contrib come node-red-contrib-http-request).
• Il bridge propaga bridge.method in msg.method e il template in msg.payload, così puoi inviare JSON o form-data.

  Registri Modbus

L’IoT Bridge è un adattatore di messaggi per node-red-contrib-modbus. Non crea un client TCP/seriale e non interroga autonomamente i dispositivi: installa una versione del pacchetto compatibile con il tuo runtime Node-RED e configura queste parti nei nodi Modbus esterni.

Per le nuove righe scegli Compatibile con Flex Write, imposta Unit ID, Area e Tipo di dato, quindi inserisci in Target l’indirizzo di protocollo zero-based. Un valore KNX inviato a un coil genera FC5; verso un holding register genera FC6. L’uscita 1 è direttamente compatibile con modbus-flex-write:

msg.payload = {
  value: 215,
  fc: 6,
  unitid: 1,
  address: 9,
  quantity: 1
}

Per riportare i dati verso KNX, collega l’uscita dati di modbus-flex-getter o modbus-read all’ingresso del bridge. Flex Getter fornisce la richiesta (fc, unitid, address, quantity) in msg.modbusRequest; Modbus Read la conserva in msg.input.payload. L’array dei valori restituiti può trovarsi in msg.payload oppure in msg.values. Il bridge supporta entrambe le forme. Abilita Keep Msg Properties su Flex Getter. Una singola risposta di lettura può coprire più indirizzi configurati e il bridge sceglie l’elemento corretto dell’array per ogni riga corrispondente.

È supportato un solo bit o un singolo registro a 16 bit per mappatura: bool, uint16 o int16. Valori multiword, decodifica a 32 bit/float e conversione dell’ordine byte/word non fanno parte di questo adattatore. Scala e offset seguono raw = KNX × scala + offset; Modbus → KNX applica l’inversa. Lettura valori KNX al deploy non esegue polling Modbus.

Le mappature senza modbusMessageFormat mantengono l’output scalare legacy con msg.address e msg.modbusFunction al livello principale, quindi i flow salvati non vengono migrati implicitamente.

Flow di esempio

Stato KNX → MQTT

[
  {
    "id": "bridge1",
    "type": "knxUltimateIoTBridge",
    "z": "flow1",
    "server": "gateway1",
    "name": "Bridge luci",
    "emitOnChangeOnly": true,
    "readOnDeploy": true,
    "acceptFlowInput": true,
    "mappings": [
      {
        "id": "map-luce",
        "enabled": true,
        "label": "Luce soggiorno",
        "ga": "1/1/10",
        "dpt": "1.001",
        "direction": "bidirectional",
        "iotType": "mqtt",
        "target": "knx/light/soggiorno",
        "method": "POST",
        "modbusFunction": "writeHoldingRegister",
        "scale": 1,
        "offset": 0,
        "template": "{{value}}",
        "property": "",
        "timeout": 0,
        "retry": 0
      }
    ],
    "wires": [["mqttOut"],["debugAck"]]
  },
  {
    "id": "mqttOut",
    "type": "mqtt out",
    "name": "MQTT stato",
    "topic": "",
    "qos": "0",
    "retain": "false",
    "broker": "mqttBroker",
    "x": 520,
    "y": 120,
    "wires": []
  },
  {
    "id": "debugAck",
    "type": "debug",
    "name": "Ack KNX",
    "active": true,
    "tosidebar": true,
    "complete": "true",
    "x": 520,
    "y": 180,
    "wires": []
  }
]

Comando MQTT → KNX

[
  {
    "id": "mqttIn",
    "type": "mqtt in",
    "name": "MQTT comando",
    "topic": "knx/light/soggiorno/set",
    "qos": "1",
    "datatype": "auto",
    "broker": "mqttBroker",
    "x": 140,
    "y": 200,
    "wires": [["bridge1"]]
  }
]

Unisci i due snippet nello stesso flow per ottenere il round-trip KNX ↔ MQTT con ack.

Payload REST

{
  "id": "bridge-rest",
  "type": "knxUltimateIoTBridge",
  "name": "Bridge contatore",
  "mappings": [
    {
      "label": "Potenza attiva",
      "ga": "2/1/20",
      "dpt": "9.024",
      "direction": "knx-to-iot",
      "iotType": "rest",
      "target": "https://example/api/knx/power",
      "method": "POST",
      "template": "{\"value\":{{value}},\"ga\":\"{{ga}}\",\"ts\":\"{{isoTimestamp}}\"}"
    }
  ]
}

Instrada l’uscita 1 verso http request e usa la risposta per log o retry basati su bridge.retry.

Scrittura Modbus

1. Mappa con Target = 9, Tipo = Modbus, Formato = Compatibile con Flex Write, Unit ID = 1, Area = Holding register, Tipo di dato = uint16.
2. Collega direttamente l’uscita 1 del bridge a modbus-flex-write; non serve un nodo Function.
3. Collega la risposta di modbus-read o modbus-flex-getter all’ingresso del bridge per Modbus → KNX.
4. Importa examples/IoT Bridge - Modbus Flex Adapter.json come flow iniziale manuale e senza polling.

   Suggerimenti finali

   • Lascia Target vuoto solo nelle mappature MQTT/REST che devono ereditare outputtopic; Modbus Flex richiede un indirizzo.
   • emitOnChangeOnly limita il rumore dei sensori; disattivalo se serve ogni telegramma.
   • L’uscita 2 conferma il valore effettivamente inviato a KNX; non è una conferma fisica di lettura/scrittura Modbus.
   • Un riferimento di manuale come 40010 corrisponde comunemente all’indirizzo 9, ma verifica sempre la documentazione del dispositivo. Buon bridging!