Documentación de ELX-MODBUS — pasarelas, registros y MQTT

Instalación

Descargue el paquete de su arquitectura e instálelo. apt es preferible a dpkg, porque resuelve lo que el paquete necesita.

Instalar

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

Qué paquete necesita se lo dice uname -m: x86_64 es amd64, aarch64 es arm64, armv7l es armhf.

Servicio y registro

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

Añadir una pasarela

Una pasarela es el camino físico hasta el bus. Todo lo que está por debajo — dispositivos y registros — se interroga a través de ella, una petición cada vez.

Tipo	Qué hay que introducir
Modbus TCP	La dirección y el puerto del dispositivo, normalmente 502
RTU sobre TCP	La dirección y el puerto del convertidor de Ethernet a RS-485
RTU serie	El puerto (`/dev/ttyUSB0`), la velocidad, la paridad, los bits de datos y de parada

Permisos sobre el puerto serieEn Linux el puerto suele pertenecer al grupo dialout. Si el terminal solo muestra tiempos agotados y el cableado está bien, compruebe que el usuario del servicio puede abrir el dispositivo.

Dos pasarelas en vez de unaLos dispositivos de buses físicos distintos corresponden a pasarelas distintas: así se interrogan en paralelo en vez de por turnos, y un dispositivo que deja de responder no frena a los demás.

Dispositivos y registros

Un dispositivo tiene una dirección en el bus, un nombre, un prefijo MQTT y una lista de registros. Elegir una plantilla de la biblioteca rellena la lista; un dispositivo propio empieza vacío.

Campo	Significado
Tipo de registro	Holding y Coil se pueden escribir; Input y Discrete son de solo lectura
Dirección	El número de registro tal como figura en la hoja de datos — atención al origen, algunos fabricantes cuentan desde uno
Tipo de dato	int16, uint16, int32, float32, cadena o un solo bit
Orden de palabras	Qué mitad de un valor de 32 bits va primero; la causa habitual de números inverosímiles
Multiplicador y desplazamiento	Convierten un recuento en bruto en una unidad real: 0,1 hace que 245 sea 24,5
Máscara de bits	Extrae una marca de una palabra de estado compactada
Periodo	Cada cuánto se interroga precisamente este registro, si debe diferir del dispositivo

Un valor desviado por un factor o al revésCasi todos esos casos tienen tres causas: multiplicador equivocado, orden de palabras invertido, o un valor con signo leído como sin signo. El terminal muestra la trama en bruto y zanja la cuestión en segundos.

El broker

Dirección y puerto. El anfitrión y el puerto del broker; el TLS está disponible donde el broker lo ofrece.
Credenciales. Nombre y contraseña, si el broker los exige.
Tema base. El prefijo bajo el que aparece todo lo que este servicio publica — home, por ejemplo.
Retención. Si el broker debe conservar el último valor de cada tema.
Temas de orden. El sufijo que acepta escritura, /set por omisión.

El tema completo se forma como {base}/{prefijo del dispositivo}/{clave del registro}, lo que lo hace previsible solo con la configuración — la suscripción en Home Assistant puede escribirse antes incluso de que el dispositivo esté cableado.

Qué brokerCualquiera, siempre que sea estándar. Si aún no tiene uno, ELX-MQTT Broker está en este sitio y se instala con la misma facilidad.

El terminal de protocolo

El terminal muestra cada petición y cada respuesta como tramas en bruto, con tiempos y errores. Es la herramienta de los dos momentos más difíciles: poner en marcha un dispositivo que nadie ha descrito y explicar por qué lo que funcionaba ha dejado de hacerlo.

Lo que se ve	Lo que suele significar
Tiempo agotado en cada petición	Puerto equivocado, velocidad equivocada, hilos A y B invertidos, o dispositivo sin alimentación
Tiempo agotado en un solo dispositivo	Dirección en el bus equivocada, o ese dispositivo no está conectado
Excepción 02	Esa dirección de registro no existe en este dispositivo
Excepción 03	El valor escrito está fuera del intervalo que el dispositivo acepta
Errores de CRC bajo carga	Cable demasiado largo, resistencias de terminación ausentes, o velocidad que la línea no soporta

Copia de seguridad y restauración

Toda la configuración — pasarelas, dispositivos, mapas de registros y ajustes del broker — se exporta a un archivo JSON y se restaura desde él. Ese archivo es además la forma correcta de copiar una instalación que funciona a una segunda máquina, o de poner la configuración de una obra bajo control de versiones.

Cuando algo no va

Síntoma	Dónde mirar
La interfaz web no se abre	`systemctl status elxmodbusmqtt`; puede que el servicio no haya podido tomar el puerto 8080
Los valores aparecen en la interfaz pero no en MQTT	La publicación está desactivada, o las credenciales del broker son erróneas — el registro de sucesos dice cuál de las dos
Una orden en `/set` no cambia nada	El canal es de solo lectura, o el registro es un Input y no un Holding
Los valores se actualizan demasiado despacio	Demasiados registros en una pasarela con el mismo periodo; súbalo para los que no cambian
Los números oscilan entre verosímiles y absurdos	El orden de palabras, o dos maestros en el mismo bus respondiéndose uno sobre otro

Documentación