Modbus TCP to MQTT: read registers and publish them to your broker

Steps

1. 01

   Open the device wizard and choose Modbus TCP

   Go to Connect > Devices and select New. Choose the Edge Gateway on the machine’s network: the connection is tested from that gateway. Type modbus in the protocol search box, select the Modbus TCP card (Modbus RTU Over TCP or Modbus ASCII Over TCP for a serial device behind a device server), then select Next: Connection.

   Docs: Add a device

   

2. 02

   Enter the address and test the connection

   Enter the machine’s IP address as the gateway sees it. Leave Port empty to use port 502. Protocol settings such as the unit ID and byte order are shown with the address, less common ones under Advanced. Leave Read every at Profile default unless you need faster or slower reads, then select Test the connection. The gateway itself tries to reach the machine and shows each check: whether it reached the address, and whether the machine accepted the protocol session.

   Docs: Add a device

   

3. 03

   Paste the registers

   On the Paste tab, paste one tag per line with the columns name, address, type and unit, separated by tabs (as Excel copies them), commas or semicolons, and select Add to the list. Datasheet numbers are converted: 40001 becomes x=3;0 (holding register 0), 30001 becomes x=4;0 (input register 0), 10001 becomes x=2;0 (discrete input) and 1 becomes x=1;0 (coil).

   Docs: Add a device

   

4. 04

   Read every tag once

   Check the table and select Read all once: the gateway reads every tag one time and shows the value next to it, and a wrong address shows its error on the row. The Address helper builds an address from a register number so it cannot be mistyped. Enter a Profile name so the next device of this model reuses the registers.

   Docs: Add a device

   

5. 05

   Name and place the device, then save

   In Place and type, enter a unique Device name, fill in the Place from Enterprise down to Equipment module (every level is optional) and choose the Device type, which Proxus does not guess. The place decides where the device appears in the Unified Namespace. Select Save and verify: the stages Saved, Sent, Device connected and First values turn green in order, and each tag shows its first value.

   Docs: Add a device

6. 06

   Create the MQTT target for your broker

   Go to Connect > Outbound Targets, switch the filter to All, open the MQTT sample and select Clone.... Enter a unique Profile Name, then select Edit Parameters and fill in Broker Host and Broker Port (1883 by default). Set Topic to the topic to publish to; left empty, values go to proxus_device_data. Username and Password are used only when both are set. For TLS, turn on Use TLS, use port 8883 and choose the broker’s CA as Trusted Server Certificate. Under Transport Strategy, Pass Through sends every value read and On Change only values that changed. Select Save.

   Docs: Outbound targets

   

7. 07

   Check the target from the gateway

   On the saved target, select Check. Under Run Probe On, choose the gateway that reads the device rather than the hub: the gateway is what sends the data, and a target that only the plant network can reach fails from the hub. The Configuration Check lists errors and warnings without contacting the target. Test Connection then connects without sending data and reports Connected, Reachable or Failed with the reason.

   Docs: Outbound targets

   

8. 08

   Send the device’s values to the target

   In Connect > Devices, select the device (or several), then Targets > Add Target and choose the target. For one device you can also use the Delivery tab on its page; a new device can tick the target under Where does the data go? in the wizard. The target’s Devices count goes up, and its Status turns green after the first delivery.

   Docs: Outbound targets

Verify the data

• In the wizard’s last step, the stages complete in order and each tag shows its first value. Add a device
• Open the device. On the Live values tab every tag shows its value, a small trend, its Quality and when it was updated. Good means the value was read without error. The device page
• Open Organize > UNS Explorer, type the device name in Search... and press Enter, then right-click a node and choose Expand All. The device sits at the place you gave it, each tag with its current value, trend and update time. UNS Explorer
• Subscribe to the target’s Topic on your broker with any MQTT client: each reading arrives there as JSON. Each gateway also publishes the same values on its built-in broker; subscribe to v1/# with the gateway’s MasterToken as user name (port 1883, or 8883 with TLS). MQTT and the UNS topics
• On the target, Status is green, and Last Success is renewed about once a minute while the target keeps delivering. Outbound targets

Common problems

Every value is off by one register

Datasheets count from 1, the protocol from 0. In Proxus, 40001 means holding register 0 (x=3;0). Troubleshoot devices

Numbers are far too large or tiny, such as 1.0836943E-38

The data type or the byte order does not match the device. Check the type (Float against Int) and the profile’s byte order setting. Troubleshoot devices

Modbus Bool tags should usually use coil/discrete input areas, not holding/input registers.

Proxus recognizes common Modbus mistakes and says so on the tag. Another one: The Modbus address format is invalid. Expected patterns are like x=3;100 for holding registers. Troubleshoot devices

The device refused the session.

The network is fine, but the device did not accept the protocol. Check the unit ID, and that the device is not limited to one client that is already connected. Troubleshoot devices

The gateway cannot reach the device.

There is no TCP connection: a wrong address or port, the device is off, or a firewall or VLAN is in between. The test runs on the gateway, so check reachability from the gateway’s host, not from your own computer. Troubleshoot devices

The broker is down for a while

Data is not lost. The gateway writes it to its own durable queue first and removes it only after the target has taken it; when the target is back, the waiting data is written in order. It waits for the gateway’s Buffer Retention (hours): 48 hours by default, up to 30 days. Outbound targets

Next steps

• Modbus driver: TCP, RTU and ASCII over TCP →
• MQTT and Sparkplug B integration →
• MQTT and the UNS topics →
• Import many devices from a spreadsheet →
• Device profiles: the next machine of the same kind →