Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who are familiar with the applicable national standards.
It is essential that the following notes and explanations are followed when installing and commissioning these components.

The responsible staff must ensure that the application or use of the products described satisfy all the requirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly under development.
For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics.
In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning.
No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE® and XFC® are registered trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.

Patent Pending

The TwinCAT Technology is covered, including but not limited to the following patent applications and patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.

Copyright

© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.


Overview

The library contains function blocks that permit the exchange of data between the BC9xxx Bus Controller and a remote partner on the MODBUS/TCP port.

Comments

  • The number of IP connections that may be open simultaneously is restricted to four, in order to maintain the use of resources at a minimum. If it is necessary to establish a further connection, a connection that is not required must first be closed.
  • After about 10 seconds, a connection that has not been used during that period is automatically closed, and must be reopened if needed.

Function blocks

Name | Description
FB_ModbusTcpOpen | Open a MODBUS/TCP connection to a remote partner.
FB_ModbusTcpClose | Close a MODBUS/TCP connection to a remote partner.
FB_ModbusTcpRequest | Send a MODBUS request to a remote partner.


FUNCTION_BLOCK FB_ModbusTcpOpen

This function block opens a TCP/IP connection to a remote partner on the MODBUS/TCP port. The number of IP connections that may be open is restricted to four, in order to maintain the use of resources at a minimum. If it is necessary to establish a further connection, a connection that is not currently in use can first be closed using the FB_ModbusTcpClose function block. If successful, the FB_ModbusTcpOpen function block supplies a port number in the iMyPortNo output variable. This port number is required in order to send a MODBUS request using either of the FB_ModbusTcpRequest or FB_ModbusTcpClose function blocks, e.g. to close the connection. When opening the connection, the tTimeout input parameter is also used to specify the time-out period for the MODBUS request and for the disconnection. After about 10 seconds, a connection that has been opened but has not been used during that period is automatically closed, and must be reopened if needed.

VAR_INPUT

VAR_INPUT
    bStart		: BOOL;
    sRemoteIPAddr	: STRING(15);
    tTimeOut		: TIME;
END_VAR

bStart: The function block is activated by a rising edge at this input.

sRemoteIPAddr: This variable is a string containing the network address (IP address) of the remote partner.

tTimeOut: Gives the time that may not be exceeded during execution of the command.

VAR_OUTPUT

VAR_OUTPUT
    bBusy		: BOOL;
    bError		: BOOL;
    iErrorId		: WORD;
    iMyPortNo		: WORD;
END_VAR

bBusy: When the function block is activated this output is set. It remains set until and acknowledgement is received.

bError: If an error should occur during the execution of the command, then this output is set, after the bBusy output has been reset.

iErrorId: When the bError output is set, this variable supplies the command-specific error code (table) or the device-specific error code.

iMyPortNo: When successful, the local port number associated with the connection is returned at this output. The port number is a dynamic number, generated afresh each time the connection is established.

Error Codes | Description
0x8500 | Resource error
0x8501 | No socket available
0x8502 | Open connection error

Example of calling the block in FBD:

PROGRAM MAIN
VAR
    fbModbusOpen	: FB_ModbusTcpOpen;
    bOpen		: BOOL;
    bBusy		: BOOL;
    bError		: BOOL;
    nErrId		: WORD;
    nConnectionPort	: WORD;
END_VAR

In this example, a rising edge at the bOpen input causes a TCP/IP connection to the remote partner with network address '172.16.2.209' to be established.

Development environment | Target platform | PLC libraries to be linked
TwinCAT v2.7.0 and below | BC9xxx (165) firmware version >=0xB6 | TcModbusTCPBC.Lb6


FUNCTION_BLOCK FB_ModbusTcpClose

The FB_ModbusTcpClose function block closes a connection to a remote partner that was opened with the FB_ModbusTcpOpen function block. The number of IP connections that may be open is restricted to four, in order to maintain the use of resources at a minimum. If it is necessary to establish a further connection, a connection that is not currently in use must first be closed. A connection is automatically closed after about 10 seconds if it is not used during that period. A confirmation from the remote partner is not expected when a connection is closed. This means that under certain circumstances (e.g., if network communication has been interrupted) it can happen that a connection still exists. The remote partner should then close any such open connections. A Bus Controller operating as a remote partner closes such open connections automatically.

VAR_INPUT

VAR_INPUT
    bStart		: BOOL;
    sRemoteIPAddr	: STRING(15);
    iMyPortNo		: WORD;
END_VAR

bStart: The function block is activated by a rising edge at this input.

sRemoteIPAddr: This variable is a string containing the network address (IP address) of the remote partner whose connection is to be closed.

iMyPortNo: The port number associated with the connection is passed here as a parameter. The port number is generated afresh (dynamically) each time the connection is established with the FB_ModbusTcpOpen function block.

VAR_OUTPUT

VAR_OUTPUT
    bBusy		: BOOL;
    bError		: BOOL;
    iErrorId		: WORD;
END_VAR

bBusy: When the function block is activated this output is set. It remains set until and acknowledgement is received.

bError: If an error should occur during the execution of the command, then this output is set, after the bBusy output has been reset.

iErrorId: When the bError output is set, this variable supplies the command-specific error code (table) or the device-specific error code.

Error Codes | Description
0x8400 | Connection is already closed.
0x8401 | Connection close timeout.
0x8402 | Connection close resource error.

Example of calling the block in FBD:

PROGRAM MAIN
VAR
    fbModbusClose	: FB_ModbusTcpClose;
    bOpen		: BOOL;
    bBusy		: BOOL;
    bError		: BOOL;
    nErrId		: WORD;
    nConnectionPort	: WORD;
END_VAR

In the example, a rising edge at the bClose input triggers closure of the TCP/IP connection to the remote partner with network address '172.16.2.209'.

Development environment | Target platform | PLC libraries to be linked
TwinCAT v2.7.0 and below | BC9xxx (165) firmware version >=0xB6 | TcModbusTCPBC.Lb6


FUNCTION_BLOCK FB_ModbusTcpRequest

The FB_ModbusTcpRequest function block can send a MODBUS request to a remote partner. The connection required for this must first have been opened with the FB_ModbusTcpOpen function block. The dynamic port number returned as the connection is established is passed as an input parameter to the iMyPortNo variable. Connections that are not used are automatically closed after about 10 seconds, or may be closed by the remote partner. If there is no connection, error code 0x8305 is returned, for example, to the iErrorId output. The FB_ModbusTcpRequest function block transmits the entire MODBUS frame, beginning with the UNIT ID. The TCP section is inserted by the BC9xxx Bus Controller at the start.

VAR_INPUT

VAR_INPUT
    bStart		: BOOL;
    sRemoteIPAddr	: STRING(15);
    iMyPortNo		: WORD;
    pReqBuff		: DWORD;
    cbReqLen		: WORD;
    pResBuff		: DWORD;
    cbResLen		: WORD;
END_VAR

bStart: The function block is activated by a rising edge at this input.

sRemoteIPAddr: This variable is a string containing the network address (IP address) of the remote partner.

iMyPortNo: The port number associated with the connection is passed here as a parameter. The port number is generated afresh (dynamically) each time the connection is established with the FB_ModbusTcpOpen function block.

pReqBuff: Contains the address of the buffer with the MODBUS request data. It is the programmer who is responsible for dimensioning the buffer appropriately so that cbReqLen bytes can be removed from it. The buffer can be a single variable, an array or a structure, whose address can be found with the ADR operator.

cbReqLen: Length, in bytes, of the MODBUS request data in the pReqBuff buffer.

pResBuff: Contains the address of the buffer for the MODBUS response data. The programmer is himself responsible for dimensioning the buffer to a size that can accept cbResLen bytes. The buffer can be a single variable, an array or a structure, whose address can be found with the ADR operator.

cbResLen: Length, in bytes, of the MODBUS response buffer. It is the programmer who is responsible for dimensioning the buffer to such a size that all the response data can be accepted.

VAR_OUTPUT

VAR_OUTPUT
    bBusy		: BOOL;
    bError		: BOOL;
    iErrorId		: WORD;
    cbResponse	: WORD;
END_VAR

bBusy: When the function block is activated this output is set. It remains set until and acknowledgement is received.

bError: If an error should occur during the execution of the command, then this output is set, after the bBusy output has been reset.

iErrorId: When the bError output is set, this variable supplies the command-specific error code (table) or the device-specific error code.

cbResponse: The length, in bytes, of the response data actually returned in the response buffer.

Error Codes | Description
0x8300 | Tx error. Timeout error.
0x8301 | Tx error. Remote shutdown.
0x8302 | Tx error. Internal error.
0x8303 | Tx error. Resource error.
0x8305 | Tx error. No remote connection.
0x8100 | Rx error. Wrong transaction ID.
0x8101 | Rx error. Wrong protocol ID.
0x8102 | Rx error. Wrong length.
0x8103 | Rx error. Exceeding length.
0x8104 | Rx error. Wrong unit ID.

Example of calling the block in FBD:

PROGRAM MAIN
VAR
    fbModbusRequest	: FB_ModbusTcpRequest;
    bExecute		: BOOL;
    bExecute		: nConnectionPort;
    SendBuffer	: ARRAY[0..5] OF BYTE := 1,6,64,64,0,0;
    ReceiveBuffer	: ARRAY[0..255] OF BYTE;
    bBusy		: BOOL;
    bError		: BOOL;
    nErrId		: WORD;
    cbReceived	: WORD;
END_VAR

In the example, a rising edge at the bExecute input causes a request to be sent to the remote partner with network address '172.16.2.209'.

Development environment | Target platform | PLC libraries to be linked
TwinCAT v2.7.0 and below | BC9xxx (165) firmware version >=0xB6 | TcModbusTCPBC.Lb6


BC9xxx return codes

Value (hex) | Description
0x8800 | No valid network configuration.
0x8E00 | Connection closed by target.
0x8F00 | Resource error.

Value (hex) | Description Receive Error
0x8100 | Receive wrong transaction ID
0x8101 | Receive wrong protocol ID
0x8102 | Receive wrong lenght
0x8103 | Receive exceeding lenght
0x8104 | Receive wrong unit ID

Value (hex) | Description Transmit Error
0x8300 | Transmit timeout
0x8301 | Transmit Shutdown
0x8302 | Transmit internal error
0x8303 | Transmit resource error
0x8305 | Transmit remote not connected

Value (hex) | Description Close Error
0x8400 | Receive wrong transaction ID
0x8401 | Receive wrong protocol ID
0x8402 | Receive wrong lenght

Value (hex) | Description Open Error
0x8500 | Open ressoucre error
0x8501 | Open ressoucre error_1
0x8502 | Open connect error
0x8503 | Open connection already open