ModBus XOP
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 FOCUS Software Engineering Pty LTd, Autralia.
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 - March 2020
Updated for Igor Pro 8.04 and macOS Catalina 10.15, Help file updated.
Version 1.0.8 for macOS and Igor Pro 8
(64 bit XOP)
(dmg - 2.74 Mi)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.
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.
(zip - 190 Ki)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.
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):
(dmg - 172 Ki)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() // Set device for MODBUS operations. // Check the connection | ||
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