Modbus Gateway Guide

Bring Modbus RTU / Modbus TCP devices into Virtuino Cloud — no native Modbus support needed, thanks to MQTT-to-Modbus gateways.

1How It Works

Most Modbus RTU devices live on an isolated RS-485 serial bus, and most Modbus TCP gateways sit behind your local router's firewall with no public IP — our cloud servers can't simply "dial in" to reach them. An MQTT-to-Modbus gateway solves this the other way around: it makes an outbound connection from your network to our broker, so no port-forwarding or exposing your equipment to the internet is required.

2Gateway Connection Parameters

Configure your MQTT-to-Modbus gateway's MQTT client / MQTT publisher settings exactly as you would for any device connecting to Virtuino Cloud — see the full MQTT Connection Guide for details on every field. The essentials:

* Required field

3Mapping Modbus Registers to Topics

Most MQTT-Modbus gateways let you define, per register, which MQTT topic to publish or subscribe to. In Virtuino Cloud a topic is simply the name of a field — plc1/temperature is one field. There is nothing else to add to the topic; see Topic Structure for the full reference.

Reading registers (PLC → cloud)

The gateway polls the register and publishes its value to the field's topic. The best payload is the plain value — 23.5, not {"value":23.5} — because it is stored exactly as it arrives.

• Scaling. Registers usually hold whole numbers — 235 for 23.5 °C. Use the gateway's scale or multiplier setting if it has one. Otherwise publish the raw value to a field such as plc1/temp_raw and let a script write the converted value to plc1/temperature.
• JSON payloads. Many gateways can only send JSON, often several registers in one message: {"temperature":23.5,"humidity":61}. Publish that message to one field, e.g. plc1/data, and set up a JSON Splitter (dashboard → Tools → JSON Splitter) that writes each value to its own field. Make plc1/data a standard field — historical fields accept at most 512 characters.
• How often. Poll only as fast as you need. A temperature every 10–60 seconds is plenty; publishing every second to a historical field fills your storage quickly. Many gateways can also publish only when the value changes.

Writing registers and coils (cloud → PLC)

For a register or coil the gateway must write — a setpoint, a relay — the gateway subscribes to the field's topic. Whenever a value is written to that field with Publish via MQTT on — by a dashboard widget, a rule, a script or a scheduler — the gateway receives it and writes it to the PLC.

• Plain values. The gateway receives the value as plain text, e.g. 1 or 21.5. Check that your gateway accepts a plain value on its write topic.
• After a restart the gateway receives the last value of every subscribed field straight away, so relays and setpoints return to their commanded state without waiting for the next command.
• Confirmation. If the gateway reads the coil back after writing it and publishes the result on the same topic, you can turn on command confirmation for that field. The dashboard then shows a command only once the PLC has really applied it.

4Choosing a Gateway

Any MQTT-to-Modbus gateway works, as long as it can publish/subscribe to a standard MQTT broker over TLS with username/password authentication. Common options:

• Commercial industrial gateways — many RS-485/Modbus-TCP-to-MQTT gateway modules are available from industrial automation vendors; look for one that supports configurable MQTT topics per register and TLS.
• Node-RED — combine a Modbus-reading node (e.g. node-red-contrib-modbus) with Node-RED's built-in mqtt out and mqtt in nodes to build a fully custom polling/mapping flow on a Raspberry Pi or similar — see the Node-RED tutorial for a ready flow.
• Custom scripts — a small Python/Node.js service using a Modbus library (e.g. pymodbus) alongside an MQTT client library is straightforward to run on a Raspberry Pi or industrial PC if you need full control over polling logic.

Whichever option you choose, the connection to Virtuino Cloud is always the same: standard MQTT, TLS on port 8883, authenticated with your Sub-account Key and MQTT password, publishing and subscribing to the names of your fields.

5Troubleshooting