Documentazione ELX-MODBUS — gateway, dispositivi, registri e MQTT

Installazione

Scaricate il pacchetto per la vostra architettura e installatelo. apt è preferibile a dpkg, perché risolve ciò di cui il pacchetto ha bisogno.

Installare

sudo apt install ./elxmodbusmqtt_1.2.38_amd64.deb
systemctl status elxmodbusmqtt
xdg-open http://localhost:8080

Quale pacchetto vi serve lo dice uname -m: x86_64 è amd64, aarch64 è arm64, armv7l è armhf.

Servizio e registro

systemctl status elxmodbusmqtt
journalctl -u elxmodbusmqtt -f
sudo systemctl restart elxmodbusmqtt

Aggiungere un gateway

Un gateway è la via fisica verso il bus. Tutto ciò che sta sotto — dispositivi e registri — viene interrogato attraverso di esso, una richiesta alla volta.

Tipo	Cosa inserire
Modbus TCP	L'indirizzo e la porta del dispositivo, di solito 502
RTU su TCP	L'indirizzo e la porta del convertitore da Ethernet a RS-485
RTU seriale	La porta (`/dev/ttyUSB0`), la velocità, la parità, i bit di dati e di stop

Permessi sulla porta serialeSu Linux la porta appartiene di solito al gruppo dialout. Se il terminale mostra soltanto scadenze di tempo e il cablaggio è a posto, verificate che l'utente del servizio possa aprire il dispositivo.

Due gateway invece di unoDispositivi su bus fisici distinti appartengono a gateway distinti: così vengono interrogati in parallelo invece che a turno, e un dispositivo che smette di rispondere non rallenta gli altri.

Dispositivi e registri

Un dispositivo ha un indirizzo sul bus, un nome, un prefisso MQTT e un elenco di registri. Scegliere un modello dalla biblioteca riempie l'elenco; un dispositivo personalizzato parte vuoto.

Campo	Significato
Tipo di registro	Holding e Coil sono scrivibili; Input e Discrete sono di sola lettura
Indirizzo	Il numero di registro come sta nella scheda tecnica — attenzione all'origine, alcuni costruttori contano da uno
Tipo di dato	int16, uint16, int32, float32, stringa o un singolo bit
Ordine delle parole	Quale metà di un valore a 32 bit viene prima; la causa abituale di numeri poco credibili
Moltiplicatore e scostamento	Trasformano un conteggio grezzo in un'unità reale: 0,1 fa di 245 il valore 24,5
Maschera di bit	Estrae un singolo contrassegno da una parola di stato compattata
Periodo	Ogni quanto viene interrogato proprio questo registro, se deve differire dal dispositivo

Un valore sbagliato di un fattore o rovesciatoQuasi tutti questi casi hanno tre cause: moltiplicatore sbagliato, ordine delle parole invertito, oppure un valore con segno letto come senza segno. Il terminale mostra la trama grezza e chiude la questione in pochi secondi.

Il broker

Indirizzo e porta. L'host e la porta del broker; il TLS è disponibile dove il broker lo offre.
Credenziali. Nome e password, se il broker le richiede.
Argomento di base. Il prefisso sotto cui compare tutto ciò che questo servizio pubblica — per esempio home.
Conservazione. Se il broker debba tenere l'ultimo valore di ogni argomento.
Argomenti di comando. Il suffisso che accetta la scrittura, /set in modo predefinito.

L'argomento completo si compone come {base}/{prefisso del dispositivo}/{chiave del registro}, il che lo rende prevedibile dalla sola configurazione — la sottoscrizione in Home Assistant si può scrivere prima ancora che il dispositivo sia cablato.

Quale brokerUno qualsiasi, purché standard. Se non ne avete ancora uno, ELX-MQTT Broker è su questo sito e si installa con la stessa facilità.

Il terminale di protocollo

Il terminale mostra ogni richiesta e ogni risposta come trame grezze, con tempi ed errori. È lo strumento dei due momenti più difficili: mettere in funzione un dispositivo che nessuno ha descritto e spiegare perché ciò che funzionava ha smesso.

Cosa si vede	Cosa significa di solito
Scadenza di tempo a ogni richiesta	Porta sbagliata, velocità sbagliata, fili A e B invertiti, oppure dispositivo senza alimentazione
Scadenza di tempo su un solo dispositivo	Indirizzo sul bus sbagliato, oppure quel dispositivo non è collegato
Eccezione 02	Quell'indirizzo di registro non esiste su questo dispositivo
Eccezione 03	Il valore scritto è fuori dall'intervallo che il dispositivo accetta
Errori CRC sotto carico	Cavo troppo lungo, resistenze di terminazione mancanti, o velocità che la linea non regge

Salvataggio e ripristino

L'intera configurazione — gateway, dispositivi, mappe dei registri e impostazioni del broker — si esporta in un file JSON e si ripristina da quello. Quel file è anche il modo giusto per copiare un impianto funzionante su una seconda macchina, o per mettere la configurazione di un sito sotto controllo di versione.

Quando qualcosa non va

Sintomo	Dove guardare
L'interfaccia web non si apre	`systemctl status elxmodbusmqtt`; il servizio potrebbe non aver preso la porta 8080
I valori compaiono nell'interfaccia ma non in MQTT	La pubblicazione è disattivata, oppure le credenziali del broker sono sbagliate — il registro degli eventi dice quale delle due
Un comando in `/set` non cambia nulla	Il canale è di sola lettura, oppure il registro è un Input e non un Holding
I valori si aggiornano troppo lentamente	Troppi registri su un gateway con lo stesso periodo; alzatelo per quelli che non cambiano
I numeri oscillano fra plausibili e assurdi	L'ordine delle parole, oppure due master sullo stesso bus che si rispondono a vicenda

Documentazione