Integrare componenti Modbus via TCP o seriale su Home Assistant

SCOPI DELLA GUIDA: Integrare componenti Modbus a Home Assistant Livello di difficoltà: medio Categoria d’integrazione: Local Push/Polling CONCETTI AFFRONTATI: Utilizzo e configurazione software	COMPONENTI SOFTWARE UTILIZZATE: Home Assistant Componente Home Assistant “Modbus” PREREQUISITI: Home Assistant configurato e funzionante DISPOSITIVI FISICI UTILIZZATI: Il computer sul quale è in esecuzione Home Assistant Il/i componente/i Modbus da integrare
GUIDA INDICATA A UTENTI CON ISTALLAZIONE:
NOTE E DISCLAIMER qualsiasi eventuale modifica agli impianti domestici dev'essere progettata e realizzata SOLO da personale qualificato; qualsiasi modifica non prevista attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno infatti puro scopo didattico) e fa decadere garanzia, omologazioni e certificazioni di qualità; dei dispositivi interessati; tutte le tecniche descritte si intendono applicate a software e firmware aggiornati alle ultime versioni disponibili; gli articoli di inDomus sono totalmente indipendenti e non sponsorizzati. Se mai questo cambiasse, verrà segnalato chiaramente sulle pagine oggetto di sponsorizzazione; questa pagina è materialmente scritta e manutenuta da più individui: non ci si aspetti né si pretenda un supporto personale. In caso di difficoltà, chiedere supporto alla community sul nostro forum o sulla nostra chat; se hai bisogno di orientarti, c'è la mappa.
Revisione guida: 1.0

Abstract

La possibilità di adottare, tra i tanti, lo standard Modbus quale veicolo per l’integrazione delle più disparate componenti compatibili con tale standard verso Home Assistant è certamente una delle tante possibilità che rende quest’ultimo uno degli HUB più adottati e apprezzati worldwide.

Solitamente gli standard più adottati in domotica personale sono il TCP/IP (via Wi-Fi/Ethernet), lo ZigBee, lo Z-Wave, KNX, il bluetooth, l’infrarosso/radiofrequenza e altri; Modbus, solitamente, è uno standard adottato piuttosto in ambito industriale e di ricerca, ma capita talvolta che anche alcuni componenti presenti in casa e negli uffici siano compatibili con esso, consentendo così ai possessori una piena integrazione nella propria domotica.

Lo scopo della presente guida è quello di illustrare tramite esempi come integrare su Home Assistant componenti Modbus-compatibili piuttosto semplici (come sensori, o attuatori) o altri, più complessi e strutturati.

Si parte

• Assunti
• Componente Home Assistant
  • Sensori
  • Attuatori
  • Sistemi clima (HVAC)

Assunti

Si assume che:

• il componente compatibile con lo standard Modbus da integrare sia già operativo;
• tale componente sia connesso a una rete TCP/IP dell’HUB tramite adattatore Wi-Fi o adattatore ethernet oppure, via adattatore seriale, direttamente al computer che ospita Home Assistant;
• si abbia a disposizione la mappa dei registri Modbus del componente (solitamente disponibile nella documentazione propria del componente).

Si assume altresì che, ovviamente, anche Home Assistant sia già operativo.

Componente Home Assistant

L’HUB Home Assistant contempla un componente d’integrazione dedicato a Modbus che consente, come già accennato negli assunti, di integrare componenti Modbus via seriale (connessi al computer ospitante Home Assistant) o tramite rete TCP, sempre tramite attuatore.

Il componente, debitamente configurato, consente di creare sostanzialmente entità di diversi tipi:

• binary_sensor
• climate
• cover
• sensor
• switch

La configurazione di tale componente si effettua tramite la modifica del file di configurazione di Home Assistant, aggiungendo un blocco di configurazione che sostanzialmente prevede:

• una sezione (o più) relativa alla tipologia di connessione (e relativi parametri);
• una sotto-sezione (o più) relativa alle varie entità da creare (ognuna contenente i parametri necessari per raggiungere, in scrittura o lettura, i registri Modbus del componente in questione).

La prima sezione è relativa alla configurazione seriale o TCP. Le due configurazione sono pressoché le seguenti:

#esempio di configurazione seriale
modbus:
  - name: hub1
    type: serial
    method: rtu
    port: /dev/ttyUSB0
    baudrate: 9600
    stopbits: 1
    bytesize: 8
    parity: N

#esempio di configurazione TCP
modbus:
  - name: hub1
    type: tcp
    host: 192.168.1.99
    port: 502

Come si piò apprezzare facilmente, la prima configurazione utilizza il parametro port (e altri) per indicare a Home Assistant su quale porta logica sia attestato l’adattatore seriale, mentre nella seconda utilizza host per indicare l’IP (e altri) per indicare l’indirizzamento TCP della rete sul quale è attestato l’adattatore (Wi-Fi o Ethernet che sia).

Ovviamente è possibile indicare più componenti, i quali vengono distinti dal blocco che inizia da “- name“; le variabili di configurazione in modalità seriale e TCP/IP sono disponibili qui.

Nella seconda parte della configurazione si andranno invece ad indicare le caratteristiche delle entità da generare: da qui in poi proseguiremo come anticipato per esempi.

Sensori

La piattaform “Sensor” è supportata da Modbus indicando in configurazione tante voci quanti sono valori da leggere dal componente Modbus in questione. In questo caso si definisce un sotto-blocco “sensors:”, come si può vedere nella configurazione d’esempio che segue:

modbus:
  - name: hub1
    type: tcp
    host: 192.168.1.20
    port: 502
    sensors:
      - name: "sensore 1"
        unit_of_measurement: °C
        slave: 1
        address: 100
        count: 1
        scale: 0.1
        offset: 0
        precision: 1
        data_type: integer
      - name: "sensore 2"
        unit_of_measurement: mg
        slave: 1
        address: 110
        count: 2
      - name: "sensore 3"
        unit_of_measurement: °C
        slave: 1
        address: 120
        input_type: input
        data_type: float
        scale: 0.01
        offset: -273.16
        precision: 2 

nel caso del primo sensore (“Sensor1“, il quale genererà un’entità chiamata sensor.sensor1), si indica in configurazione di andare a leggere il registro con indirizzo 100 al fine di estrapolare una temperatura, e così via. Tutti i sensori fanno capo al blocco “hub1“, il quale punta a un elemento Modbus via TCP.

UN ESEMPIO

Il protocollo Modbus prevede che l’utente conosca a priori cosa un determinato registro che si va a interrogare rappresenti. Le schede tecniche dei componenti Modbus, solitamente, espongono tabelle descrittive dei registri dove è possibile comprendere cosa rappresentino, la lunghezza in termini di byte e quale trasformazione/scaling richiedano.

Supponiamo a mo’ d’esempio di avere a disposizione un sensore Modbus che esponga, presso il registro 120, il valore intero di una temperatura in gradi Celsius. Ipotizziamo che interrogando il registro si ottengano dati interi elevati di un’unità di grandezza (eg. “272” anziché il decimale “27,2“). E’ chiaro quindi come questo valore vada, per ottenere una lettura intelleggibile, trasformato: in questo specifico caso la trasformazione necessaria sarà una scala di “0.01“.

Di seguito possiamo vedere l’esempio di configurazione:

sensor:
  platform: modbus
  registers:
    - name: "sensore di temperatura"
      hub: hub1
      unit_of_measurement: °C
      slave: 1
      register: 120
      register_type:
      data_type:
      scale: 0.01
      precision: 2 

Ovviamente, ogni configurazione andrà adattata al dispositivo in questione e alla relativa tabella registri.

Attuatori

Nondimeno, la piattaforma “Switch” viene definita in modo analogo:

modbus:
  - name: hub1
    type: tcp
    host: 192.168.1.44
    port: 502
    switches:
      - name: "switch 1"
        address: 13
        input_type: coil
      - name: "switch 2"
        slave: 2
        address: 14
        input_type: coil
      - name: "switch 3"
        address: 11
        command_on: 1
        command_off: 0

In questa configurazione vengono definiti due interruttori passo-passo (i blocchi “Switch1” e “Switch2“) e uno switch comandabile (“Register1“).

Sistemi clima (HVAC)

Definire un’entità “Climate” per controllare un impianto di riscaldamento/raffrescamento (quale sia, purché sia compatibile Modbus, ovviamente) non è tanto più complesso come si potrebbe immaginare. Vediamo una configurazione tipo:

modbus:
  - name: hub1
    type: tcp
    host: 192.167.1.32
    port: 502
    climates:
      - name: "climatizzatore sala"
        slave: 1
        data_type: uint
        data_count: 1
        scale: 0.1
        offset: 0
        precision: 1
        max_temp: 30
        min_temp: 15
        temp_step: 1
        target_temp_register: 2782
        current_temp_register: 27586
    sensors:
      - name: "sensore 1"
        slave: 10
        address: 0
        input_type: holding
        unit_of_measurement: °C
        count: 1
        scale: 0.1
        offset: 0
        precision: 1
        data_type: integer

La configurazione prevede semplicemente una quantità maggiore di parametri: facendo riferimento alla documentazione del componente in oggetto, è possibile completare la configurazione al fine di completare l’integrazione con successo.

UN ESEMPIO

Un nostro utente, VaR63, ci ha per esempio segnalato l’integrazione pienamente funzionante della propria caldaia Solvis, la quale, tramite le configurazioni illustrate anche su questo articolo, viene pienamente integrata al proprio Home Assistant.