Modbus Gateway Guide

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

Virtuino Cloud does not speak Modbus directly. Instead, a small gateway device on your local network polls your Modbus equipment and republishes the values over MQTT — the same MQTT broker and topic format documented in our MQTT Connection Guide. To the platform, data coming from a Modbus gateway is indistinguishable from data coming from an ESP32 — it's just another MQTT publisher.

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.

Modbus Devices

RTU (RS-485) or TCP

MQTT-Modbus Gateway

polls registers locally

cloud.virtuino.com

MQTT broker (outbound, TLS)

Your Dashboard

widgets update live

Why not connect Modbus TCP devices directly to the internet?
Modbus has no built-in authentication or encryption. Exposing a Modbus TCP gateway directly to the public internet (via port-forwarding) is a well-known security risk — it can be discovered and controlled by anyone who finds the open port. Always keep Modbus traffic local, and let a gateway relay it out over authenticated, encrypted MQTT instead.

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:

Parameter	Value	Notes
*Broker Host	cloud.virtuino.com	Same host for both plain and TLS connections
*Port	8883 TLS / SSL	Recommended — most gateways support TLS out of the box. Use 1883 only for local testing.
*Username	`vr-abcd1234`	Your Sub-account Key — found in Console → API & Connections
*Password	your MQTT password	Found in Console → API & Connections → MQTT Credentials
Client ID	`vr-abcd1234_gateway`	Must begin with your Sub-account Key as prefix; the suffix is arbitrary

* Required field

3Mapping Modbus Registers to Topics

Most MQTT-Modbus gateways let you define, per register, which MQTT topic to publish to. Map each register to a topic under your namespace using the same /in/ (device → cloud) and /out/ (cloud → device) convention used everywhere else on the platform — see Topic Structure for the full reference.

Devices & Fields must exist first: Before mapping a register to a topic, create the matching Device and Field in the Virtuino Cloud Console (Console → Devices). The names must match exactly what you use in the topic, or the broker will ignore the message.

Modbus Register Register Type Topic to Publish

Holding Register 30001 (temperature) Read (device → cloud) vr-abcd1234/in/device/plc1/temperature

Holding Register 30002 (humidity) Read (device → cloud) vr-abcd1234/in/device/plc1/humidity

Coil 00001 (relay) Write (cloud → device) vr-abcd1234/out/device/plc1/relay1

Modbus Register	Register Type	Topic to Publish
Holding Register 30001 (temperature)	Read (device → cloud)	`vr-abcd1234/in/device/plc1/temperature`
Holding Register 30002 (humidity)	Read (device → cloud)	`vr-abcd1234/in/device/plc1/humidity`
Coil 00001 (relay)	Write (cloud → device)	`vr-abcd1234/out/device/plc1/relay1`

For coils/registers the gateway should write to (e.g. a relay controlled from your dashboard), subscribe to the corresponding /out/ topic instead of publishing to it — the gateway receives the value from Virtuino Cloud and writes it to the Modbus register.

Tip: Use Format 2 (Device Path) from the MQTT guide ({sub_account_key}/in/device/{device_name}/{sensor_name}) when bridging Modbus — it keeps every PLC/gateway's registers grouped under its own device name, which scales much better than the flat format once you have more than a handful of registers.

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 the built-in MQTT-out node to build a fully custom polling/mapping flow on a Raspberry Pi or similar.
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/subscribing to topics under your own namespace.