ELX-MODBUS documentation — gateways, devices, registers and MQTT

Installation

Download the package for your architecture and install it. apt is preferred over dpkg because it resolves anything the package needs.

Installing

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

uname -m tells you which package you need: x86_64 is amd64, aarch64 is arm64, armv7l is armhf.

Service and logs

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

Adding a gateway

A gateway is the physical path to the bus. Everything below it — devices and registers — is polled through it, one request at a time.

Type	What to enter
Modbus TCP	The address and port of the device, usually 502
RTU over TCP	The address and port of the Ethernet-to-RS-485 converter
Serial RTU	The port (`/dev/ttyUSB0`), baud rate, parity, data and stop bits

Permission to the serial portOn Linux the port usually belongs to the dialout group. If the terminal shows nothing but timeouts and the cabling is right, check that the service user may open the device.

Two gateways instead of oneDevices on separate physical buses belong to separate gateways: they are then polled in parallel instead of taking turns, and a device that stops answering does not slow down the rest.

Devices and registers

A device has a slave address on the bus, a name, an MQTT prefix and a list of registers. Choosing a template from the library fills the register list in; a custom device starts empty.

Field	Meaning
Register type	Holding and Coil can be written; Input and Discrete are read-only
Address	The register number as printed in the datasheet — mind the base, some vendors count from 1
Data type	int16, uint16, int32, float32, string, or a single bit
Word order	Which half of a 32-bit value comes first; the usual cause of implausible numbers
Multiplier and offset	Turn a raw count into a real unit: 0.1 turns 245 into 24.5
Bit mask	Extracts one flag from a packed status word
Interval	How often this register is polled, if it should differ from the device

A value that is out by a factor or reversedThree causes cover almost every case: the multiplier is wrong, the word order is swapped, or the value is signed and being read as unsigned. The terminal shows the raw frame, which settles the question in seconds.

The broker

Address and port. The broker's host and port; TLS is available where the broker offers it.
Credentials. Username and password, if the broker requires them.
Base topic. The prefix under which everything this service publishes appears — home, for instance.
Retain. Whether the broker should keep the last value of each topic.
Command topics. The suffix that accepts writes, /set by default.

The full topic is {base}/{device prefix}/{register key}, which makes it predictable from the configuration alone — you can write the subscription in Home Assistant before the device is even wired.

Which brokerAny standard one. If you do not have one yet, ELX-MQTT Broker is on this site and installs as easily.

The protocol terminal

The terminal shows every request and every answer as raw frames, with timing and errors. It is the tool for the two hardest moments: bringing up a device nobody has described, and explaining why a device that used to work has stopped.

What you see	What it usually means
Timeout on every request	Wrong port, wrong baud rate, reversed A/B wiring, or no power to the device
Timeout on one device only	Wrong slave address, or that device is off the bus
Exception 02	The register address does not exist on this device
Exception 03	The value written is outside the range the device accepts
CRC errors under load	Cable too long, missing termination resistors, or a baud rate the line cannot carry

Backup and restore

The whole configuration — gateways, devices, register maps and broker settings — exports to one JSON file and restores from it. That file is also the right way to copy a working setup onto a second machine, or to keep the configuration of an installation in version control.

When something is wrong

Symptom	Where to look
The web interface does not open	`systemctl status elxmodbusmqtt`; the service may have failed to bind port 8080
Values appear in the interface but not in MQTT	Publishing is switched off, or the broker credentials are wrong — the event log says which
A command in `/set` changes nothing	The channel is read-only, or the register is an Input rather than a Holding register
Values update far too slowly	Too many registers on one gateway at one interval; raise the interval for the ones that do not change
Numbers jump between plausible and absurd	Word order, or two masters on the same bus answering over each other

Frequently asked questions

Where is the configuration stored?

In a SQLite database in the service's working directory. It can be exported to JSON from the interface, and that export is the file to keep.

Can several instances run on one machine?

Yes, with different web ports and different working directories — useful when two buses must stay strictly separate.

Does it need a broker on the same machine?

No. The broker can be anywhere reachable over the network.

Documentation