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 PLC library TcCPLink3.Lib belongs to the product CP-Link 3 . The CP-Link 3 installation copies this library to the folder ..\TwinCAT\Lib . The PLC library contains CP-Link 3 functions and function blocks.


FB_CPLink3_AcquireHIDFocus

TwinCAT PLC Library: CP-Link 3

FUNCTION_BLOCK FB_CPLink3_AcquireHIDFocus

This function block is used to acquire or release the HID focus.

VAR_IN_OUT

VAR_IN_OUT
    hFocus 	: T_HCPLink3HidFocus;(* CPLink3 HID focus handle *)
END_VAR

hFocus: CP-Link3 HID focus handle.

VAR_INPUT

VAR_INPUT
    bEnable 	: BOOL := FALSE;(* TRUE = Acquire, FALSE = Release focus *)
    setIP 	: T_IPv4Addr := '';
END_VAR

bEnable: TRUE = acquire focus, FALSE = release focus.

setIP: The IP address of the client.

VAR_OUTPUT

VAR_OUTPUT
    bAcquired 	: BOOL := FALSE;(* Focus status information *)
    bLED 		: BOOL := FALSE;(* LED control output *)
    bBusy 		: BOOL;(* TRUE => function in progress *)
    bError 		: BOOL;(* Error flag *)
    nErrID 		: UDINT;(* Error code *)
END_VAR

bAcquired: This output is set when the client gets the focus and is reset when the client looses the focus.

bLED: This meaning of this output depends on the output mode:

Mode | Meaning
Constant TRUE | The client has the focus.
Constant FALSE | The client does not have the focus.
Toggles | The client is waiting for the focus.

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

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

nErrID: When the bError output is set, this variable supplies the ADS error code.

Example: Example Program: Controlling the HID focus through special keys

Manually setting the HID focus can, for instance, be controlled by a clients special key. The special key is linked to the corresponding input variable in the PLC program through the TwinCAT System Manager. An instance of FB_CPLink3_AcquireHidFocus is generated for each client, and configured with the client's IP address. After the special key at a client is pressed, where the rising edge will be detected by the R_TRIG function block, the PLC program will attempt to set the HID focus through the corresponding instance of FB_CPLink3_AcquireHidFocus. The function block can, in addition, control an output (e.g. a LED) that indicates whether the HID focus has successfully been set, or whether it is still attempting to obtain the focus. Pressing the special key again resets the HID focus.

The three instances of the FB_CPLink3_AcquireHidFocus function block use the hFocus variable to exchange information between each other. This is used, for instance, to ensure that only the instance that has successfully set the HID focus is able to reset it.

The PLC program for three clients looks like this:

PROGRAM MAIN
VAR
    button1 AT%IX0.0 : BOOL;
    button2 AT%IX0.1 : BOOL;
    button3 AT%IX0.2 : BOOL;

    led1 AT%QX0.0 : BOOL;
    led2 AT%QX0.1 : BOOL;
    led3 AT%QX0.2 : BOOL;

    hFocus : T_HCPLink3HidFocus;
    fbPanel1 : FB_CPLink3_AcquireHidFocus := ( setIP := '192.168.1.1' );
    fbPanel2 : FB_CPLink3_AcquireHidFocus := ( setIP := '192.168.1.2' );
    fbPanel3 : FB_CPLink3_AcquireHidFocus := ( setIP := '192.168.1.3' );

    trigger1 : R_TRIG;
    trigger2 : R_TRIG;
    trigger3 : R_TRIG;
END_VAR
(* Panel 1 *)
trigger1( CLK := button1 );
IF trigger1.Q THEN
    fbPanel1.bEnable := NOT fbPanel1.bEnable;
END_IF
fbPanel1( hFocus:= hFocus, bLED=>LED1);

(* Panel 2 *)
trigger2( CLK := button2 );
IF trigger2.Q THEN
    fbPanel2.bEnable := NOT fbPanel2.bEnable;
END_IF
fbPanel2( hFocus:= hFocus, bLED=>LED2 );

(* Panel 3 *)
trigger3( CLK := button3 );
IF trigger3.Q THEN
    fbPanel3.bEnable := NOT fbPanel3.bEnable;
END_IF
fbPanel3( hFocus:= hFocus, bLED=>LED3 );

Development environment | Target system type | PLC libraries to include
TwinCAT v2.10.0 and higher | PC | TcCPLink3.Lib


F_GetVersionTcCPLink3

TwinCAT PLC Library: CP-Link 3

FUNCTION F_GetVersionTcCPLink3

This function returns library version information.

FUNCTION F_GetVersionTcCPLink3 : UINT

VAR_INPUT
    nVersionElement : INT;
END_VAR

nVersionElement: Version element to be read. Possible parameter:

  • 1: major number
  • 2: minor number
  • 3: revision number
Development environment | Target system type | PLC libraries to include
TwinCAT v2.10.0 and higher | PC | TcCPLink3.Lib


T_HCPLink3HidFocus

TwinCAT PLC Library: CP-Link 3

TYPE T_HCPLink3HidFocus

CP-Link3 HID focus handle: used by several instances of the function block FB_CPLink3_AcquireHIDFocus to exchange information between each other.

TYPE T_HCPLink3HidFocus:
END_TYPE
Development environment | Target system type | PLC libraries to include
TwinCAT v2.10.0 Build and higher | PC | TcCPLink3.Lib