Modulo smartCORE ModBus
Descrizione
Il modulo "modbus" legge principalmente i registri ModBus dei nodi ModBus. Questi nodi possono essere collegati
- tramite una connessione seriale (ModBus/RTU)
- tramite TCP (ModBus/TCP)
Interfacce e protocolli utilizzati
- ModBus
Configurazione JSON
Nella sezione seguente viene descritta l'intera configurazione JSON del modulo e vengono illustrati i singoli parametri.
Configurazione di esempio
Di seguito è riportata una configurazione di esempio per ModBus/TCP:
{
"module": "ModBus",
"comment": "ModBus/TCP config",
"factory": "modbus",
"config": {
"version": 1,
"type": "modbus",
"enable": true,
"pollCycleInMilliseconds": 1000,
"transport": {
"type": "tcp",
"ipAddress": "192.168.0.1",
"ipPortNumber": 502,
"timeoutInMilliseconds": 200
},
"devices": [
{
"enable": true,
"deviceName": "Device Name",
"deviceAddress": 1,
"readChannels": [
{
"name": "Channel Name",
"address": 49152,
"registerType": "HoldingReg",
"registerFormat": "REAL",
"byteOrder": "ABCD",
"bitOffset": 0,
"unit": "",
"scale": 1.0,
"offset": 0.0
}
]
}
]
}
}
Parametri globali del modulo
| Nome del parametro | Obbligatorio | Tipo di dati | Intervallo di valori sensato | Default | Descrizione |
|---|---|---|---|---|---|
| version | SÌ | INT | 1 | Versione del protocollo ModBus | |
| type | SÌ | STRING | "modbus" | Interfaccia seriale per la comunicazione | |
| enable | SÌ | BOOL | true | Interruttore per la produzione dei dati negli smartCHANNEL | |
| pollCycleInMilliseconds | SÌ | INT | 1 - | Intervallo di interrogazione [ms] degli accessi ModBus | |
| transport | SÌ | JSON Objekt | Configurazione del livello di trasporto ModBus (vedere sotto) | ||
| devices | SÌ | JSON Array von JSON Objekten | Elenco dei nodi ModBus | ||
| pollCycleInNanoseconds | No | INT | 1 - | 100000000 | Intervallo di interrogazione [ns]. Se la chiave è impostata, ha la precedenza su pollCycleInMilliseconds. Se mancano entrambe, vengono utilizzati 100 ms |
| enableInternalDataReduction | No | BOOL | true, false | false | Aggiunge a ogni canale generato una riduzione dei dati (absTolerance 0.0, timeoutMs 60000): i valori invariati non vengono scritti, al più tardi dopo 60 s però di nuovo |
| autoGroup | No | BOOL | true, false | true | Riunisce automaticamente registri adiacenti di un dispositivo in blocchi di registri, letti in un'unica transazione (vedere Blocchi di registri) |
| autoGroupAllowGaps | No | BOOL | true, false | false | Ammette lacune all'interno di un blocco: i registri non necessari vengono letti insieme, invece di separare il blocco |
| maxRegisterGroup | No | INT | 1 - 125 | 125 | Numero massimo di registri di un blocco. Valori maggiori vengono limitati a 125 con un avvertimento — ModBus non ne consente di più in una transazione |
| useF23withoutOutputs | No | BOOL | true, false | false | Utilizza il codice funzione 23 (Read/Write Multiple Registers) anche quando non c'è nulla da scrivere (da smartCORE 2.12) |
| minimalChannelAlarmCount | No | INT | 1 - | 2 | Numero di tentativi falliti immediatamente consecutivi dopo il quale un blocco di registri viene disattivato (vedere Timeout e disattivazione) |
| retryAfterBlockFailS | No | INT | 0 - | 0 | Tempo di attesa [s] dopo il quale un blocco di registri disattivato viene ritentato. 0 = nessun nuovo tentativo, il blocco resta disattivato per la misura (da smartCORE 2.12) |
| workloadAsChannel | No | BOOL | true, false | false | Crea un canale diagnostico che riporta il carico del bus |
| workloadChannelBuffersize | No | INT | 1 - | 100 | Dimensione del buffer del canale del carico del bus in elementi |
| workloadChannel | No | STRING o JSON Objekt | Nome o definizione completa del canale del carico del bus |
Parametri di trasporto specifici di ModBus/TCP ("transport")
| Nome del parametro | Obbligatorio | Tipo di dati | Intervallo di valori sensato | Default | Descrizione |
|---|---|---|---|---|---|
| type | SÌ | STRING | "tcp" | Selezione di ModBus/TCP | |
| ipAddress | SÌ | STRING | Indirizzo IP valido | Indirizzo IP del dispositivo ModBus | |
| ipPortNumber | SÌ | INT | Numero di porta IP valido | Numero di porta IP del dispositivo ModBus (se non diversamente specificato, dovrebbe essere impostato su 502) | |
| timeoutInMilliseconds | SÌ | INT | 1 - | Timeout [ms] per la connessione TCP (se non diversamente specificato, dovrebbe essere impostato su 200) |
Parametri di trasporto specifici di ModBus/RTU ("transport")
| Nome del parametro | Obbligatorio | Tipo di dati | Intervallo di valori sensato | Default | Descrizione |
|---|---|---|---|---|---|
| type | SÌ | STRING | "rtu" | Selezione di ModBus/RTU | |
| baudRate | SÌ | INT | Baud rate ModBus valida | Baud rate dell'interfaccia seriale | |
| dataBits | SÌ | INT | 5 - 8 | Bit di dati dell'interfaccia seriale | |
| parity | SÌ | STRING | "no", "even", "odd" | Parità dell'interfaccia seriale | |
| stopBits | SÌ | DOUBLE | 1.0, 1.5, 2.0 | Bit di stop dell'interfaccia seriale | |
| portName | SÌ | STRING | Device file valido | File di dispositivo dell'interfaccia seriale | |
| timeoutInMilliseconds | SÌ | INT | 1 - | Timeout di risposta [ms] della connessione seriale. Limita il tempo di attesa della risposta di un nodo e viene passato a libmodbus come modbus_set_response_timeout() | |
| deviceTimeoutInMilliseconds | No | INT | 0 - | 0 | Timeout aggiuntivo [ms] tra le interrogazioni di nodi ModBus diversi |
| readDelayMs | No | INT | 0 - | Sovrascrive il silenzio di trama t3.5 [ms] mantenuto prima di ogni richiesta. Senza la chiave viene calcolato dalla baud rate (vedere Silenzio di trama) |
Parametri del dispositivo ModBus ("devices")
| Nome del parametro | Obbligatorio | Tipo di dati | Intervallo di valori sensato | Default | Descrizione |
|---|---|---|---|---|---|
| enable | SÌ | BOOL | true | Interruttore per l'attivazione del dispositivo ModBus | |
| deviceName | SÌ | STRING | Nome del dispositivo ModBus | ||
| deviceAddress | SÌ | INT | 1 - | Indirizzo del dispositivo ModBus | |
| readChannels | SÌ | JSON Array von JSON Objekten | vedere sotto |
Le chiavi autoGroup, autoGroupAllowGaps, maxRegisterGroup e useF23withoutOutputs
possono essere indicate anche per singolo dispositivo e sovrascrivono lì il valore globale.
Configurazione dei canali ModBus ("readChannels")
| Nome del parametro | Obbligatorio | Tipo di dati | Intervallo di valori sensato | Default | Descrizione |
|---|---|---|---|---|---|
| name | SÌ | STRING | Nome dello smartCHANNEL | ||
| address | SÌ | INT | Indirizzo del registro ModBus | ||
| registerType | SÌ | STRING | Tipo di registro ModBus valido | Tipo del registro ModBus ("InputReg", "HoldingReg", "Coil", "Status", "0x17" (solo accesso in lettura)) | |
| registerFormat | SÌ | STRING | Formato di registro ModBus valido | Formato del registro ModBus ("I8","I16","I32","I64","UI8","UI16","UI32","UI64","REAL","BOOL") | |
| byteOrder | SÌ | STRING | vedere sotto | Ordine dei byte del valore, vedere Ordine dei byte | |
| bitOffset | SÌ | UINT | Offset in bit del valore da interpretare | ||
| unit | SÌ | STRING | Unità dello smartCHANNEL | ||
| scale | SÌ | DOUBLE | Scalatura dello smartCHANNEL | ||
| offset | SÌ | DOUBLE | Offset dello smartCHANNEL | ||
| enable | No | BOOL | true, false | true | Un canale con false non viene né creato né letto |
| pollingIntervalMultiplicator | No | INT | 1 - | 1 | Il blocco di registri di questo canale viene letto solo in ogni n-esimo ciclo di interrogazione |
| registerGroup | No | INT | 0 - | Assegna manualmente il canale a un blocco di registri. I canali con lo stesso numero formano un blocco e vengono esclusi dal raggruppamento automatico |
Configurazione dei canali ModBus ("readChannelGroups")
In alternativa è possibile riunire più configurazioni di canale in un JSON Array, in modo che i registri ModBus alla base di questo gruppo possano essere letti in un unico passaggio (se il tipo di registro è identico). Questo array readChannelGroup così riunito può quindi essere elencato nel JSON Array di "readChannelGroups", ad es.
"readChannelGroups": [
[
{
"name": "Channel 1",
"address": 49152,
"registerType": "HoldingReg",
"registerFormat": "REAL",
"byteOrder": "ABCD",
"bitOffset": 0,
"unit": "",
"scale": 1.0,
"offset": 0.0
},
{
"name": "Channel 2",
"address": 49158,
"registerType": "HoldingReg",
"registerFormat": "REAL",
"byteOrder": "ABCD",
"bitOffset": 0,
"unit": "",
"scale": 1.0,
"offset": 0.0
}
]
]
In alternativa è possibile specificare "readChannels" oppure "readChannelGroups".
Blocchi di registri
I canali di un dispositivo non vengono letti singolarmente. smartCORE li riunisce in blocchi di registri: un blocco è un intervallo di indirizzi contiguo di un tipo di registro e viene letto in esattamente una transazione ModBus. Ogni canale è alimentato da esattamente un blocco.
Il raggruppamento avviene per tipo di registro e indirizzo. I quattro spazi di indirizzamento ModBus (Coil, Discrete Input, Input Register, Holding Register) sono indipendenti l'uno dall'altro — Coil 4 e Input Register 4 sono cose diverse e non finiscono mai nello stesso blocco. Un nuovo blocco inizia non appena
- l'intervallo comprenderebbe più di
maxRegisterGroupregistri, oppure - il registro successivo non segue immediatamente il precedente e
autoGroupAllowGapsè impostato sufalse.
Con autoGroupAllowGaps: true le lacune vengono colmate: il blocco legge anche registri di cui
nessun canale ha bisogno, ma risparmia così una transazione. Conviene con lacune piccole e accessi
costosi, non con indirizzi molto distanti tra loro.
Chi vuole stabilire da sé la suddivisione assegna registerGroup per ogni canale: i canali con lo stesso
numero formano un blocco e vengono esclusi dal raggruppamento automatico.
Ordine dei byte
Il valore di un canale viene estratto dal buffer letto dallo stesso componente usato nel
modulo fmProducer, il SimpleBufferPicker. byteOrder conosce quindi
due notazioni:
- Per nome —
bigEndian(anchebig,be,motorola,msb,network) oppurelittleEndian(anchelittle,le,intel,lsb). Senza indicazione vale Big Endian. - Come mappatura — una sequenza di lettere che porta i byte del valore nell'ordine in cui si trovano sul bus. La lunghezza della sequenza indica su quanti byte si estende il valore, l'ordine delle lettere come vanno scambiati.
Così si spiega anche la differenza tra "AB" e "BA": entrambi descrivono un
valore di due byte. "AB" li acquisisce nell'ordine letto, "BA" li scambia.
Analogamente con quattro byte: "ABCD" invariato, "CDAB" scambiato a parole, "DCBA"
completamente invertito — le quattro varianti con cui i dispositivi ModBus memorizzano i valori a 32 bit.
"BIT" è un caso speciale per l'accesso a un singolo bit. Una sequenza che non è né un
nome noto né una mappatura valida disattiva il canale; il messaggio lo indica
per nome.
Comportamento temporale e gestione degli errori
Ciclo di interrogazione
Il bus è servito da un thread dedicato che in ogni ciclo di interrogazione
(pollCycleInMilliseconds o pollCycleInNanoseconds) legge in sequenza tutti i blocchi di registri
in scadenza. Un blocco con pollingIntervalMultiplicator: n è in scadenza solo in ogni n-esimo ciclo;
i blocchi con lo stesso moltiplicatore vengono distribuiti su cicli diversi, in modo che
non coincidano tutti nello stesso ciclo.
Un blocco che in un ciclo non è in scadenza non produce nulla. Fino a smartCORE 2.11 veniva
invece emesso di nuovo il contenuto invariato del blocco con l'ora attuale — un
canale con pollingIntervalMultiplicator: 5 forniva così cinque volte più valori di quante misure
fossero state effettuate.
Timestamp dei valori misurati
Ogni canale porta il timestamp della transazione da cui proviene il suo valore: l'istante in cui è arrivata la risposta del dispositivo. Tutti i canali di un blocco di registri portano quindi lo stesso timestamp. L'istante in cui il dispositivo ha formato il valore o lo ha messo sulla linea non è osservabile tramite ModBus — l'arrivo della risposta è l'istante più vicino che il protocollo fornisce.
Fino a smartCORE 2.11 i valori portavano l'istante della loro emissione nello smartCHANNEL, non quello della misura — cioè l'istante successivo all'interrogazione di tutti i dispositivi sul bus, eventualmente in ritardo di diversi secondi.
Silenzio di trama con ModBus/RTU
Prima di ogni richiesta la linea viene mantenuta silenziosa per la durata del silenzio di trama t3.5 — la pausa che separa un messaggio RTU dal successivo. La sua durata risulta da:
| Condizione | Silenzio |
|---|---|
readDelayMs è impostato | il valore indicato |
| Baud rate superiore a 19200 (o sconosciuta) | 1,75 ms — il valore fisso della MODBUS over Serial Line Specification V1.02; quello calcolato si ridurrebbe a 0,33 ms a 115200 baud e non separerebbe più nulla |
| altrimenti | 3,5 caratteri da 11 bit, cioè 38500000 / baud rate microsecondi — 4,01 ms a 9600 baud |
La pausa si trova prima della richiesta. Fino a smartCORE 2.11 la pausa veniva fatta dopo una risposta riuscita — quindi proprio non dopo un timeout, e dunque non nel caso in cui la linea ha più bisogno del silenzio.
Due elementi vengono registrati nel log, perché indicano un impianto configurato troppo veloce: byte della richiesta precedente che all'avvio della successiva si trovano ancora nella coda di invio ("la linea è più lenta di quanto presuppone il ciclo di interrogazione"), e dati che si trovano inaspettatamente nel buffer di ingresso. Questi ultimi vengono letti e segnalati con i loro primi byte, non scartati silenziosamente.
Timeout e disattivazione di un blocco di registri
Se una richiesta non riceve risposta entro timeoutInMilliseconds, l'accesso è considerato
fallito. Il blocco di registri conta tali tentativi falliti e, dopo
minimalChannelAlarmCount tentativi falliti consecutivi, viene disattivato: non viene più
interrogato e i suoi canali non producono più nulla. Il messaggio indica dispositivo, indirizzo del registro,
codice funzione, la lunghezza della serie di errori e se è previsto un nuovo tentativo.
Non ogni errore conta ai fini di questa soglia:
| Risposta del dispositivo | Effetto |
|---|---|
| Nessuna risposta (timeout), Illegal Function (01), Illegal Data Address (02), Illegal Data Value (03), Server Failure (04), Negative Acknowledge (07), Memory Parity (08), Gateway Target Failed To Respond (0B) | conta ai fini della disattivazione — il dispositivo o la configurazione non sono permanentemente in ordine |
| Acknowledge (05), Server Busy (06), Gateway Path Unavailable (0A) | non conta — il dispositivo chiede pazienza |
| Trama danneggiata, ad es. errore CRC | non conta — un evento, non uno stato; ripetere la richiesta è la risposta corretta |
retryAfterBlockFailS decide se un blocco disattivato ritorna: con 0 resta
disattivato per la durata della misura, con un valore maggiore di zero viene ritentato dopo questo tempo.
Se il tentativo riesce, il blocco è di nuovo in funzione e il contatore è a zero;
se fallisce, il tempo di attesa ricomincia da capo.
Un dispositivo che sul campo occasionalmente scompare e ritorna ha bisogno di
retryAfterBlockFailS. Senza la chiave, dopo minimalChannelAlarmCount tentativi falliti
è finita, anche se il dispositivo due minuti dopo è di nuovo collegato al bus.
Informazioni sul modulo
| Informazione | Valore |
|---|---|
| Autori | optiMEAS GmbH |
| da smartCORE | 0.1 |
| Tipo di modulo | Producer |
| Dipendenze | NESSUNA |