> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/app-builder/build-backend/functions/connectors/modbus.md). # 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](/app-builder/build-backend/functions/connectors.md#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

Input	Key	Description	Type
`options`	`host`	The hostname or IP address of the Modbus device.	string
	`port`	The target network port. Default 1502, see Modbus TCP port mapping.	integer
	`unitId`	The unit identifier of the target hardware. Default 1.	integer
	`socketTimeout`	The connection timeout in milliseconds. Default 5000.	integer

#### Example ```yaml # options host: 192.168.1.120 port: 502 unitId: 1 ``` #### 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

Input	Key	Description	Type
`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 ```yaml # options path: /dev/ttyUSB0 baudRate: 19200 parity: even unitId: 10 ``` #### 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. {% hint style="danger" %} #### Irreversible action Deleting an instance removes its configuration. To communicate with the device again, you must trigger `create` anew. {% endhint %} #### 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

Input	Key	Description	Type
`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 ```yaml # options fc: 1 address: 100 length: 1 dataType: boolean ``` Example 2: Read a 16-bit big-endian signed integer from a holding register ```yaml # options fc: 3 address: 40001 length: 1 dataType: int16BE ``` 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. ```yaml # options fc: 4 address: 30010 length: 2 dataType: floatBE ``` #### 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

Input	Key	Description	Type
`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 ```yaml # data true # addressInfo fc: 5 address: 100 ``` Example 2: Set a single 16-bit register value ```yaml # data 1234 # addressInfo fc: 6 address: 40001 ``` Example 3: Update multiple sequential register data elements ```yaml # data - 100 - 200 # addressInfo fc: 16 address: 40050 ``` #### 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

Input	Description	Type
`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 ```yaml # startAddress 40100 # length 10 ``` #### 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](#text-string-encoding-padding) for how uneven byte lengths are handled. #### Parameters

Input	Description	Type
`text`	The text string to transmit to the target device.	string
`startAddress`	The zero-based register destination starting offset address.	integer

#### Example ```yaml # text New Product ID # startAddress 40100 ``` #### 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.heisenware.com/app-builder/build-backend/functions/connectors/modbus.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.