Modbus TCP

The Modbus TCP configuration pages define Modbus devices and Modbus variables. Start by creating the device connection settings, then create the variables that map to coils, discrete inputs, input registers, or holding registers.

Use Modbus device entries for endpoint information such as address, port, and communication behavior. Use Modbus variable entries for register-level mapping, datatype, scaling, and naming.

Keep register maps grouped logically and name variables according to plant function instead of raw register number only. This makes later troubleshooting easier.

Device Settings

Each Modbus TCP device defines a connection to a Modbus TCP slave (server). Configure the connection endpoint, timing, and data handling options.

Create a new device with the Add button in the toolbar. The Add device dialog contains all device settings organized in the sections General, Connection, Scanning, Byte order, and Diagnostics, with default values already filled in. Enter at least the Name and IP Address and press Create.

The device row shows Enable, Name, IP Address, Port, Unit ID, Scan Rate, Template, and Description directly and these values can be edited in place. Press the Settings icon on a device row to open the Edit device dialog, which contains the same sections and all settings of the device. Press Save to apply the changes.

Variable Settings

Each Modbus TCP variable maps a single register address to a named variable in the EnvisionSCADA namespace.

Create a new variable with the Add button in the toolbar. The Add variable dialog organizes all variable settings in the tabs General, Scaling, Historian, and Gateway, with default values already filled in. Enter at least the Name and Address on the General tab and press Create. When the variable is created on a template device, it is also created on all instance devices that use the template. On a template device, start the Name with the {Device} replacer, so that each instance device gets its own variable. The Name must resolve to a different variable on each device; this is checked for every instance device before anything is saved, when a variable is created and when it is renamed.

The variable row shows Enable, Name, Asset, Type, Address, and Description directly and these values can be edited in place. Press the Settings icon on a variable row to open the Edit variable dialog, which contains the same tabs and all settings of the variable. Press Save to apply the changes. Changes made on a template device are also applied to the matching variable on all instance devices, while each instance keeps its own Modbus Address value. The Gateway tab settings Modbus Address, OPC UA, Writeable, MQTT Publisher, Kafka Device, Kafka Remap Device, and Kafka Remap Variable are also available as table columns, which are shown with Columns as described in the Configuration Tables article.

Supported Data Types

The Type field determines how the raw register bytes are interpreted.

Addressing

The Address field supports both IEC-style prefix notation and standard Modbus numeric notation. Holding and input register addresses support an optional bit selector using dot notation.

Variable Arrays

A variable can expand into an array by setting the Array size field to a value between 2 and 512. The variable itself is the first element and its Name must end in the first index, for example PLC1.Temps[0]. The remaining elements are created automatically as Temps[1], Temps[2] and so on, with addresses advancing by the width of the data type: one register for INT, UINT and WORD, two registers for DINT, UDINT, DWORD and REAL, four registers for LINT, ULINT and LREAL, and one point per element for coils and discrete inputs. An address with a bit selector cannot form an array.

The element rows are managed by the first element: they follow its settings, appear locked in the variable list, and are edited by editing the first element. Changing the Array size adds or removes elements at the end. Renaming the first element or changing its address renames and re-addresses all elements. Setting Array size back to 0 while elements exist removes the elements.

To turn the elements into ordinary independent variables, use the Ungroup array action on the first element's row in the variable list, or the Configuration API (POST /API/Config/VariableArrays/Ungroup). All rows are kept; only the grouping is removed. This is one-way. The element count badge next to the first element's name folds and unfolds the element rows in the list.

The same mechanism is available on OPC UA (the elements share one array node), EtherNet/IP (the tag address must end in an array index such as MyArray[0]), S7, MELSEC, Omron FINS, DNP3, BACnet, IEC104, Beckhoff ADS and Local variables.

Bit Selector

Use the dot notation to select a single bit from a holding or input register. This is useful for reading packed status words as individual BOOL values.

A BOOL on a bit of a holding register can be written. The write sends that one register, with the selected bit set or cleared in the register value of the last scan. The value must be true, false, 1 or 0. Any other value is rejected and the register on the device keeps its value. The variable status then shows FormatError until the next successful read; ModbusWriteMany in a Python script skips the entry and reports it as not written.

Notes

The channel state indicator on each device row shows the current communication status. A connected device shows the execution time of the last scan cycle.

When Allow Scanning Blocks is enabled, the system groups contiguous register ranges into a single Modbus request. This reduces network overhead but requires that the slave supports reading a range that spans all registers in the block. Use Max Block Size Allowed to limit the block length if the slave has restrictions.

Byte Swap, Word Swap, and Double Swap affect the byte ordering of multi-byte values. The correct combination depends on the Modbus slave device. When communication succeeds but values appear incorrect, adjust the swap settings to match the byte order of the target device.

Variables are referenced at runtime using the format DeviceName.VariableName, for example PLC1.Pump1_Speed.

Simulation mode lets you exercise a project when the device is not connected. When Simulation is enabled on a device, the device does not open its connection and its scan thread does not run. Its variables stay present in the runtime with a Good status instead of Connection Lost, and each variable is read and written directly in memory, exactly like a Local variable. This makes graphics, alarms, events, logic, and trends respond to values written from the runtime without any hardware. The device Channel State reads Simulation. Written values live in memory only and reset to their default when the application restarts. Turning Simulation off and saving reloads the device and it attempts the real connection again.

Enable Verbose only during commissioning or diagnostics. It increases log volume significantly. With Verbose 2 the SystemLog Viewer shows every request as one line: the request text, then TX with the request and RX with the response of the device, both in hexadecimal. TX and RX start with the Modbus function code, followed by the data of that function code. The Unit ID is part of the request text.

Reading Holding Registers at Unit:1 Start:100 Count:3 | TX [0300640003] | RX [030604D200000000]
Write Multiple Registers at Unit:1 Addr:100 Value:04D2 | TX [10006400010204D2] | RX [1000640001]
Write Single Coil at Unit:1 Addr:5 Value:True | TX [050005FF00] | RX [050005FF00]

An RX value that starts with the function code plus 80 hexadecimal is a Modbus exception response, followed by the exception code. For example, RX [8302] is exception code 02 on a Read Holding Registers request. RX (no valid response) is shown when the request ends without a valid response, for example after a timeout. In both cases the error is logged on the next line.

A value written to a variable must match its type: a number for the numeric types and true, false, 1 or 0 for a BOOL. A value that does not match, for example text written to a REAL, is not sent and the register on the device keeps its value. The System Log records the rejected write, and the variable status shows FormatError until the next successful read of the variable.