ModBus XOP

ModBus XOP is an Igor external operation (XOP) that permits you to control a device supporting the Modbus/TCP protocol from Igor's command line or from an Igor procedure. A full description of the Modbus protocol can be found at http://www.modbus.org. This XOP is based upon the FieldTalk™ Modbus Master C++ Library distributed by proconX.

The command line operations described below will be added to Igor Pro. Modbus XOP adds no menu items or dialogs to Igor. The exact settings you use depend on the instrument you are talking to. The important thing is that you know what your instrument expects and what the Modbus operations do so that you can coordinate them.

This plug-in is free and may be improved on request. For using it, download the disk image file containing the XOP and the Help files. Then, put both in the Igor Extensions folder and relaunch Igor.

Version 1.08 - November 2024

Updated for Igor Pro 8.04 and 9.x. Compatible with macOS and Windows (64-bit). Help file updated.

for macOS and Igor Pro 8.04, 9.x
(64 bit XOP):

for Windows and Igor Pro 8.04, 9.x
(64 bit XOP):

Version 1.07 - November 2018

Fixes MBWrite issues encountered with 32-bit data vaues, Help file updated.
Compatible with macOS X 10.12 - 10.14.

for macOS X and Igor Pro 7
(64 bit XOP):

for macOS X and Igor Pro 8
(64 bit XOP):

Version 1.06 - October 2018

Linked with FieldTalk Library 2.9.0 for Windows 10 (32- and 64-bit versions), 64-bit version linked with FieldTalk library 2.6.5 for macOS and Igor Pro 8, Help file updated.
Compatible with Windows 7, 8 and 10, macOS X 10.12 - 10.13.

for macOS X and Igor Pro 7
(64 bit XOP):

for Windows and Igor Pro 7
(32 bit XOP):

for Windows and Igor Pro 8
(32 bit XOP):

for macOS X and Igor Pro 8
(64 bit XOP):

for Windows and Igor Pro 7
(64 bit XOP):

for Windows and Igor Pro 8
(64 bit XOP):

Version 1.05 - September 2018

FieldTalk library 2.6.5 compiled on macOS X, Help file updated,
Compatible with macOS X 10.6 - 10.12.

for macOS X and Igor Pro 7
(32 bit XOP):

for macOS X and Igor Pro 7
(64 bit XOP):

Version 1.04 - May 2012

Added poll delay refreshed without requiring Igor restart, Fixed bug leading to incorrect error messages, FieldTalk library updated to release 2.6.4 for Windows and 2.6.5 for Mac OS X, Help file updated, Compatible with Windows XP, 7, macOS X 10.6 - 10.12.

for Mac OS X and Igor Pro 5.02+
(Universal Binary XOP):

for Windows XP and Igor Pro 5.02+
(Win32 XOP):

Commands

ModBus XOP adds the following command line operation to Igor:

MBOpen for opening the communication with a remote device
MBGetStatus for checking a remote device TCP/IP connection
MBClose for closing a TCP/IP communication with a remote device
MBRead for reading the status of coils, inputs and registers in a remote device
MBWrite for setting coils, inputs and registers in a remote device.

MBOpen [/Q] IP=hostName, port=TCPport, timeout=time, delay=pollDelay

The MBOpen operation opens the communication with a MODBUS device. If an error is encountered, the error code is returned in V_MBerr.

Flags
/Q			MBOpen sets V_MBerr to zero if no error occurred or to non-zero if an error did occur. If the error is a timeout (codes 132 or 133), MBOpen does not report it to Igor so that your procedure can handle the error.
Keywords
IP=hostName			Used in preparation for MODBUS/TCP read/write operations. hostName is the IP address of the device to control.
port=TCPport			Used in preparation for MODBUS/TCP read/write operations. TCPport is the TCP port number to be used for the communication. The default TCP port number is 1100.
timeout=time			Used in preparation for MODBUS/TCP read/write operations. time is the time-out in ms to be used for the communication. The default time-out is 1000ms.
delay=pollDelay			Used in preparation for ModBus/TCP read/write operations. pollDelay is the delay time which applies between two consecutive Modbus read/write. A value of 0 disables the poll delay. The default value is 10ms.
Example
This function opens the TCP/IP connection with a MODBUS device before starting read/write operations:
Function InitModBusCommunication()// This variable is useful for TCP/IP calls using the MODBUS commands.String/G gDeviceAddress = "192.168.1.1"// Set device for MODBUS operations.MBOpen /Q IP=gDeviceAddress, port=1100, timeout=100, delay=0// Check the connectionif (V_MBerr)...End

MBGetStatus [/Q] IP=hostName

The MBGetStatus operation returns the status of the MODBUS device. The status code is returned in V_MBStatus. If an error is encountered, the error code is returned in V_MBerr.

Flags
/Q			MBGetStatus does not report the error to Igor so that your procedure can handle the error using V_MBerr.
Keywords
IP=hostName			hostName is the IP address of the device to check.
Example
MBGetStatus /Q IP="192.168.1.1"

MBClose [/Q] IP=hostName

The MBClose operation closes the TCP/IP communication with a MODBUS device. If an error is encountered, the error code is returned in V_MBerr.

Flags
/Q			MBOpen sets V_MBerr to zero if no error occurred or to non-zero if an error did occur. If the error is a timeout (codes 132 or 133), MBOpen does not report it to Igor so that your procedure can handle the error.
Keywords
IP=hostName			hostName is the IP address of the device to close.
Example
This command closes the TCP/IP connection with a MODBUS device:
MBClose IP="192.168.1.1"returns in the history window:=> MODBUS/TCP connection closed with device at address "192.168.1.1"

MBRead [/L/F/Q] IP=hostName, keyword =address [, keyword=address...]

The MBRead operation reads the status of coils, inputs or registers into variables (MODBUS public function codes 1, 2, 3, 4). If an error is encountered, the error code is returned in V_MBerr.

Flags
/L			Specifies 32-bit long integers data types access (only valid when used with keywords HoldingRegister and InputRegister).
/F			Specifies 32-bit float data types access (only valid when used with keywords HoldingRegister and InputRegister).
/Q			MBOpen sets V_MBerr to zero if no error occurred or to non-zero if an error did occur. If the error is a timeout (codes 132 or 133), MBOpen does not report it to Igor so that your procedure can handle the error.
Keywords
IP=hostName			hostName is the IP address of the device to access.
Coil=address			Reads a coil status in a remote device (public function code 1). address is the address of the coil (default value is 0).
DiscreteInput=address			Reads a discrete input in a remote device (public function code 2). address is the address of the input (default value is 0).
HoldingRegister=address			Reads the contents of a holding register in a remote device (public function code 3). address is the address of the register (default value is 0).
InputRegister=address			Reads an input register in a remote device (public function code 4). address is the address of the starting register (default value is 0).
Example
This command reads the holding register 619 of a remote device into the variable V_HoldingRegister:
MBRead IP="192.168.1.1" HoldingRegisters=619

MBWrite [/L/F/Q] IP=hostName, keyword ={parameters...}

The MBWrite operation writes a coil or a register (MODBUS public function codes 5, 6). If an error is encountered, the error code is returned in V_MBerr.

Flags
/L			Specifies 32-bit long integers data types access (valid when used with keywords HoldingRegisters and InputRegisters).
/F			Specifies 32-bit float data types access (valid when used with keywords HoldingRegisters and InputRegisters).
/Q			MBWrite does not report an error to Igor so that your procedure can handle the error using V_MBerr.
Keywords
IP=hostName			hostName is the IP address of the device to access.
Coil={address, value}			Writes a single output to either ON or OFF in a remote device (public function code 5). address is the address of the coil (default value is 0). number is either 0 (OFF) or 1 (ON).
Register={address, value}			Writes a single holding register in a remote device (public function code 6). address is the address of the register (default value is 0). number is either a 16-bit value, a 32-bit long integer (/L) or a 32-bit float number (/F).
Example
This command writes 23 in the register at address 2
MBWrite IP="192.168.1.1" Register={2, 23}

Error Codes

ModBus XOP commands set the variable V_MBerr after completion. The error codes are defined as follows:

Codes	Name	Description
0	MB_SUCCESS	Operation was successful
1	MB_ILLEGAL_ARGUMENT	A parameter passed to the command is invalid or out of range
2	MB_ILLEGAL_STATE	The command is called in a wrong state, e.g. the protocol has not been opened successfully yet.
3	MB_EVALUATION_EXPIRED	The version of the FieldTalk library is a function limited evaluation version that has expired (should never be encountered)
4	MB_NO_DATA_TABLE	The slave has been started without adding a data table.
5	MB_ILLEGAL_SLAVE_ADDRESS	A slave address or unit ID of 0 is used as broadcast address for ASCII and RTU protocol and therefore illegal for serial protocols (should never be encountered).
6	MB_IO_ERROR_CLASS	A problem in conjonction with the I/O system is encountered.
65	MB_IO_ERROR	The underlaying I/O system reported an error.
66	MB_OPEN_ERROR	The TCP/IP socket or the serial port could not be opened. In case of serial, it indicates that the serial port does not exist on the system.
67	MB_PORT_ALREADY_OPEN	The serial port defined is already opened by another application.
68	MB_TCPIP_CONNECT_ERR	Signals that the TCP/IP connection could not be established. Typically, this occurs when a hos does not exist on the network or the IP address or hots name is wrong. The remote host must also listen on the appropriate port.
69	MB_CONNECTION_CLOSED	Signals that the TCP/IP connection was closed by the remote peer or is broken.
70	MB_SOCKET_LIB_ERROR	The TCP/IP socket library could not be loaded.
71	MB_PORT_ALREADY_BOUND	Indicates that the specified TCP port cannot be bound. The port might already be taken by another application or has not been released yet by the TCP/IP stack for re-use.
72	MB_LISTEN_FAILED	The listen operation on the specified TCP port failed.
73	MB_FILEDES_EXCEEDED	Maximum number of usable file descriptors exceeded.
74	MB_PORT_NO_ACCESS	You do not have permission to access the serial or TCP port. Run the program as root. If the error is related to a serial port, change the access privilege. If it is related to TCP/IP use TCP port number which is outside the IPPORT_RESERVED range.
75	MB_PORT_NOT_AVAILABLE	The specified TCP port is not available on this machine.
128	MB_BUS_PROTOCOL_ERR	Signals that a fieldbus protocol related error has occured. This class is the general class of errors produced by failed or interrupted data transfer functions. It is also produced when receiving invalid frames or exception responses.
129	MB_CHECKSUM_ERROR	Signals that the checksum of a received frame is invalid. A poor data link typically causes this error.
130	MB_INVALID_FRAME	Signals that a received frame does not correspond either by structure or content to the specifications or does not match a previously sent query frame. A poor data link typically causes this error.
131	MB_INVALID_REPLY	Signals that a received reply does not correspond to the specification.
132	MB_REPLY_TIMEOUT	Signals that a fieldbus data transfer times out. This can occur is the slave device does not reply in time or does not reply at all. A wrong unit address will cause this error. In some occasions, this exception is also produced if the characters received do not constitute a complete frame.
133	MB_SEND_TIMEOUT	Signals that a fieldbus data send timed out. This can only occur if the handshake lines are not properly set.
160	MB_EXCEPTION_RESPONSE	Signals that a Modbus exception response was received. Exception responses are sent by a slave device instead of a normal response message if it received the query message correctly but cannot handle the query. This error usually occurs if a master queried an invalid or non-existing data address or if the master used a Modbus function, which is not supported by the slave device.
161	MB_ILLEGAL_FUNCTION	Signals that an Illegal Function exception response (ModBus code 01) was received. This exception response is sent by a slave device instead of a normal response message if a master sent aModbus function, which is not supported by the slave device.
162	MB_ILLEGAL_DATA_ADDRESS	Signals that an Illegal Data Address exception response (ModBus code 02) was received. This exception response is sent by a slave device instead of a normal response message if a master queried an invalid or non-existing data address.
163	MB_ILLEGAL_DATA_VALUE	Signals that a Illegal Value exception response was (ModBus code 03) received. This exception response is sent by a slave device instead of a normal response message if a master sent a data value, which is not an allowable value for the slave device.
164	MB_SLAVE_DEVICE_FAILURE	Unrecoverable error encountered while the remote device was attempting to perform the request action

Revision notes of older versions

Version 1.03A - October 2011
Help file updated (variable names corrected),
Compatible with Windows XP, macOS X 10.6 - 10.12

Version 1.03 - January 2010
Help file updated, "delay=pollDelay" parameter added to MBOpen,
Compatible with Windows XP and Mac OS 10.6

Version 1.02 - January 2010
Help file updated, Version resource added to Windows release, Fixed a bug where wrong error codes were returned,
Compatible with Windows XP and Mac OS 10.6

Version 1.01 - September 2009
Help file updated, XOP recompiled with DTRACELOG disabled in FieldTalk library.
Compatible with Windows XP and Mac OS 10.6

Version 1.00 - August 2008
First release based on FieldTalk library 2.4.0 - includes MBOpen, MBGetStatus, MBWrite, MBRead, MBClose