Documentation ELX-MODBUS — passerelles, registres et MQTT

Installation

Téléchargez le paquet correspondant à votre architecture et installez-le. apt est préférable à dpkg, car il résout ce dont le paquet a besoin.

Installer

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

uname -m vous indique le paquet nécessaire : x86_64 pour amd64, aarch64 pour arm64, armv7l pour armhf.

Service et journal

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

Ajouter une passerelle

Une passerelle est le chemin physique vers le bus. Tout ce qui se trouve dessous — appareils et registres — est interrogé par elle, une requête à la fois.

Type	Ce qu'il faut saisir
Modbus TCP	L'adresse et le port de l'appareil, en général 502
RTU sur TCP	L'adresse et le port du convertisseur Ethernet vers RS-485
RTU série	Le port (`/dev/ttyUSB0`), la vitesse, la parité, les bits de données et d'arrêt

Droits sur le port sérieSous Linux, le port appartient d'ordinaire au groupe dialout. Si le terminal ne montre que des dépassements de délai alors que le câblage est bon, vérifiez que le compte du service peut ouvrir le périphérique.

Deux passerelles plutôt qu'uneDes appareils sur des bus physiques distincts relèvent de passerelles distinctes : ils sont alors interrogés en parallèle au lieu de l'être à tour de rôle, et un appareil qui cesse de répondre ne ralentit pas les autres.

Appareils et registres

Un appareil a une adresse esclave sur le bus, un nom, un préfixe MQTT et une liste de registres. Choisir un modèle dans la bibliothèque remplit la liste ; un appareil personnalisé part de zéro.

Champ	Signification
Type de registre	Holding et Coil sont inscriptibles ; Input et Discrete sont en lecture seule
Adresse	Le numéro de registre tel qu'il figure dans la notice — attention à l'origine, certains constructeurs comptent à partir de un
Type de données	int16, uint16, int32, float32, chaîne ou un bit unique
Ordre des mots	Quelle moitié d'une valeur 32 bits vient en premier ; la cause habituelle des nombres invraisemblables
Multiplicateur et décalage	Transforment un comptage brut en unité réelle : 0,1 fait de 245 la valeur 24,5
Masque de bits	Extrait un drapeau d'un mot d'état compacté
Période	À quelle fréquence ce registre est interrogé, s'il doit différer de l'appareil

Une valeur décalée d'un facteur ou inverséePresque tous ces cas tiennent à trois causes : mauvais multiplicateur, ordre des mots inversé, ou valeur signée lue comme non signée. Le terminal montre la trame brute et tranche la question en quelques secondes.

Le courtier

Adresse et port. L'hôte et le port du courtier ; le TLS est disponible là où le courtier le propose.
Identifiants. Nom et mot de passe, si le courtier les exige.
Sujet de base. Le préfixe sous lequel apparaît tout ce que ce service publie — home, par exemple.
Conservation. Si le courtier doit garder la dernière valeur de chaque sujet.
Sujets de commande. Le suffixe qui accepte l'écriture, /set par défaut.

Le sujet complet s'écrit {base}/{préfixe de l'appareil}/{clé du registre}, ce qui le rend prévisible à partir de la seule configuration — l'abonnement dans Home Assistant peut être écrit avant même que l'appareil ne soit câblé.

Quel courtierN'importe lequel, pourvu qu'il soit standard. Si vous n'en avez pas encore, ELX-MQTT Broker figure sur ce site et s'installe tout aussi facilement.

Le terminal de protocole

Le terminal montre chaque requête et chaque réponse sous forme de trames brutes, avec les durées et les erreurs. C'est l'outil des deux moments les plus difficiles : mettre en service un appareil que personne n'a décrit, et expliquer pourquoi ce qui fonctionnait ne fonctionne plus.

Ce que vous voyez	Ce que cela signifie d'ordinaire
Dépassement de délai à chaque requête	Mauvais port, mauvaise vitesse, fils A et B inversés, ou appareil non alimenté
Dépassement de délai sur un seul appareil	Mauvaise adresse esclave, ou cet appareil n'est pas sur le bus
Exception 02	Cette adresse de registre n'existe pas sur cet appareil
Exception 03	La valeur écrite sort de la plage acceptée par l'appareil
Erreurs CRC en charge	Câble trop long, résistances de terminaison absentes, ou vitesse que la ligne ne supporte pas

Sauvegarde et restauration

Toute la configuration — passerelles, appareils, plans de registres et réglages du courtier — s'exporte dans un fichier JSON et s'y restaure. Ce fichier est aussi la bonne façon de recopier une installation qui fonctionne sur une seconde machine, ou de placer la configuration d'un site sous gestion de versions.

Quand quelque chose ne va pas

Symptôme	Où regarder
L'interface web ne s'ouvre pas	`systemctl status elxmodbusmqtt` ; le service n'a peut-être pas pu prendre le port 8080
Les valeurs apparaissent dans l'interface mais pas dans MQTT	La publication est désactivée, ou les identifiants du courtier sont faux — le journal d'événements dit lequel
Une commande dans `/set` ne change rien	La voie est en lecture seule, ou le registre est un Input et non un Holding
Les valeurs se rafraîchissent beaucoup trop lentement	Trop de registres sur une passerelle à la même période ; augmentez-la pour ceux qui ne changent pas
Les nombres oscillent entre plausibles et absurdes	L'ordre des mots, ou deux maîtres sur le même bus qui se répondent l'un par-dessus l'autre

Documentation