Waveshare Gateway: ModbusTCP Mode vs Transparent Mode (8899)

Waveshare’s RS-485-to-Ethernet gateways ship with two completely different operating modes, and picking the wrong one is why your QModMaster connection either works perfectly or fails in confusing ways. This guide explains ModbusTCP conversion mode (port 502) vs transparent transmission mode (port 8899), which one to choose, and exactly how to configure QModMaster for each.

Mode 1: ModbusTCP conversion mode (port 502)

In conversion mode the gateway is a protocol translator. On the Ethernet side it speaks real Modbus TCP — it parses the 7-byte MBAP header, reads the Unit ID byte, and rebuilds the request as a Modbus RTU frame on the RS-485 bus addressed to that slave. Replies travel the reverse path. This is the mode that makes multi-slave setups work: each Unit ID in your TCP request reaches a different RTU device (see our Unit ID gateway guide for the details).

Choose conversion mode when your master software speaks native Modbus TCP — which includes QModMaster’s TCP mode. The Home Assistant community documents this split clearly: integrations use type: tcp against Waveshare gateways in conversion mode, while type: rtuovertcp is reserved for transparent bridges (see the ha-toshiba-modbus docs, which spell out exactly this mapping).

Mode 2: Transparent transmission mode (port 8899)

In transparent mode the gateway is a dumb pipe: raw RS-485 bytes go in one end and come out the other, wrapped in nothing but a TCP stream. There is no MBAP header, no Unit ID parsing, no protocol conversion. Whatever bytes your software sends to port 8899 appear verbatim on the RS-485 bus.

This is the mode behind the well-known port 8899 in the Home Assistant world — Waveshare gateways in transparent mode are reached as “raw RTU over TCP”, which is why HA configs use rtuovertcp for them (documented in the Solis-Local gateway docs: TCP⇔RTU conversion vs transparent raw-RTU-over-TCP). Choose transparent mode when your master only speaks Modbus RTU and you want the Ethernet link to behave exactly like a very long serial cable.

How to connect each mode from QModMaster

Here is the part that trips everyone up: QModMaster only offers two modes — RTU (serial port) and TCP. It has no native RTU-over-TCP option. So the correct QModMaster setup depends entirely on the gateway mode:

• Gateway in ModbusTCP conversion mode → QModMaster in TCP mode. Enter the gateway IP, port 502, and set the Slave ID field to the Unit ID of the device you want (this fills the MBAP Unit ID byte). This is the straightforward, recommended combination for QModMaster users.
• Gateway in transparent mode (8899) → QModMaster in RTU mode via a virtual serial port. Since QModMaster can’t send raw RTU frames over TCP by itself, install a virtual COM port driver that maps a virtual serial port to the gateway’s IP:8899, then open that virtual port in QModMaster’s RTU mode with the correct baud/parity settings. The gateway then acts as a transparent serial extension.

The most common misconfiguration: the gateway sits in transparent mode on 8899 while QModMaster connects in TCP mode to 502 — QModMaster sends MBAP-framed requests into a pipe that forwards the bytes raw, the slaves see garbage framing, and nothing answers. Match the QModMaster mode to the gateway mode and the problem disappears.