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_TcOpcUA

TS6100 | TwinCAT PLC Lib: OpcUA

Overview of the defined OPC UA Function Blocks

FB_TcOpcUAOpen

FB_TcOpcUAReadValue

FB_TcOpcUAWriteValue

FB_TcOpcUAClose

Server Function Blocks

FB_TcOpcUAServer

FB_TcOpcUAServerGetStatus

Development environment | Target system type | PLC libraries to be linked
TwinCAT v2.11, build 1548 onwards | PC (i386) | TcOpcUA.Lib


E_OpcUA_NodeIDType

ENUM E_OpcUA_NodeIDType

E_OpcUA_NodeIDType

TYPE E_OpcUA_NodeIDType:
(
        eOpcUA_NodeIDType_String        := 1,
        eOpcUA_NodeIDType_Numeric       := 2,
        eOpcUA_NodeIDType_GUID  := 3
);
END_TYPE

NodeID can be of type String, Numeric or GUID.

Development environment | Target system type | PLC libraries to be linked


E_OpcUA_SecurityMsgMode

ENUM E_OpcUA_SecurityMsgMode

E_OpcUA_SecurityMsgMode

TYPE E_OpcUA_SecurityMsgMode:
(
        eOpcUA_SecurityMsgMode_None     :=1,
        eOpcUA_SecurityMsgMode_Sign     :=2,
        eOpcUA_SecurityMsgMode_Sign_Encrypt     :=3
);
END_TYPE

Security message mode can be None, Sign or Sign and Encrypt.

Development environment | Target system type | PLC libraries to be linked


E_OpcUA_SecurityPolicy

ENUM E_OpcUA_SecurityPolicy

E_OpcUA_SecurityPolicy

TYPE E_OpcUA_SecurityPolicy:
(
        eOpcUA_SecurityPolicy_None              := 1,
        eOpcUA_SecurityPolicy_Basic128  := 2,
        eOpcUA_SecurityPolicy_Basic128Rsa15     := 3,
        eOpcUA_SecurityPolicy_Basic256  := 4
);
END_TYPE

Opc UA Security Policy can be

None : a policy used for configurations with lowest security needs

Basic128 : a policy used for low to medium secure configurations.

Basic128Rsa15 : defines a Security Policy for medium to highly secure configurations.

Basic256 : defines a Security Policy for configurations with high security needs

Development environment | Target system type | PLC libraries to be linked


E_OpcUA_TransportProfile

ENUM E_OpcUA_TransportProfile

E_OpcUA_TransportProfile

TYPE E_OpcUA_TransportProfile:
(
        eOpcUA_TransportProfileUri_UATcp                := 1,
        eOpcUA_TransportProfileUri_WSHttpBinary         := 2,
        eOpcUA_TransportProfileUri_WSHttpXmlOrBinary    := 3,
        eOpcUA_TransportProfileUri_WSHttpXml    := 4
);
END_TYPE

Transport profile can be TCP, HTTP Binary, HTTP XML or Binary or HTTP XML.

Development environment | Target system type | PLC libraries to be linked


E_OpcUAServerOption

ENUM E_OpcUAServerOption

E_OpcUAServerOption

TYPE E_OpcUAServerOption:
(
        eOPCUASERVER_NONE               := 0,
        eOPCUASERVER_RESTART    := 1,
        eOPCUASERVER_SHUTDOWN   := 2,
        eOPCUASERVER_REFRESHCFG         := 3,
        eOPCUASERVER_SERVERINFO         := 4
);
END_TYPE

With this data type you can mention the server service required. The different services are explained below.

eOPCUASERVER_NONE := 0
None
eOPCUASERVER_RESTART := 1
With this option you have the possibility to restart the TcOpcUAServer
eOPCUASERVER_SHUTDOWN := 2
TwinCAT OPC UA Server shutdown can be done with this option

eOPCUASERVER_REFRESHCFG := 3
The variable configuration can be refreshed with this option.
eOPCUASERVER_SERVERINFO := 4
Server information like number of session active, rejected number of sessions, session timeout count etc. can be read using this option.

Development environment | Target system type | PLC libraries to be linked


E_OpcUAServerStatus

ENUM E_OpcUAServerStatus

E_OpcUAServerStatus

TYPE E_OpcUAServerStatus:
(
        eOPCUAServerStatus_NONE                 := 0,
        eOPCUAServerStatus_Alive                := 1,
        eOPCUAServerStatus_NotResponding        := 2
);
END_TYPE

OPC UA Server status can be either Alive or NotResponding. Value 0 is invalid and hence represents no status.

Development environment | Target system type | PLC libraries to be linked


ST_OpcUA_NodeID

STRUCT ST_OpcUA_NodeID

ST_OpcUA_NodeID

TYPE ST_OpcUA_NodeID:
STRUCT
        eNodeIDType     : E_OpcUA_NodeIDType;              (* String *)
        sNamespaceName  : STRING(MAX_STRING_LENGTH);  (* PLC1 *)
        sIdentifier     : STRING(MAX_STRING_LENGTH);  (* MAIN.Temp *)
END_STRUCT
END_TYPE

eNodeIDType: NodeID type can be selected with this variable. Please see E_OpcUA_NodeIDType.

sNamespaceName: Namespace name.

sIdentifier: Object to be read or written. Object can be a variable, array or structure.

Development environment | Target system type | PLC libraries to be linked


ST_OpcUA_SessionConnectInfo

STRUCT ST_OpcUA_SessionConnectInfo

ST_OpcUA_SessionConnectInfo

TYPE ST_OpcUA_SessionConnectInfo:
STRUCT
        sApplicationUri                 : STRING(MAX_STRING_LENGTH);
        sApplicationName                : STRING(MAX_STRING_LENGTH);

        eSecurityMode           : E_OpcUA_SecurityMsgMode;
        eSecurityPolicyUri      : E_OpcUA_SecurityPolicy;
        eTransportProfileUri    : E_OpcUA_TransportProfile;

        nSessionTimeout                 : UDINT;
        nConnectTimeout                 : UDINT;
END_STRUCT
END_TYPE

sApplicationUri: Application Uri with a maximum string length of 255. MAX_STRING_LENGTH is a global constant defined in TcSystem.lib, set to a value of 255.

sApplicationName: Application name with a maximum string length of 255. MAX_STRING_LENGTH is a global constant defined in TcSystem.lib, set to a value of 255.

eSecurityMode: Security message mode. See the available modes here E_OpcUA_SecurityMsgMode.

eSecurityPolicyUri: Security policy Uri. See the available security policy uri's here E_OpcUA_SecurityPolicy.

eTransportProfileUri: Transport profile Uri. See the available transport profile uri's here E_OpcUA_TransportProfile;

nSessionTimeout: Session timeout value.

nConnectTimeout: Connection timeout value.

Development environment | Target system type | PLC libraries to be linked


ST_OpcUAServerInfo

STRUCT ST_OpcUAServerInfo

ST_OpcUAServerInfo

TYPE ST_OpcUAServerInfo:
STRUCT
        nReserved                       : UDINT;
        nCummulatedSessionCount                 : UDINT;
        nCurrentSessionCount            : UDINT;
        nRejectedSessionCount           : UDINT;
        nSecurityRejectedSessionCount   : UDINT;
        nSessionTimeoutCount            : UDINT;
        nCurrentSubscriptionCount               : UDINT;
        nRejectedRequestCount           : UDINT;
        nSecurityRejectedRequestCount   : UDINT;
END_STRUCT
END_TYPE

nReserved : Reserved.

nCummulatedSessionCount : Total session count.

nCurrentSessionCount : Current session count.

nRejectedSessionCount : Session count rejected.

nSecurityRejectedSessionCount : Session count rejected due to security.

nSessionTimeoutCount : Session timeout count.

nCurrentSubscriptionCount : Current subscription count.

nRejectedRequestCount : Requests rejected.

nSecurityRejectedRequestCount : Requests rejected due to security.

Development environment | Target system type | PLC libraries to be linked


FB_OpcUAOpen

FUNCTION_BLOCK FB_OpcUAOpen

With this function block the Opc UA session can be opened.

VAR_INPUT

      VAR_INPUT
        sNetID                  : T_AmsNetId;
        bExecute                        : BOOL;
        sURL                    : STRING(MAX_STRING_LENGTH);
        stSessionConnectInfo    : ST_OpcUA_SessionConnectInfo;
        tTimeout                        : TIME := DEFAULT_ADS_TIMEOUT;
END_VAR

sNetID : Is a string containing the AMS network identifier of the target device to which the command is directed..

bExecute : The command is triggered by a rising edge at this input.

sURL : Opc UA device URL. e.g. 'opc.tcp://172.16.3.207:4840' or 'opc.tcp://CX_0193BF:4840'.

stSessionConnectInfo : Information for session connection. Please see ST_OpcUA_SessionConnectInfo.

tTimeout : States the time before the function is cancelled. DEFAULT_ADS_TIMEOUT is a global constant in TcSystem.lib set to 5 seconds.

VAR_OUTPUT

      VAR_OUTPUT
        bBusy           : BOOL;
        bError          : BOOL;
        nErrorID                : UDINT;
        hSession                : UDINT;
END_VAR

bBusy: This output remains TRUE until the block has executed a command, but at the longest for the duration supplied to the ‘Timeout’ input. While Busy = TRUE, no new command will be accepted at the inputs. Please note that it is not the execution of the service but its acceptance whose time is monitored.

bError: This output is switched to TRUE if an error occurs during the execution of a command. The command-specific error code is contained in ‘nErrorID’.

nErrorID: Contains the command-specific ADS error code of the most recently executed command.

hSession : OPC UA Session handle.

Development environment | Target system type | PLC libraries to be linked


FB_OpcUAReadValue

FUNCTION_BLOCK FB_OpcUAReadValue

With function block FB_OpcUAReadValue, objects like variables, structures, arrays in PLC on a local (another runtime) or remote device can be read.

VAR_INPUT

      VAR_INPUT
        sNetID          : T_AmsNetId;
        bExecute                : BOOL;
        hSession                : UDINT;
        stNodeID                : ST_OpcUA_NodeID;
        nLength         : UDINT;
        pBuffer                 : UDINT;
        tTimeout                : TIME := DEFAULT_ADS_TIMEOUT;
END_VAR

sNetID : Is a string containing the AMS network identifier of the target device to which the command is directed..

bExecute : The command is triggered by a rising edge at this input.

hSession : OPC UA Session handle received by FB_OpcUAOpen call.

stNodeID : Information of node from where the data is to be read. Please see ST_OpcUA_NodeID.

nLength : Contains the number, in bytes, of the data to be read.

pBuffer : Contains the address of the buffer which is to receive the data that has been read. The programmer is himself responsible for dimensioning the buffer to a size that can accept ‘nLength’ bytes. The buffer can be a single variable, an array or a structure, whose address can be found with the ADR operator.

tTimeout : States the time before the function is cancelled. DEFAULT_ADS_TIMEOUT is a global constant in TcSystem.lib set to 5 seconds.

VAR_OUTPUT

      VAR_OUTPUT
        Busy            : BOOL;
        Error           : BOOL;
        ErrorID                 : UDINT;
        nReadLength     : UDINT;
END_VAR

bBusy : This output remains TRUE until the block has executed a command, but at the longest for the duration supplied to the ‘Timeout’ input. While Busy = TRUE, no new command will be accepted at the inputs. Please note that it is not the execution of the service but its acceptance whose time is monitored.

bError : This output is switched to TRUE if an error occurs during the execution of a command. The command-specific error code is contained in ‘nErrorID’.

nErrorID : Contains the command-specific ADS error code of the most recently executed command.

nReadLength : Number of successfully returned data bytes.

Development environment | Target system type | PLC libraries to be linked


FB_OpcUAWriteValue

FUNCTION_BLOCK FB_OpcUAWriteValue

With function block FB_OpcUAWriteValue, objects like variables, structures, arrays in PLC on a local (another runtime) or remote device can be written.

VAR_INPUT

      VAR_INPUT
        sNetID          : T_AmsNetId;
        bExecute                : BOOL;
        hSession                : UDINT;
        stNodeID                : ST_OpcUA_NodeID;
        nLength         : UDINT;
        pBuffer                 : UDINT;
        tTimeout                : TIME := DEFAULT_ADS_TIMEOUT;
END_VAR

sNetID : Is a string containing the AMS network identifier of the target device to which the command is directed..

bExecute : The command is triggered by a rising edge at this input.

hSession : OPC UA Session handle received by FB_OpcUAOpen call.

stNodeID : Information of node to which the data is to be written. Please see ST_OpcUA_NodeID.

nLength : Contains the number, in bytes, of the data to be read.

pBuffer : Contains the address of the buffer from which the data to be written is to be fetched. The programmer is himself responsible for dimensioning the buffer to such a size that ‘nLength’ bytes can be taken from it. The buffer can be a single variable, an array or a structure, whose address can be found with the ADR operator.

tTimeout : States the time before the function is cancelled. DEFAULT_ADS_TIMEOUT is a global constant in TcSystem.lib set to 5 seconds.

VAR_OUTPUT

      VAR_OUTPUT
        bBusy           : BOOL;
        bError          : BOOL;
        nErrorID                : UDINT;
END_VAR

bBusy: This output remains TRUE until the block has executed a command, but at the longest for the duration supplied to the ‘Timeout’ input. While Busy = TRUE, no new command will be accepted at the inputs. Please note that it is not the execution of the service but its acceptance whose time is monitored.

bError: This output is switched to TRUE if an error occurs during the execution of a command. The command-specific error code is contained in ‘nErrorID’.

nErrorID: Contains the command-specific ADS error code of the most recently executed command.

Development environment | Target system type | PLC libraries to be linked


FB_OpcUAClose

FUNCTION_BLOCK FB_OpcUAClose

With this function block the Opc UA session opened by FB_OpcUAOpen can be closed.

VAR_INPUT

      VAR_INPUT
        sNetID          : T_AmsNetId;
        bExecute                : BOOL;
        hSession                : UDINT;                (* OPC UA Session handle *)
        tTimeout                : TIME := DEFAULT_ADS_TIMEOUT;
END_VAR

sNetID : Is a string containing the AMS network identifier of the target device to which the command is directed..

bExecute : The command is triggered by a rising edge at this input.

hSession : Is assigned by the Opc UA sesion handle created with FB_OpcUAOpen.

tTimeout : States the time before the function is cancelled. DEFAULT_ADS_TIMEOUT is a global constant in TcSystem.lib set to 5 seconds.

VAR_OUTPUT

      VAR_OUTPUT
        bBusy           : BOOL;
        bError          : BOOL;
        nErrorID                : UDINT;
END_VAR

bBusy: This output remains TRUE until the block has executed a command, but at the longest for the duration supplied to the ‘Timeout’ input. While Busy = TRUE, no new command will be accepted at the inputs. Please note that it is not the execution of the service but its acceptance whose time is monitored.

bError: This output is switched to TRUE if an error occurs during the execution of a command. The command-specific error code is contained in ‘nErrorID’.

nErrorID: Contains the command-specific ADS error code of the most recently executed command.

Development environment | Target system type | PLC libraries to be linked


FB_OpcUAServer

FUNCTION_BLOCK FB_OpcUAServer

This function block integrates different OPC UA Server functionalities like get server information, refresh server configuration, server restart and server shutdown.

VAR_INPUT

      VAR_INPUT
        sNetID          : T_AmsNetId;
        bExecute                : BOOL;
        eOpcUAServerOption      : E_OpcUAServerOption;
        tTimeout                : TIME := DEFAULT_ADS_TIMEOUT;
END_VAR

sNetID : Is a string containing the AMS network identifier of the target device to which the command is directed..

bExecute : The command is triggered by a rising edge at this input.

eOpcUAServerOption : Is a enum stating the desired command. Please see E_OpcUAServerOption.

tTimeout : States the time before the function is cancelled. DEFAULT_ADS_TIMEOUT is a global constant in TcSystem.lib set to 5 seconds.

VAR_OUTPUT

      VAR_OUTPUT
        stOpcUAServerInfo       : ST_OpcUAServerInfo;
        bBusy           : BOOL;
        bError          : BOOL;
        nErrorID                : UDINT;
END_VAR

stOpcUAServerInfo : server information please see ST_OpcUAServerInfo

bBusy: This output remains TRUE until the block has executed a command, but at the longest for the duration supplied to the ‘Timeout’ input. While Busy = TRUE, no new command will be accepted at the inputs. Please note that it is not the execution of the service but its acceptance whose time is monitored.

bError: This output is switched to TRUE if an error occurs during the execution of a command. The command-specific error code is contained in ‘nErrorID’.

nErrorID: Contains the command-specific ADS error code of the most recently executed command.

Development environment | Target system type | PLC libraries to be linked


FB_OpcUAServerGetStatus

FUNCTION_BLOCK FB_OpcUAServerGetStatus

This function block delivers server status.

VAR_INPUT

      VAR_INPUT
        sNetID          : T_AmsNetId;
        bGetStatus      : BOOL;
        tTimeout                : TIME := DEFAULT_ADS_TIMEOUT;
END_VAR

sNetID : Is a string containing the AMS network identifier of the target device to which the command is directed..

bGetStatus : The command is executed if this input is TRUE.

tTimeout : States the time before the function is cancelled. DEFAULT_ADS_TIMEOUT is a global constant in TcSystem.lib set to 5 seconds.

VAR_OUTPUT

      VAR_OUTPUT
        eOpcUAServerStatus      : E_OpcUAServerStatus;
        bDone                   : BOOL;
        bBusy                   : BOOL;
        bError                  : BOOL;
        nErrorID                        : UDINT;
END_VAR

eOpcUAServerStatus : OPC UA Server status can be either Alive or NotResponding. Value 0 is invalid and hence represents no status.

bDone: This output is set to true, once the command is executed without any error.

bBusy: This output remains TRUE until the block has executed a command, but at the longest for the duration supplied to the ‘Timeout’ input. While Busy = TRUE, no new command will be accepted at the inputs. Please note that it is not the execution of the service but its acceptance whose time is monitored.

bError: This output is switched to TRUE if an error occurs during the execution of a command. The command-specific error code is contained in ‘nErrorID’.

nErrorID: Contains the command-specific ADS error code of the most recently executed command.

Development environment | Target system type | PLC libraries to be linked


F_GetVersionTcOpcUA

FUNCTION F_GetVersionTcOpcUA

The function returns library version info.

FUNCTION F_GetVersionTcOpcUA : UINT

VAR_INPUT
        nVersionElement : INT;
END_VAR

nVersionElement : Version parameter:

  • 1 : major number;
  • 2 : minor number;
  • 3 : revision number;
Development environment | Target system type | PLC libraries to include
TwinCAT v2.11.0 | PC (i386) | TcOpcUA.Lib


TcOpcUA_Samples_PLCOpen_BoilerControl

TS6100 | TwinCAT PLC Lib: OpcUA

Sample of TcOpcUA

Download PLCOpen BoilerControl Sample


TcOpcUA_Samples_ReadWriteInt

Read and Write Integer Variable

Download Read and Write Integer Variable Sample

In this example program, the value of nIntVar in PLC project BoilerControl_0_01_06+Light+HDA_Int.pro is read into 'nIntRead' variable in TcOpcUA_SampleInt.pro. Once the value of 'nIntRead' has reached 1000, the variable 'nIntVar' in PLC project BoilerControl_0_01_06+Light+HDA_Int.pro is set back to zero.

Screenshot from BoilerControl_0_01_06+Light+HDA_Int.pro Global_Variables. 'nIntVar' is incremented every PLC cycle by 1 in MAIN.

Above the screenshot from TcOpcUA_SampleInt.pro showing the function call FB_OpcUAReadValue to read Integer variable value into 'nIntRead' variable. Following this is a function block call of FB_OpcUAWriteValue to write the value from 'nIntWrite' on 'nIntVar' variable.

It is necessary to include TcOpcUA.Lib in TcOpcUA_SampleInt.pro PLC project.

NOTE: To start the TcOpcUA_SampleInt.pro please force the 'bTest' variable to TRUE. To reconnect in case of link lost or error please force again 'bTest' variable to TRUE.


TcOpcUA_Samples_ReadByteArray

Read Byte Array

Download Read Byte Array Sample

In this example program, the value of 'arrByte' (array of bytes with 20 elements) in PLC project BoilerControl_0_01_06+Light+HDA_ByteArray.pro is read into 'arrRead' variable in TcOpcUA_SampleByteArray.pro.

Above is screenshot from BoilerControl_0_01_06+Light+HDA_ByteArray.pro Global_Variables. Every element in 'arrByte' is incremented every PLC cycle by 1 in MAIN.

Above is a screenshot from TcOpcUA_SampleByteArray.pro showing the function call FB_OpcUAReadValue to read byte array elements value into 'arrRead' variable.

It is necessary to include TcOpcUA.Lib in TcOpcUA_SampleByteArray.pro PLC project.

NOTE: To start the TcOpcUA_SampleByteArray.pro please force the 'bTest' variable to TRUE. To reconnect in case of link lost or error please force again 'bTest' variable to TRUE.


TcOpcUA_Samples_ReadWriteStructure

Read and Write Structure

Download Read and Write Structure Sample

In this example program, the value of 'stStuct1' in PLC project BoilerControl_0_01_06+Light+HDA_Structure.pro is read into 'stStructRead' structure in TcOpcUA_SampleStructure.pro. Once the value of 'stStructRead.nDint' is divisible by 100, the structure is changed and copied into 'stStruct2' in PLC project BoilerControl_0_01_06+Light+HDA_Structure.pro. 'stStruct2.arrBool[0]' is toggled and 'stStruct2.sString' is changed between 'BECKHOFF' and 'OPC UA CLIENT'.

Structure elements are as shown below:

TYPE ST_Structure :
STRUCT
nDint : DINT;
arrBool : ARRAY [0..3] OF BOOL;
sString : STRING(11);
END_STRUCT
END_TYPE

Above is screenshot from BoilerControl_0_01_06+Light+HDA_Structure.pro Global_Variables. 'stStruct1.nDint' is incremented every PLC cycle by 1 in MAIN.

Above the screenshot from TcOpcUA_SampleStructure.pro showing the function call FB_OpcUAReadValue to read structure value into 'stStructRead' variable. Following this is a function block call of FB_OpcUAWriteValue to write the value from 'stStructWrite' on 'stStruct2'.

It is necessary to include TcOpcUA.Lib in TcOpcUA_SampleStructure.pro PLC project.

NOTE: To start the TcOpcUaA_SampleStructure.pro please force the 'bTest' variable to TRUE. To reconnect in case of link lost or Error please force again 'bTest' variable to TRUE.