Beckhoff TF6610 User Manual

Manual | EN

TF6610

TwinCAT 3 | S5/S7 Communication

11/10/2020 | Version: 1.1

Table of contents

Table of contents

1 Foreword ....................................................................................................................................................5

1.1 Notes on the documentation..............................................................................................................5

1.2 Safety instructions .............................................................................................................................6

2 Overview.....................................................................................................................................................7

3 Installation..................................................................................................................................................8

3.1 Installation .........................................................................................................................................8

3.2 Installation WindowsCE..................................................................................................................11

3.3 Licensing .........................................................................................................................................13

4 Configuration of an IBH Link S5/S7 ++ adapter....................................................................................16

5 Description of the PLC data area parameter values ............................................................................18

6 API.............................................................................................................................................................20

6.1 PLC Reference ................................................................................................................................20

6.1.1 Function blocks................................................................................................................ 20

6.1.2 Functions [obsolete]......................................................................................................... 25

6.1.3 Data Types ...................................................................................................................... 26

6.1.4 Global Constants ............................................................................................................. 29

7 Samples....................................................................................................................................................31

8 Appendix ..................................................................................................................................................32

8.1 Error codes overview.......................................................................................................................32

8.2 Internal S5/S7 communication error codes .....................................................................................33

8.3 ADS Return Codes ..........................................................................................................................35

8.4 Win32 Error Codes ..........................................................................................................................40

8.5 Troubleshooting/diagnostics............................................................................................................95

TF6610 3Version: 1.1

Table of contents

TF66104 Version: 1.1

Foreword

1 Foreword

1.1 Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who
are familiar with applicable national standards.
It is essential that the documentation and the following notes and explanations are followed when installing
and commissioning the components.
It is the duty of the technical personnel to use the documentation published at the respective time of each
installation and commissioning.

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.
We reserve the right to revise and change the documentation at any time and without prior announcement.
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®, EtherCAT G®, EtherCAT G10®, EtherCAT P®, Safety over EtherCAT®,
TwinSAFE®, XFC®, XTS® and XPlanar® 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 EtherCAT Technology is covered, including but not limited to the following patent applications and
patents:
EP1590927, EP1789857, EP1456722, EP2137893, DE102015105702
with corresponding applications or registrations in various other countries.

EtherCAT® is a registered trademark and patented technology, licensed by Beckhoff Automation GmbH,
Germany

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.

TF6610 5Version: 1.1

Foreword

1.2 Safety instructions

Safety regulations

Please note the following safety instructions and explanations!
Product-specific safety instructions can be found on following pages or in the areas mounting, wiring,
commissioning etc.

Exclusion of liability

All the components are supplied in particular hardware and software configurations appropriate for the
application. Modifications to hardware or software configurations other than those described in the
documentation are not permitted, and nullify the liability of Beckhoff Automation GmbH & Co. KG.

Personnel qualification

This description is only intended for trained specialists in control, automation and drive engineering who are
familiar with the applicable national standards.

Description of symbols

In this documentation the following symbols are used with an accompanying safety instruction or note. The
safety instructions must be read carefully and followed without fail!

DANGER

Serious risk of injury!

Failure to follow the safety instructions associated with this symbol directly endangers the life and health of
persons.

WARNING

Risk of injury!

Failure to follow the safety instructions associated with this symbol endangers the life and health of per­sons.

CAUTION

Personal injuries!

Failure to follow the safety instructions associated with this symbol can lead to injuries to persons.

NOTE

Damage to the environment or devices

Failure to follow the instructions associated with this symbol can lead to damage to the environment or
equipment.

Tip or pointer

This symbol indicates information that contributes to better understanding.

TF66106 Version: 1.1

Overview

2 Overview

The function blocks of the PLC library Tc2_S5S7Com can be used to realise data exchange between the
local TwinCAT PLC and a S5/S7 controller via an Ethernet LAN adapter from IBHsoftec.

The adapter is not part of the Beckhoff product and must be bought from IBHsoftec.

Product components

The function TF6610 | S5/S7 consists of the following components which are automatically installed during
setup:

• Functions: TF6310

• PLC library Tc2_S5S7Com (Tc2_TcpIp installed with TF6310)

• Background program:TwinCAT TCP/IP connection server (for communication, installed with
TF6310);.

System requirements

Supported adapters:

• IBH Link S5++ adapter from IBHsoftec (from firmware version 1.39; the firmware version can be
read via the configuration software provided).
Older adapters (without ++) are currently not supported.

• IBH Link S7++ adapter from IBHsoftec (from firmware version NL50MPI V02.004 05.06.09; the
firmware version can be read via the configuration software provided).

The following article describes the minimum requirements for the engineering or runtime system.

Development environment

A development environment describes a computer developing PLC program, but not running. On a
development computer, the following have to be installed:

• TwinCAT v3.1.4016.0 XAE (engineering) or higher;

• TwinCAT 3 Function TF6610 S5 / S7 Communication;

Run-time environment

A runtime environment describes a computer running PLC programs. On a runtime computer, the following
have to be installed:

• TwinCAT v3.1.4016.0 XAR (runtime) or higher;

• TwinCAT 3 Function TF6610 S5 / S7 Communication;

• Licenses for TC1200 PLC and TF6610;

Developer and run-time version on a computer

To run a runtime and development environment on a computer (for example, to test a PLC program before
loading it to the target computer), the following requirements must be fullfilled:

• TwinCAT v3.1.4016.0 XAE (Engineering) or higher;

• TwinCAT 3 function TF6610 S5 / S7 communication;

• Licenses for TC1200 PLC, TF6610;;

Please note: For test purposes a 7-day trial license can be generated, see licensing.

TF6610 7Version: 1.1

Installation

3 Installation

The function TF6610 can be installed with the Operating System XP and CE.

3.1 Installation

The following section describes how to install the TwinCAT3Function for Windows-based operating
systems.

ü The TwinCAT3Function setup file was downloaded from the Beckhoff website.

1. Run the setup file as administrator. To do this, select the command Run as administrator in the context
menu of the file.

ð The installation dialog opens.

2. Accept the end user licensing agreement and click Next.

TF66108 Version: 1.1

3. Enter your user data.

Installation

4. If you want to install the full version of the TwinCAT3Function, select Complete as installation type. If
you want to install the TwinCAT3Function components separately, select Custom.

TF6610 9Version: 1.1

Installation

5. Select Next, then Install to start the installation.

ð A dialog box informs you that the TwinCAT system must be stopped to proceed with the installation.

6. Confirm the dialog with Yes.

TF661010 Version: 1.1

7. Select Finish to exit the setup.

Installation

ð The TwinCAT3Function has been successfully installed and can be licensed (see Licensing [}13]).

3.2 Installation WindowsCE

The following section describes how to install a TwinCAT3function (TFxxx) on a Beckhoff Embedded PC
with WindowsCE.

1. Download and install the setup file [}11]

2. Transfer the CAB file to the WindowsCE device [}12]

3. Run the CAB file on the WindowsCE device [}12]

If an older TFxxx version is already installed on the WindowsCE device, it can be updated:

• Software upgrade [}12]

Download and install the setup file

The CAB installation file for WindowsCE is part of the TFxxx setup. This is made available on the Beckhoff
website www.beckhoff.com and automatically contains all versions for Windows XP, Windows 7 and

Windows CE (x86 and ARM).

Download the TFxxx setup file and install the TwinCAT3function as described in the Installation [}8]
section.

After the installation, the installation folder contains three directories (one directory per hardware platform):

• CE-ARM: ARM-based Embedded PCs running WindowsCE, e.g. CX8090, CX9020

• CE-X86: X86-based Embedded PCs running WindowsCE, e.g. CX50xx, CX20x0

• Win32: Embedded PCs running WindowsXP, Windows7 or WindowsEmbeddedStandard

The CE-ARM and CE-X86 directories contain the CAB files of the TwinCAT3function for WindowsCE in
relation to the respective hardware platform of the WindowsCE device.

Example: "TF6310" installation folder

TF6610 11Version: 1.1

Installation

Transfer the CAB file to the WindowsCE device

Transfer the corresponding CAB file to the WindowsCE device.

There are various options for transferring the executable file:

• via network shares

• via the integrated FTP server

• via ActiveSync

• via CF/SD cards

Further information can be found in the Beckhoff Information System in the "Operating Systems"
documentation (EmbeddedPC>Operating Systems>CE).

Run the CAB file on the WindowsCE device

After transferring the CAB file to the WindowsCE device, double-click the file there. Confirm the installation
dialog with OK. Then restart the WindowsCE device.

After restarting the device, the files of the TwinCAT3function (TFxxxx) are automatically loaded in the
background and are then available.

The software is installed in the following directory on the WindowsCE device:

\Hard Disk\TwinCAT\Functions\TFxxxx

Software upgrade

If an older version of the TwinCAT3function is already installed on the WindowsCE device, carry out the
following steps on the WindowsCE device to upgrade to a new version:

1. Open the CE Explorer by clicking Start>Run and entering "Explorer".

2. Navigate to \Hard Disk\TwinCAT\Functions\TFxxx\xxxx.

3. Rename the file Tc*.exe to Tc*.old.

4. Restart the WindowsCE device.

5. Transfer the new CAB file to the WindowsCE device.

6. Run the CAB file on the WindowsCE device and install the new version.

7. Delete the file Tc*.old.

8. Restart the WindowsCE device.

ð The new version is active after the restart.

TF661012 Version: 1.1

Installation

3.3 Licensing

The TwinCAT3function can be activated as a full version or as a 7-day test version. Both license types can
be activated via the TwinCAT 3 development environment (XAE).

Licensing the full version of a TwinCAT3Function

A description of the procedure to license a full version can be found in the Beckhoff Information System in
the documentation "TwinCAT3Licensing".

Licensing the 7-day test version of a TwinCAT3Function

A 7-day test version cannot be enabled for a TwinCAT 3 license dongle.

1. Start the TwinCAT 3 development environment (XAE).

2. Open an existing TwinCAT 3 project or create a new project.

3. If you want to activate the license for a remote device, set the desired target system. To do this, select
the target system from the Choose Target System drop-down list in the toolbar.

ð The licensing settings always refer to the selected target system. When the project is activated on

the target system, the corresponding TwinCAT 3 licenses are automatically copied to this system.

4. In the Solution Explorer, double-click License in the SYSTEM subtree.

ð The TwinCAT 3 license manager opens.

TF6610 13Version: 1.1

Installation

5. Open the Manage Licenses tab. In the AddLicense column, check the check box for the license you
want to add to your project (e.g."TF6420:TC3DatabaseServer").

6. Open the Order Information (Runtime) tab.

ð In the tabular overview of licenses, the previously selected license is displayed with the status

“missing”.

7. Click7-DayTrialLicense... to activate the 7-day trial license.

ð A dialog box opens, prompting you to enter the security code displayed in the dialog.

8. Enter the code exactly as it is displayed and confirm the entry.

9. Confirm the subsequent dialog, which indicates the successful activation.

ð In the tabular overview of licenses, the license status now indicates the expiry date of the license.

10. Restart the TwinCAT system.

TF661014 Version: 1.1

ð The 7-day trial version is enabled.

Installation

TF6610 15Version: 1.1

Configuration of an IBH Link S5/S7 ++ adapter

4 Configuration of an IBH Link S5/S7 ++ adapter

The adapter configuration software is provided by the manufacturer of the adapter. It is not part of the
TwinCAT function. A detailed description of the module configuration can be found in the manufacturer
documentation.

Configuration of an IBH Link S5++ adapter

In the following example a fixed IP address 172.16.11.16 was set:

Configuration of an IBH Link S7++ adapter

In the following example a fixed IP address 172.16.11.17 was set:

TF661016 Version: 1.1

Configuration of an IBH Link S5/S7 ++ adapter

TF6610 17Version: 1.1

Description of the PLC data area parameter values

5 Description of the PLC data area parameter

values

The parameter values to be used for the write/read command differ depending on the type of external control
used, the adapter or the communication protocol. Some data areas may not be available, or the data have to
be read/written word by word instead of byte by byte. Further information can be found in the documentation
for the external control.

Data type

Read access to word variables in the S5/S7 controller returns data in Motorola format (Hi and Lo
bytes interchanged). For the evaluation the read data first have to be converted to the common Intel
format used in the TwinCAT system. Data to be written from the TwinCAT system to the S5/S7 con­troller must be converted to the Motorola format before the write access.

The BCD number system is used in the S5/S7 controller for representing the counter/timer variables. The
data may have to be converted, if necessary.

The TwinCAT PLC library: TcUtilities.Lib offers functions for conversion between Motorola and Intel format
(e.g. BE16_TO_host, host_TO_BE16...).

The following table provides an overview of the available communication routes:

Control LAN adapter Transport

protocol

S5 IBH Link S5++ TCP/IP IBH S5 LAN link protocol =

S7 IBH Link S7++ TCP/IP NetLink MPI protocol (NL-MPI)

IBH S5 LAN link protocol = FETCH/WRITE telegrams

• Currently this protocol can only be used with S5 controllers.

• The TCP/IP port number has the default value 2002;

• The parameter devAddr is not evaluated.

• The data block number (nDB) is only evaluated when the areas data blocks (DB) and extended data
blocks (DX) are accessed. Permitted range: 1..255;

• The areas P (periphery) and OS (operating state) are not supported.

Data area (eArea) Start address (nOffset) Permitted data length (cbBuffer)

DB Data word offset: 0..2047 read/write 1..2048 words

M Flag byte offset: 0..255 read/write 1..256 bytes

I Input byte offset: 0..127 read 1..128 bytes

Q Output byte offset: 0..127 write 1..128 bytes

P I/O periphery byte offset: 0..127 (digital

I/Os), 128..255 (analog I/Os)

C Counter start offset: 0..255 read/write 1 word

T Timer start offset: 0..255 read/write 1 word

DX Data word offset: read/write 1..2048 words

LAN adapter communication
protocol

FETCH/WRITE telegrams

from Hilscher

read/write 1..256 bytes

Notes

No connection parameterisation
required in the external controller.

No connection parameterisation
required in the external controller.

NetLink MPI protocol (NL-MPI) from Hilscher

• This protocol can only be used with S7 controllers.

• The TCP/IP port number has the default value 1099

• The MPI address (devAddr) has the default value 2. Permissible values: 1..126;

• The data block number (nDB) is only evaluated when the data blocks (DB) data area is accessed.
Permissible values: 0..65534;

TF661018 Version: 1.1

Description of the PLC data area parameter values

• The areas P (periphery) and DX (extended data block) are not supported.

• The byte length has to be specified for the data length parameter (cbBuffer).

• The OS area (operating state) is only available for read access.

Data area (eArea) Start address (nOffset) Permitted data length (cbBuffer)

DB Data byte offset: 0..65534 Read: max. 222 bytes, write: max. 216

M Flag byte offset: 0..65534

I Input byte offset: 0..65534

Q Output byte offset: 0..65534

C Counter start offset: 0..65534 Read: max. 111 word counters, write:

T Timer start offset: 0..65534 Read: max. 111 word timers, write: max.

OS Operating state: Irrelevant 1 word (0=STOP, 1=START, 2=RUN,

bytes

max. 108 counters

108 timers

3=UNKNOWN)

TF6610 19Version: 1.1

API

6 API

6.1 PLC Reference

6.1.1 Function blocks

6.1.1.1 FB_NLinkOpen

This function block (actively) establishes a network connection to the third-party system. If successful, the
internal parameters of the hLink variable are initialised. The same instance of the hLink variable must then

be transferred to the other instances of the communication blocks FB_NLinkFetch [}22], FB_NLinkWrite
[}24] or FB_NLinkClose [}21]. In a PLC application one instance of this variables is required for each

network connection (TwinCAT system<->Ethernet LAN adapter<->external controller).

VAR_IN_OUT

VAR_IN_OUT
hLink : T_HNLINK;
END_VAR

hLink : Network connection handle ( Type:T_HNLINK [}29]). The instance of this variable is required by the
other communication blocks and is transferred to them via VAR_IN_OUT.

VAR_INPUT

VAR_INPUT
stSettings:ST_NLinkSettings:=(sHost:='127.0.0.1',nPort:=2002);
nOpt:DWORD:=0;
bExecute:BOOL;
tTimeout:TIME:=T#45s;
END_VAR

stSettings: Structure with configuration settings for the communication connection. The member variables of
this structure should contain parameters such as port number, host name, etc.

nOpt: Reserved for future applications.

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

tTimeout: Specifies the timeout that must not be exceeded on receipt of the command.

VAR_OUTPUT

VAR_OUTPUT
bBusy : BOOL;
bError : BOOL;
nErrID : UDINT;
END_VAR

TF661020 Version: 1.1

API

bBusy: When the function block is activated this output is set. It remains set until a feedback is received.
While Busy = TRUE, no new command will be accepted at the inputs. Please note that it is not the command
execution but the receipt of the command that is monitored.

bError: In the event of an error during the command transfer, this output is set once the bBusy output has
been reset.

nErrID: Supplies the error number [}32] when the bError output is set.

Example:

See examples [}31].

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

6.1.1.2 FB_NLinkClose

This function block closes the network connection to the third-party system.

VAR_IN_OUT

VAR_IN_OUT
hLink : T_HNLINK;
END_VAR

hLink : Network connection handle ( Type:T_HNLINK [}29]). This is where the instance of the variable used
for establishing the connection by the FB_NLinkOpen [}20] function block is transferred.

VAR_INPUT

VAR_INPUT
nOpt:DWORD:=0;
bExecute:BOOL;
tTimeout:TIME:=DEFAULT_ADS_TIMEOUT;
END_VAR

nOpt: Reserved for future applications.

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

tTimeout: Specifies the timeout that must not be exceeded on receipt of the command.

VAR_OUTPUT

VAR_OUTPUT
bBusy : BOOL;
bError : BOOL;

TF6610 21Version: 1.1

API

nErrID : UDINT;
END_VAR

bBusy: When the function block is activated this output is set. It remains set until a feedback is received.
While Busy = TRUE, no new command will be accepted at the inputs. Please note that it is not the command
execution but the receipt of the command that is monitored.

bError: In the event of an error during the command transfer, this output is set once the bBusy output has
been reset.

nErrID: Supplies the error number [}32] when the bError output is set.

Example:

See examples [}31].

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

6.1.1.3 FB_NLinkFetch

This function block reads data from the third-party system and writes them to the local TwinCAT system
(FETCH service).

VAR_IN_OUT

VAR_IN_OUT
hLink : T_HNLINK;
END_VAR

hLink : Network connection handle (Type:T_HNLINK [}29]). This is where the instance of the variable used
for establishing the connection by the FB_NLinkOpen [}20] function block is transferred.

VAR_INPUT

VAR_INPUT
devAddr:BYTE:=2;
eArea:E_NLinkArea:=eNLinkArea_DB;
nDB:WORD:=0;
nOffset:WORD:=0;
cbBuffer:UDINT(0..MAX_NLink_DATALENGTH):=0;
pBuffer:POINTERTOBYTE:=0;
nOpt:DWORD:=0;

TF661022 Version: 1.1

API

bExecute:BOOL;
tTimeout:TIME:=DEFAULT_ADS_TIMEOUT;
END_VAR

devAddr: Device address, MPI address of the component on the third-party system.

eArea: PLC data area in the third-party system (inputs, outputs, data block etc.) from which data are to be

read (type:E_NLinkArea [}26]).

nDB: Data block number in the third-party system. Data are to be read from this data block (only relevant for
access to data blocks and extended data blocks).

nOffset: The start byte address or word address from which data are to be read in the third-party system.
Whether a byte or word address is to be specified depends on the type of external controller/protocol used

and the data area to be accessed. Further information can be found here: Description of the PLC data area
parameter values [}18].

cbBuffer: Maximum number of data bytes to be read. The byte length is specified even for access to word
addresses.

pBuffer: Pointer/address of the target data buffer in the TwinCAT system. The read data are written into this
buffer. The address can be determined with the ADR operator. The target data buffer must not be smaller
than the specified length of the data to be read.

nOpt: Reserved for future applications.

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

tTimeout: Specifies the timeout that must not be exceeded on receipt of the command.

VAR_OUTPUT

VAR_OUTPUT
bBusy : BOOL;
bError : BOOL;
nErrID : UDINT;
cbRead : UDINT := 0; (* Number of recend realy returned data bytes *)
END_VAR

bBusy: When the function block is activated this output is set. It remains set until a feedback is received.
While Busy = TRUE, no new command will be accepted at the inputs. Please note that it is not the command
execution but the receipt of the command that is monitored.

bError: In the event of an error during the command transfer, this output is set once the bBusy output has
been reset.

nErrID: Supplies the error number [}32] when the bError output is set.

cbRead: Number of successfully read data bytes.

Example:

See examples [}31].

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

TF6610 23Version: 1.1

API

6.1.1.4 FB_NLinkWrite

This function block sends data from the local TwinCAT system to the third-party system (WRITE service).

VAR_IN_OUT

VAR_IN_OUT
hLink : T_HNLINK;
END_VAR

hLink : Network connection handle ( Type:T_HNLINK [}29]). This is where the instance of the variable used
for establishing the connection by the FB_NLinkOpen [}20] function block is transferred.

VAR_INPUT

VAR_INPUT
devAddr:BYTE:=2;
eArea:E_NLinkArea:=eNLinkArea_DB;
nDB:WORD:=0;
nOffset:WORD:=0;
cbBuffer:UDINT(0..MAX_NLink_DATALENGTH):=0;
pBuffer:POINTERTOBYTE:=0;
nOpt:DWORD:=0;
bExecute:BOOL;
tTimeout:TIME:=DEFAULT_ADS_TIMEOUT;
END_VAR

devAddr: Device address, MPI address of the component on the third-party system.

eArea: PLC data area in the third-party system (inputs, outputs, data block, etc.) to which data are to be

written (type:E_NLinkArea [}26])

nDB: Data block number in the third-party system. Block in which data are to be written (only relevant for
access to data blocks and extended data blocks).

nOffset: The start byte address or word address from which data are to be written to the third-party system.
Whether a byte or word address is to be specified depends on the type of external controller/protocol used

and the data area to be accessed. Further information can be found here: Description of the PLC data area
parameter values [}18].

cbBuffer: Maximum byte length of the data to be transferred from the source data buffer in the local
TwinCAT system to the third-party system. The byte length is specified even for access to word addresses.

pBuffer: Pointer/address for the source data buffer. Data from this buffer are transferred to the third-party
system. The address can be determined with the ADR operator. The source data buffer must not be smaller
than the specified length of the data to be sent.

nOpt: Reserved for future applications.

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

tTimeout: Specifies the timeout that must not be exceeded on receipt of the command.

TF661024 Version: 1.1

API

VAR_OUTPUT

VAR_OUTPUT
bBusy : BOOL;
bError : BOOL;
nErrID : UDINT;
cbWrite : UDINT := 0;(* Number of successfull written data bytes *)
END_VAR

bBusy: When the function block is activated this output is set. It remains set until a feedback is received.
While Busy = TRUE, no new command will be accepted at the inputs. Please note that it is not the command
execution but the receipt of the command that is monitored.

bError: In the event of an error during the command transfer, this output is set once the bBusy output has
been reset.

nErrID: Supplies the error number [}32] when the bError output is set.

cbWrite: In case of success: Number of successfully written data bytes.

Example:

See examples [}31].

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

6.1.2 Functions [obsolete]

6.1.2.1 F_GetVersionTcS5S7Comm

This function can be used to read PLC library version information.

FUNCTION F_GetVersionTcS5S7Comm : UINT

VAR_INPUT
nVersionElement:INT;
END_VAR

nVersionElement : Version element to be read. Possible parameter:

• 1 : major number;

• 2 : minor number;

• 3 : revision number;

TF6610 25Version: 1.1

API

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

6.1.3 Data Types

6.1.3.1 E_NLinkArea

TYPEE_NLinkArea:
(
eNLinkArea_DB:=16#01,(* Source/dest. data from/to data block in main memory. *)
eNLinkArea_M:=16#02,(* Source/dest. data from/to flag area. *)
eNLinkArea_I:=16#03,(* Source/dest. data from/to process image of the inputs. *)
eNLinkArea_Q:=16#04,(* Source/dest. data from/to process image of the outputs. *)
eNLinkArea_P:=16#05,(* Source/dest. data from/to in I/O modules (S7 only PI, PQ). *)
eNLinkArea_C:=16#06,(* Source/dest. data from/to counter cells. *)
eNLinkArea_T:=16#07,(* Source/dest. data from/to timer cells. *)
eNLinkArea_DX:=16#0A,(* Source/dest. data from/to extended data block. *)
eNLinkArea_OS:=16#100(* Read PLC operational status information *)
);
END_TYPE

PLC data area (inputs, outputs, flag, data block etc.) to be accessed. The parameter values differ depending
on the type of external control used, the adapter or the communication protocol. Some data areas may not
be available, or the data have to be read/written word by word instead of byte by byte .

More detailed information on this topic can be found under: S5/S7 data area parameter values [}18].

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

6.1.3.2 E_NLinkProtocol

TYPE E_NLinkProtocol:
(
eNLinkProtocol_IBH_SX_PP := 0, (* IBH Link protocol (used by IBH Link S5++ adater) *)
eNLinkProtocol_MPI (* Hilscher NL-MPI protocol (used only by IBH Link S7++ adapter) *)
);
END_TYPE

Communication protocol (depends on the hardware used).

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

TF661026 Version: 1.1

6.1.3.3 E_NLinkTransport

TYPE E_NLinkTransport:
(
eNLinkTransport_TCPIP:=0
);
END_TYPE

Transport protocol (determines how the data are to be transported). Only the stream-oriented TCP/IP
protocol is supported at present.

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

6.1.3.4 E_NLinkOpState

TYPE E_NLinkOpState:
(
eNLinkOpState_STOP:=0,
eNLinkOpState_START:=1,
eNLinkOpState_RUN:=2,
eNLinkOpState_UNKNOWN:=3
);
END_TYPE

API

Operational state (only S7);

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

6.1.3.5 ST_NLinkDebug

Via these parameters the debug outputs can be activated/deactivated during troubleshooting (standard
setting: inactive)
The debug outputs are shown in the log view of the TwinCAT System Manager.

TYPEST_NLinkDebug:
STRUCT
eTx:E_DbgDirection:=eDbgDirection_OFF;
eRx:E_DbgDirection:=eDbgDirection_OFF;
bState:BOOL:=TRUE;
END_STRUCT
END_TYPE

eTx: Activates/deactivates the debug output for the send buffer (Type: E_DbgDirection).

eRx: Activates/deactivates the debug output for the receive buffer (Type: E_DbgDirection).

bState: Activates/deactivates status messages when establishing or closing the socket connection.

TF6610 27Version: 1.1

API

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

6.1.3.6 ST_NLinkSettings

TYPE ST_NLinkSettings:
STRUCT
sSrvNetID:T_AmsNetID:='';
eProtocol:E_NLinkProtocol:=eNLinkProtocol_IBH_SX_PP;
eTransport:E_NLinkTransport:=eNLinkTransport_TCPIP;
sHost:T_IPv4Addr:='127.0.0.1';
nPort:UDINT:=2002;
local_T_selector:STRING:='00 01';
remote_T_selector:STRING:='00 01';
bServer:BOOL:=FALSE;
bThrottle:BOOL:=FALSE;
debug:ST_NLinkDebug;
END_STRUCT
END_TYPE

sSrvNetID: TwinCAT network address of the TwinCAT TCP/IP connection server (default = empty string,
type: T_AmsNetId).

eProtocol: The communication protocol to be used is set via this parameter (type: E_NLinkProtocol [}26]).

eTransport: The transport protocol to be used is set via this parameter (type: E_NLinkTransport [}27]).

sHost: String containing the network address (Ipv4) of the communication partner (default = ‘127.0.0.1’,

type: T_IPv4Addr).

nPort: Internet Protocol (IP) port (default = 2002).

local_T_selector : Local TSAP address (reserved).

remote_T_selector : Remote TSAP address (reserved).

bServer: FALSE = client (active) connection. TRUE = server (passive) connection. Currently only client

connections are permitted.

bThrottle: If this parameter is set, the number of polling socket calls is reduced if no or few data are
received, i.e. the poll cycle is slowed down, thereby reducing the system load (default = FALSE).

debug: Optional debug output settings(type:ST_NLinkDebug [}27]).

Hint!

Background information about the configuration of eProtocol- and eTransport parameter:

The IBHsoftec S7++ adapter is supporting more than one communication protocol (channel) to S7 controller.

• Using the Hilscher MPI-Protokoll + TCP/IP as transport protocol.

• Using the IBHsoftec S5++/S7++ protocol + RFC1006 as transport protocol.

The TwinCAT S5/S7 communication library is supporting only the first communication channel (using TCP/IP
transport protocol).
If you want to communicate with S7 controller then use this settings:

eProtocol := eNLinkProtocol_MPI;
eTransport := eNLinkTransport_TCPIP;

If you want to communicate with S5 controller then use this settings:

TF661028 Version: 1.1

API

eProtocol := eNLinkProtocol_IBH_SX_PP;
eTransport := eNLinkTransport_TCPIP;

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

6.1.3.7 T_HNLINK

A variable of this type represents a network connection handle. The structural elements should not be written
to or modified directly. Variables of this type are used for internal data exchange.
One instance is required for each network connection (TwinCAT system<->Ethernet LAN adapter<->external
controller). The same instance is then transferred to other communication blocks as VAR_IN_OUT
parameter.

TYPE T_HNLINK :
STRUCT
END_STRUCT
END_TYPE

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

6.1.4 Global Constants

6.1.4.1 Overview

Name Value Description

MAX_NLINK_BUFFER_SIZE 16#FFFF Max. internal buffer size for RX/TX (64k)

MAX_NLINK_DATALEN 2048 Max. data length supported by the PLC blocks for

transfers. The actual max. length may be smaller due to
specific device characteristics.

MAX_NLINK_HEADERLEN 16 Max. length of the frame header for the NL-MPI and

IBHNet protocols.

MAX_NLINK_MPI_CONNECTIONS16 Max. number of open MPI connections. If this number is

exceeded, the oldest connections are closed
automatically.

TF6610 29Version: 1.1

API

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

6.1.4.2 Library version

All libraries have a specific version. This version is shown in the PLC library repository too.
A global constant contains the library version information:

Global_Version

VAR_GLOBAL CONSTANT
stLibVersion_Tc2_S5S7Com : ST_LibVersion;
END_VAR

stLibVersion_Tc2_S5S7Com: version information of Tc2_S5S7Com library (type: ST_LibVersion).To
compare the existing version to a required version the function F_CmpLibVersion (defined in Tc2_System
library) is offered.

Hint: All other possibilities known from TwinCAT2 libraries to query a library version are obsolete!

Requirements

Development environment Target platform PLC libraries to include

TwinCAT V3.1.4016 or higher PC oder CX (x86, x64, ARM) Tc2_S5S7Com (Communication->TcpIp)

Tc2_TcpIp (Communication->TcpIp)
Tc2_Utilities (System)

TF661030 Version: 1.1