Modbus
The Modbus connector provides a unified interface for communicating with Modbus devices. It handles low-level data framing and supports the two primary industrial communication protocols:
Modbus TCP: For devices connected over an Ethernet network.
Modbus RTU: For devices connected over serial lines (such as RS-485 or RS-232).
This connector requires instance creation before you can communicate with a device. You must establish an active session using the appropriate connection function before executing any read or write transactions.
Connection management
create
Creates a Modbus client instance. The connection details follow in connectTcp or connectRtu.
Parameters
None.
Output
Returns the name of the created instance.
connectTcp
Connects to a Modbus device over an Ethernet network.
Parameters
options
host
The hostname or IP address of the Modbus device.
string
unitId
The unit identifier of the target hardware. Default 1.
integer
socketTimeout
The connection timeout in milliseconds. Default 5000.
integer
Example
Output
Returns true when a network connection is successfully established. Throws an error if the connection fails.
disconnectTcp
Closes the active Modbus TCP socket connection.
Parameters
None.
Output
Returns true when the network socket closes successfully, including when no connection exists.
connectRtu
Connects to a Modbus device over a serial interface.
Parameters
options
path
The local platform file path of the serial port (such as /dev/ttyUSB0 on Linux or COM3 on Windows).
string
baudRate
The serial communication speed in bits per second. Default 9600.
integer
dataBits
The number of data bits per character frame (5, 6, 7, or 8). Default 8.
integer
stopBits
The number of stop bits at the end of each frame (1, 1.5, or 2). Default 1.
number
parity
The parity error-checking mode (none, even, or odd). Default 'none'.
string
unitId
The station address (unit ID) of the device on the serial bus. Default 1.
integer
Example
Output
Returns true when the serial port opens successfully. Throws an error if the connection fails.
disconnectRtu
Closes the active Modbus RTU serial port connection.
Parameters
None.
Output
Returns true when the serial port closes successfully.
delete
Removes the instance and frees its associated network or serial resources.
Irreversible action
Deleting an instance removes its configuration. To communicate with the device again, you must trigger create anew.
Parameters
None.
Output
Returns true upon removal.
Reading and writing
read
Reads data from coils or registers on the connected Modbus device. The function automatically handles the underlying Modbus function code framing and parses raw buffers into primitives based on your configuration.
Parameters
options
fc
The Modbus function code used to request data (1: Read Coils, 2: Read Discrete Inputs, 3: Read Holding Registers, 4: Read Input Registers).
integer
address
The zero-based starting register or element offset address.
integer
length
The total number of sequential elements or 16-bit registers to read.
integer
dataType
The target binary parser type used to interpret the raw incoming buffer elements (raw, string, boolean, doubleBE, doubleLE, floatBE, floatLE, int16BE, int16LE, int32BE, int32LE, uint16BE, uint16LE, uint32BE, uint32LE). Unknown types fall back to raw with a logged warning. Default 'raw'.
string
Examples
Example 1: Read a single discrete coil element
Example 2: Read a 16-bit big-endian signed integer from a holding register
Example 3: Read a 32-bit big-endian floating point variable
Because 32-bit values span two discrete 16-bit Modbus memory registers, set the length parameter to 2.
Output
Returns the requested values fetched from the target hardware registers, parsed into the specified data type representation. Throws an error if the operation fails.
write
Writes data payloads directly to target coil or register elements on the connected Modbus hardware.
Parameters
data
The single literal value, array of values, or raw binary Buffer payload to write to the destination device registers.
any
addressInfo
fc
The Modbus transaction function code (5: Write Single Coil, 6: Write Single Register, 15: Write Multiple Coils, 16: Write Multiple Registers).
integer
address
The zero-based starting offset address for the target elements.
integer
Examples
Example 1: Toggle a single coil active
Example 2: Set a single 16-bit register value
Example 3: Update multiple sequential register data elements
Output
Returns the raw response object of the underlying jsmodbus client, containing the request, the device response, and timing metrics. The relevant information for flows is that the call completed without throwing. Throws an error if the write fails.
String helper functions
readString
Reads register values sequentially from a specified holding register starting address and extracts them as a decoded text string.
Parameters
startAddress
The zero-based register starting offset address.
integer
length
The total number of consecutive 16-bit registers containing the string character sequence.
integer
Example
Output
Returns the text string parsed from the targeted registers, with all null padding characters removed. Throws an error if the read fails or no data is received.
writeString
Encodes a text string and writes it across consecutive holding registers. See Text string encoding padding for how uneven byte lengths are handled.
Parameters
text
The text string to transmit to the target device.
string
startAddress
The zero-based register destination starting offset address.
integer
Example
Output
Returns the raw response object of the underlying jsmodbus client, like write. Throws an error if the operation fails or text is not a string.
Tips and tricks
Modbus TCP port mapping
While the official Modbus TCP standard mandates network communication over port 502, several virtual test rigs or secure industrial gateway firewalls route traffic along port 1502. The connector automatically binds to port 1502 by default. If your physical controller expects standard port constraints, explicitly override the port assignment inside your configuration options block during connection initialization.
Text string encoding padding
Modbus memory maps allocate a full 16-bit word space per register, whereas conventional text strings occupy single 8-bit bytes per character. When executing writeString, the string processor handles this allocation automatically. If your text payload compiles to an uneven byte length count, the helper joins a trailing null termination byte (0x00) to fill the final register block correctly.
Last updated
Was this helpful?