• Simple configuration using templates

Introduzione al Modbus

Modbus è un semplice protocollo di comunicazione, spesso utilizzato per integrare apparecchiature HVAC. Utilizza la comunicazione master-slave, quando più dispositivi possono essere collegati al bus comune, ciascuno deve avere un ID Slave univoco e il dispositivo master interroga sempre i singoli dispositivi slave che rispondono ad esso.

Master - slave topologia

Nella maggior parte dei casi, TapHome viene utilizzato nella modalità in cui l'unità di controllo Core è Modbus Master e i dispositivi collegati sono Modbus Slave. Questo è impostato nella sezione Hardware → Modbus RTU o Modbus TCP. Tuttavia, è anche possibile utilizzare la direzione opposta, quando TapHome Core fornisce informazioni sui suoi dispositivi a un altro sistema superiore. È definito nella sezione Esporre dispositivi → Modbus RTU o Modbus TCP.

Livelli fisici

Modbus può comunicare attraverso diversi livelli fisici:

• tramite linea seriale, tipicamente RS485. Questo è indicato come Modbus RTU
• sulla rete LAN tramite il protocollo TCP/IP
• su rete LAN tramite protocollo UDP - attualmente non supportato dal sistema TapHome

Registri Modbus

Modbus definisce 4 tipi di registri:

Il numero di registro è di 16 bit, cioè può avere un valore da 0 a 65535. Le operazioni possono essere eseguite sui registri:

• lettura di più registri
• iscrizione di un registro
• iscrizione di più registri

Informazioni su cosa è memorizzato in quale registro e in quale formato fanno parte della documentazione dell'apparecchiatura fornita dal fornitore o produttore dell'apparecchiatura. Un esempio di documentazione Modbus di un fornitore di dispositivi Modbus:

Registro di tipo C (Coil), indice 58, poiché ha solo 2 valori (aperto/chiuso) e permette oltre alla lettura e alla scrittura, il tipo appropriato di dispositivo TapHome è Uscita Digitale.

Istruzioni accelerate per l'integrazione di un dispositivo Modbus in TapHome

1. Collegare il dispositivo al bus appropriato (per Modbus RTU e ASCII) o alla LAN (per Modbus TCP). Per un dispositivo TCP, assicurati che sia sulla stessa rete del controller TapHome Core, ad esempio utilizzando Fing (iOS, Android) o IP Scanner (Windows).
2. In TapHome → Hardware, aggiungere una nuova interfaccia Modbus RTU o Modbus TCP e impostare i parametri di comunicazione in base alla documentazione. Per Modbus RTU è Baud rate, Bit di stop, Parità, Bit di dati, per Modbus TCP è l'indirizzo IP.
3. Trova nella documentazione Modbus del dispositivo quale ID slave utilizza. Nel caso di Modbus TCP, questo è talvolta indicato come ID unità. Se si desidera utilizzare più dispositivi su un bus con Modbus RTU, è necessario modificare l'ID Slave di ciascuno in modo che sia univoco per la linea bus data.
4. Test di comunicazione - utilizzando lo strumento Operazioni manuali, provare a leggere alcune informazioni in base alla documentazione (tabella Modbus) per il dispositivo specificato. Se tutto funziona, dovresti vedere una lettura.
5. Se il test di comunicazione ha esito positivo, creare un Modulo che rappresenti il dispositivo Modbus
6. Scegliere quali informazioni dalla documentazione Modbus si desidera presentare nel sistema TapHome e creare i dispositivi corrispondenti. Inizia leggendo i valori (Leggi sceneggiatura) e, nel caso di attori, continua scrivendo (Scrivi sceneggiatura).
7. Se le funzioni di base del dispositivo funzionano, aggiungere agli script le definizioni di errore, avviso o informazione.
8. Se necessario, è anche possibile definire Attributi di servizio e Azioni di servizio per dispositivi e moduli TapHome
9. Se tutto è ottimizzato e comunica correttamente, esporta il modulo in un file XML in modo da poterlo utilizzare la prossima volta. Puoi anche contribuire alla community su github.com/taphome-official/modbus_templates

Implementazione in TapHome

Questa documentazione è destinata allo scenario in cui l'unità di controllo TapHome Core è un master Modbus e i dispositivi fisici aggiunti alla sezione Hardware → Modbus RTU / TCP sono slave Modbus.

Gerarchia

Interfaccia

Hardware → Modbus RTU: i dispositivi sono collegati su alcuni BUS, sono definiti i parametri base della trasmissione RS485, come baudrate, parità, bit di stop o se i dati sono ASCII o binari. Su questo bus possono essere collegati solo dispositivi con le stesse impostazioni di comunicazione. Inoltre, una comunicazione corretta può funzionare solo se i cavi A e B sono collegati correttamente. Hardware → Modbus TCP: i dispositivi sono collegati sulla stessa LAN dell'unità di controllo Core. Viene definita una porta TCP, comune a tutti i dispositivi collegati a questa interfaccia.

Modulo

Un'interfaccia può contenere uno o più moduli, che nella maggior parte dei casi coprono la comunicazione con l'intero dispositivo fisico. Dal punto di vista della configurazione, il Modulo definisce lo Slave ID univoco del dispositivo collegato per Modbus RTU, e inoltre l'indirizzo IP per Modbus TCP.

Dispositivo

Rappresenta uno specifico elemento di controllo o sensore nel sistema TapHome. Deve sempre far parte di un modulo genitore.

Dispositivi supportati:

• Output digitale
• Uscita analogica
• Termostato
• Interruttore multivalore
• Termometro
• Contatore elettrico
• Stato del contatto
• Pulsante
• Una variabile

Script per leggere e scrivere valori Modbus

I dispositivi TapHome comunicano con i dispositivi fisici Modbus tramite script.

Per la comunicazione con i dispositivi Modbus, su di essi sono definite sezioni di scripting:

• Inizia script: viene eseguito all'avvio del dispositivo (ad es. dopo il riavvio dell'unità di controllo)
• Lettura script: impostazione dei valori delle variabili globali o lettura degli stati di errore
• Script Read Value: script per la lettura di un valore specifico (quantità) da un dispositivo Modbus (es. temperatura impostata sul termostato o temperatura misurata sul termostato)
• Script di scrittura valore: scrive il valore sul dispositivo Modbus

Funzioni per la comunicazione con dispositivi Modbus

MODBUSR (lettura Modbus) Funzione per la lettura del registro da Modbus. A seconda del tipo di dati, può essere 1 registro (per tipi di dati a 16 bit), 2 registri (per tipi di dati a 32 bit) o più registri (per tipi di dati String)

MODBUSR(register_type, register_address, data_type, [OPTIONAL: number_of_characters if data_type=String])
Example: MODBUSR(H, 20, Int16)/100

Leggere il numero di registro H (o indirizzo) 20 e interpretarlo come un intero a 16 bit (un numero intero con un segno +-). Infine, dividi questo valore per il numero 100 (sposta la virgola decimale di 2 posizioni a sinistra).

MODBUSW (Scrittura Modbus)

MODBUSW(register_type, register_address, data_type, value_to_write)
Example: MODBUSW(H, 20, Int16, Te * 100)

Nel registro H con indirizzo 20 scrivere il valore della variabile Te moltiplicato per il numero 100 (spostando a destra la virgola di 2).

MODBUSWNE (Scrittura Modbus se diversa)

Uguale a MODBUSW con la differenza che legge il valore dal registro prima di scrivere, e lo scrive solo se il valore scritto è diverso da quello letto. L'intera operazione richiede più tempo e il suo utilizzo tipico è quando si impostano le proprietà di un dispositivo Modbus, dove la configurazione viene scritta nella memoria EEPROM con un numero limitato di scritture.

Tipi di dati Modbus

I contenuti dei registri sono definiti nella tabella modbus. Poiché la dimensione di un registro Modbus è di 16 bit, vengono utilizzati più spesso valori Int16 o UInt16 a 16 bit e le posizioni decimali vengono conteggiate alla rovescia per divisioni di 10 o 100. Ma alcuni dispositivi Modbus utilizzano anche registri a 16 bit con floating -numeri in punti (Float), oppure hanno un ordine di bit modificato (big endian, little endian), scrivono un numero in due registri (variazioni a 32 bit). A volte il modo più semplice per scoprire il tipo di dati corretto è utilizzare l'utilità direttamente nell'applicazione TapHome (Operazioni manuali), dove è possibile caricare 1 o più registri e cambiare dinamicamente il tipo di dati.

• Int16 (da -32.768 a 32.767)
• Uint16 (da 0 a 65.535)
• Int32 (da -2.147.483.648 a 2.147.483.647)
• Uint32 (da 0 a 4.294.967.295)
• Float (IEEE 754 virgola mobile a precisione singola)
• Bool 0 = falso, 1 = vero
• BigEndianInt16 = Int16
• Little Endian Int16
• BigEndianUint16 = Uint16
• LittleEndianUint16
• BigEndianInt32 / BigEndianInt32ByteSwap
• LittleEndianInt32 / LittleEndianInt32ByteSwap
• BigEndianUint32 / BigEndianUint32ByteSwap
• LittleEndianUint32 / LittleEndianUint32ByteSwap
• BigEndianFloat / BigEndianFloatByteSwap
• LittleEndianFloat / LittleEndianFloatByteSwap

• Corda

  Può essere utilizzato anche il formato BCD, grazie alle funzioni TOBCD() e FROMBCD()

Aggiornamento e intervallo di polling

Ciascun dispositivo nell'interfaccia Modbus ha un attributo Intervallo di polling definito, che determina la frequenza con cui l'unità di controllo TapHome deve eseguire il polling per i nuovi valori del dispositivo Modbus. La comunicazione Modbus è di tipo Master-Slave, quindi le informazioni dal dispositivo Modbus possono raggiungere TapHome solo quando TapHome lo richiede. Più lungo è l'intervallo di polling, più tardi viene aggiornato il valore in TapHome. Un intervallo di sondaggio troppo breve potrebbe significare che TapHome sarà gravato inutilmente dall'ottenimento di valori non necessari e potrebbe non avere il tempo di servire tutti i dispositivi entro l'intervallo di tempo specificato. Ad esempio, con Modbus RTU e velocità Baud Rate inferiori, ad es. 9600, una query/risposta può richiedere decine di ms. Per i termometri, nella maggior parte dei casi, è sufficiente un intervallo di 15000ms (15s), per i pulsanti, invece, il meno possibile, ad es. 50 ms. Alcuni dispositivi Modbus prevedono che il master scriva periodicamente il valore corrente nel registro. A questo serve l'attributo Scrittura periodica.

Definizione degli stati di errore dagli script

In alcuni script è possibile definire un errore/avviso/informazione sul dispositivo, in base alle informazioni lette dai registri Modbus del dispositivo. Questi messaggi vengono visualizzati in TapHome allo stesso modo dei messaggi di errore interni di TapHome. Facoltativamente, è possibile aggiungere un codice di errore numerico al messaggio di errore, se possibile per la manutenzione del dispositivo Modbus.

ADDERROR(), ADDWARING(), ADDINFO()

ADDERROR([Optional: custom_code], text)

Esempio: nella sezione Read Script del dispositivo Analog Output è presente un codice:

ADDERROR("Error without code");
ADDWARNING("Warning without code");
ADDINFO("Info without code");

ADDERROR(1, "Error with code");
ADDWARNING(1, "Warning with code");
ADDINFO(1,"Info with code");

...che si riflette sul dispositivo dai messaggi:

Attributi e azioni del servizio

Oltre a un valore (o più valori, come un termostato) da un dispositivo Modbus collegato, i moduli e i dispositivi TapHome possono anche leggere attributi di servizio o eseguire azioni di servizio. Questi non sono quindi accessibili sul desktop per altri utenti del sistema, ma servono solo per informazioni più dettagliate sul dispositivo Modbus, senza sovraccaricare inutilmente il sistema con un numero elevato di variabili e azioni.

Gli attributi del servizio vengono visualizzati nelle impostazioni del servizio del modulo o del dispositivo TapHome. In genere, vengono utilizzati per visualizzare informazioni sul dispositivo, come modello, numero di serie, versione firmware, versione hardware, ora dall'ultimo riavvio, ecc. Si tratta di informazioni utili dal punto di vista della manutenzione di un dispositivo Modbus, ma non ha senso creare dispositivi TapHome separati per loro.

Le azioni di servizio vengono visualizzate nelle impostazioni di servizio del modulo o del dispositivo TapHome, in fondo come pulsanti. Quando premuti, eseguono un'azione Modbus preimpostata che scrive le informazioni richieste nel registro. Esempio di utilizzo: Impostazione o modifica dell'ID Slave, Sostituzione del filtro, Impostazione del contatore al valore richiesto, Reset del dispositivo e simili.

Utilità utili

Aggiungi dal modello

Consente di configurare la comunicazione Modbus con il dispositivo senza alcuna conoscenza del protocollo Modbus o di come configurarlo in TapHome. I modelli predefiniti possono essere trovati:

• direttamente nell'applicazione: Aggiungi da modello → seleziona un dispositivo specifico → inserisci le informazioni di base e conferma. Tutti questi modelli sono mantenuti in un progetto git della comunità su https://github.com/taphome/modbus_templates e chiunque può suggerire nuove mod lì. Ciò che entra nelle app deve essere approvato direttamente dal team di TapHome
• nel tuo file XML: Aggiungi da modello → Aggiungi da file. Puoi creare il tuo file XML che definisce l'intero modello direttamente sul modulo Modbus, nel menu contestuale (3 punti in alto a destra), azione Salva come modello. Saremo felici se ci aiuti ad espandere il numero di dispositivi supportati e contribuisci con il tuo file XML al progetto git della comunità congiunta.

Maggiori informazioni sulla configurazione della comunicazione Modbus utilizzando i modelli

Operazioni manuali

Uno strumento pratico per una rapida verifica iniziale della tabella Modbus. Consente:

• caricare i seguenti registri X nella tabella da un registro specifico, quindi commutare dinamicamente i valori letti in diversi tipi di dati
• scrivere il valore nel registro indicato

Scansiona gli ID degli schiavi

Una pratica comune quando si imposta la comunicazione con un dispositivo Modbus è che l'ID slave predefinito in fabbrica sia diverso da 1 e non è facile calcolare il numero corretto. Ecco a cosa serve questa utility. Può eseguire la scansione dell'intervallo di ID Slave specificato provando a leggere dal registro selezionato sempre con l'ID Slave testato.

Informazioni sui registri

Si trova nella parte inferiore del modulo Modbus. Per ogni registro utilizzato, elenca informazioni su:

• Il nome TapHome del dispositivo che lo legge o scrive
• Data e ora dell'ultima lettura riuscita dal registro
• L'ultimo valore letto dal registro
• Data e ora dell'ultima iscrizione avvenuta con successo nel registro
• L'ultimo valore scritto nel registro

Impostazioni avanzate

Prelettura

TapHome crea un elenco di registri da leggere e da scrivere sui dispositivi Modbus, a seconda dell'intervallo di polling impostato. Il prefetch è un processo grazie al quale la centralina precarica nel buffer i valori di cui avrà bisogno durante l'aggiornamento. L'obiettivo è ridurre al minimo il numero di richieste e di andata e ritorno. Il precaricamento è influenzato da 2 impostazioni:

• Dimensione massima del gruppo dei registri di prefetch (situata nelle impostazioni di servizio del modulo): determina il numero massimo di registri che possono essere letti o scritti tramite la comunicazione Modbus con una richiesta.
• Modalità Prefetch (regolabile per ogni dispositivo):
• Nessun prelettura. Il precaricamento non verrà eseguito per questo dispositivo. Ciò significa che i valori verranno letti singolarmente ed esattamente quando viene eseguito lo script. Esempio di utilizzo: quando si comunica con un convertitore DALI non è possibile leggere direttamente il valore di una determinata luce, ma deve essere richiesto il prima possibile, il convertitore lo preparerà e solo successivamente lo restituirà. Qualsiasi precaricamento è inutile in questo caso.
• Prelettura isolata. Precarica più registri contemporaneamente, ma solo quelli definiti in questo dispositivo. Per esempio quando ho bisogno dei registri 3 e 4 nel dispositivo termostato, i registri 1, 2, 5, 6 vengono utilizzati negli altri dispositivi, quindi la richiesta dei registri 3 e 4 verrà fatta separatamente solo per questi 2 registri. Alcuni dispositivi Modbus lo richiedono.
• Prelettura normale. Si tenta di leggere tutti i registri richiesti dai dispositivi da ripristinare con il numero minimo di richieste. Nel caso di una sequenza di registri non continua, legge anche i registri che non vengono utilizzati, se sono stati letti correttamente in passato. Esempio: sono richiesti i registri 99 e 101. Se il registro 100 è stato letto correttamente in passato e la dimensione massima del gruppo di registri di prefetch è 3 o più, leggerà 3 registri con una richiesta dal registro 99. Se il registro 100 non viene utilizzato da nessuna parte e non è mai stato letto correttamente, esiste il rischio che la lettura di tale registro possa restituire un'eccezione Modbus, ad es. "Indirizzo dati illegali" in risposta all'intera richiesta.

Il prefetch può anche essere influenzato direttamente dallo script: se durante la lettura utilizziamo il registro SC o SH (invece di C o H), il valore viene letto un registro alla volta durante l'esecuzione dello script e non viene estratto dalla memoria cache. Allo stesso modo, durante la scrittura, se utilizziamo il registro SC o SH (invece di C o H), il valore viene scritto un registro alla volta e da un'altra funzione modbus. Il protocollo Modbus supporta 4 funzioni di scrittura: scrittura di più H, più C, scrivere un registro H o un C alla volta. Attenzione: non tutti i dispositivi possono supportare tutte queste funzioni. In questo modo, se necessario, lettura e scrittura possono essere combinate insieme e "una alla volta".

Porta TCP (Modbus TCP)

Nella maggior parte dei casi, il valore predefinito è 502, ma è possibile che alcuni dispositivi siano in ascolto su una porta diversa.

Timeout lettura/scrittura

Il tempo trascorso il quale TapHome rinuncia all'attesa di una risposta e segnala un errore di "Timeout", il che significa che il dispositivo non ha risposto alla richiesta entro l'intervallo di tempo indicato. I dispositivi Modbus lenti potrebbero non essere in grado di rispondere prontamente ed è necessario estendere questo intervallo all'ordine di 1 o diversi secondi. Ma attenzione ai valori inutilmente alti, perché se per qualche motivo la comunicazione con un dispositivo Modbus fallisce, ritarda inutilmente altri dispositivi Modbus in attesa di una risposta.

Ritardo tra le richieste

Il ritardo che TapHome inserisce tra le singole richieste a un dispositivo Modbus. Per Modbus TCP è di default 0 ms, per Modbus RTU questo ritardo secondo la specifica si basa sulla velocità di comunicazione (baud rate) di almeno 3,5 caratteri. Tuttavia, ci sono dispositivi Modbus TCP che richiedono fino a 5000 ms tra le richieste, o viceversa, alcuni dispositivi Modbus RTU possono gestire ritardi anche più brevi e sono quindi in grado di comunicare più velocemente.

Utilizza la comunicazione ASCII

Modbus ASCII è uno standard meno utilizzato in cui la comunicazione non è binaria, ma utilizza caratteri ASCII. La maggior parte di questi dispositivi utilizza anche l'impostazione "7 bit di dati".