interfaces mvtec

Dokumentation

OPC_UA I/O Interface for OPC UA compliant devices

Interface: OPC_UA
Revision: 19.11.4
Date: 2021-10-20
This software uses / is based on C++ based OPC UA SDK Copyright (C) Unified Automation GmbH. All rights reserved.

This software is based in part on OPC UA Ansi C Stack of the OPC Foundation. Initial version of OPC UA Ansi C Stack was founded and copyrighted by OPC Foundation, Inc. Copyright (C) 2008, 2014 OPC Foundation, Inc., All rights reserved.

This product includes cryptographic software written by Eric Young (eay@cryptsoft.com) This Windows version of this product includes software written by Tim Hudson (tjh@cryptsoft.com) Copyright (C) 1998-2007 The OpenSSL Project. All rights reserved.

This product includes code that was developed for the XML toolkit from the GNOME project xmlsoft. Copyright (C) 1998-2003 Daniel Veillard. All Rights Reserved.

General

This page provides the documentation of the HALCON OPC UA interface. Only interface-specific parameters and features are described here. For general information of the operators for I/O interfaces please have a look at the HALCON Operator Reference.
Registered customers can download the latest revision of this interface from the MVTec WWW server.

System Requirements

  • Intel compatible PC with Windows 7 (32-bit or 64-bit) or newer that is also supported by the vendor-specific SDK, also WoW64 (using 32-bit HALCON on 64-bit Windows), Linux with kernel 2.6 (or higher), or OS X 10.8/10.9.
  • Windows: HALCON I/O device interface hioOPC_UA.dll or hioOPC_UAxl.dll, respectively. Also required are libcrypto-1_1.dll, libssl-1_1.dll, and uastack.dll. If you have properly installed the interface, all these DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
  • Linux: HALCON I/O device interface hioOPC_UA.so or hioOPC_UAxl.so, respectively. Also required are the 3rd party libraries libcrypto.so.1.1, libssl.so.1.1, and libuastack.so. If you have properly installed the interface, the shared objects should reside in lib/$HALCONARCH, and the 3rd party shared libraries in lib/$HALCONARCH/thirdparty within the HALCON base directory $HALCONROOT you have chosen during the installation of HALCON.
  • MacOS: HALCON I/O device interface hioOPC_UA.dylib or hioOPC_UAxl.dylib, respectively. Also required are libcrypto.dylib.1.1, libssl.dylib.1.1, and libuastack.dylib. If you have properly installed the interface, the shared objects should reside in the HALCON framework /Library/Frameworks/HALCON.framework or the HALCON XL framework /Library/Frameworks/HALCONxl.framework in the Libraries subdirectory.

Interface Versioning

MVTec interfaces for digital I/O and image acquisition are always compatible to a range of HALCON versions. Therefore, the versioning scheme both describes the compatibility of the interface and also the revision of the interface itself. An interface version always consists of three numbers, separated by dots, i.e. 18.11.5. The first two numbers describe the minimum HALCON version the interface is compatible with. For the example version 18.11.5 this means that the interface is compatible with all HALCON versions since HALCON 18.11. The last number describes the revision of the interface, in this example this is revision 5.

Installation

Only when installing or updating the interface manually follow these steps:
  • Windows: Extract the archive containing the interface files to the HALCON base directory %HALCONROOT% (Note: Administrator privileges may be required for this step). Additionally, you have to move the interface examples to the directory %HALCONEXAMPLES% manually.
  • Linux: Extract the archive containing the interface files to the HALCON base directory $HALCONROOT.
  • OS X: Extract the archive. Manually move the following files:
    • The .dylib files located in lib/x64-macosx to /Library/Frameworks/HALCON.framework/Libraries
    • The examples folder to the version subdirectory at /Users/Shared/Library/Application Support
    • The doc folder to the version subdirectory at /Library/Application Support

Features

  • Implementation of an OPC UA client.

Limitations

  • The OPC UA I/O interface returns and expects all strings in UTF-8 encoding.
  • All dates and times are assumed to be UTC.
  • The OPC UA data types 'ImageBMP', 'ImageGIF', 'ImageJPG' and 'ImagePNG' are represented as byte strings, as HALCON's I/O interface does not allow exchanging iconic data.
  • On 32-bit systems, 64-bit OPC UA integer values (both signed and unsigned) cannot be properly represented. They can only be used if the actual value fits within a 32-bit integer.
  • OPC UA node IDs are limited to a maximum of 255 characters in their XML representation. This can lead to problems with the 'translate' control_io_device action and the 'browse' query_io_device parameter if the server has very long node IDs.
  • The only types of OPC UA user tokens currently supported are Anonymous and UserPassword.
  • OPC UA multi-dimensional arrays are not supported.

Connecting to an OPC UA server

The open_io_device operator is used to connect to an OPC UA server. Specify the URL of the server to connect to in the IODeviceName parameter. The server URL is generally in the form 'opc.tcp://Server' or 'opc.tcp://Server:Port' if the server is not using the default OPC UA port (4840).

If the server you wish to connect to is registered with an OPC UA discovery server, you can get its URL from the query_io_interface operator using the 'io_device_names' generic parameter if the discovery server is reachable via the URL 'opc.tcp://localhost:4840', or from the control_io_interface operator using the 'discovery' action if it is not. Please see the example opc_ua_discovery.hdev for details.

Converting data between HALCON and OPC UA

OPC UA has a rich set of data types that have to be mapped to the HALCON control tuple data types integer, real and string on input and output. HALCON OPC UA I/O device interface supports the following built-in OPC UA data types and their derivatives:
  • NodeId
    This type is converted to or from HALCON strings following the OPC UA XML schema. The syntax is as follows:

    'ns=<namespaceindex>;<type>=<identifier>'

    <namespaceindex> is the index of the namespace, formatted as a base 10 number. If the index is 0, the entire 'ns=0;' clause can be omitted. A server's namespaces can be determined by calling the get_io_device_param operator for the 'namespaces' parameter; the namespaces are returned in the order of their indexes.

    <type> is a flag specifying the type of <identifier>. The following values are possible:

    • i (numeric) - the identifier is a number.
    • s (string) - the identifier is a string.
    • g (guid) - the identifier is a GUID string.
    • b (opaque) - the identifier is an (opaque) byte string.

    <identifier> is the identifier encoded as a string using the XML data type mapping for the identifier type. The identifier may contain any non-NULL UTF-8 character.
    Please note that due to a limitation in the OPC UA SDK used by the interface, when converting from a node ID to a HALCON string if the node ID does not fit within 255 characters, it is truncated and cannot be used to identify nodes.

  • ExpandedNodeId
    This type is converted to or from HALCON strings with the following syntax:

    '<Server>|<NamespaceURI>|<NodeId&gt'

    <Server> is the index of the server, formatted as a base 10 number.

    <NamespaceURI> is the URI of the namespace to use, overriding the namespace specified in the <NodeId>. The reserved characters & and | have to be escaped with a prefixed &, e.g. | must be written as &|.

    <NodeId> is a node ID written in the OPC UA XML schema as detailed above.

  • QualifiedName
    This type is converted to and from HALCON strings. These strings can be used directly as path elements for the translate action of control_io_device. The syntax of the string is as follows:

    '[<ns>:]<name>'

    <ns> is the (optional) namespace index, written as one or more digits and followed by a :. If the namespace is not specified, a namespace of 0 is assumed.

    <name> is the name. The reserved characters /, ., <, >, #, !, or & have to be escaped with a prefixed &, e.g. < must be written as &<.

  • LocalizedText
    These are converted to or from HALCON strings using the following syntax:

    '<locale>|<text>'

    <locale> is the locale ID as defined in RFC 3066, e.g. 'en' for English.

    <text> is the text, encoded in the specified locale.

  • Boolean
    A boolean value, translated to and from the HALCON strings 'true' and 'false'.
  • SByte, Int16, Int32, and Int64
    These types are translated to and from HALCON integer values. On 32-bit systems, 64-bit integers outside the range of a 32-bit integer cannot be represented.
  • Byte, UInt16, UInt32, and UInt64
    These types are translated to and from HALCON signed integer values. An unsigned value outside the range of HALCON's signed integers is represented as the signed integer corresponding to the bit pattern of the unsigned integer. On 32-bit systems, 64-bit integers outside the range of a 32-bit integer cannot be represented.
  • ByteString
    This data type is converted to and from a tuple of HALCON integer values in the range [0..255].
  • DateTime
    The date is translated to and from the number of seconds since January 1, 1970 as a HALCON real value.
  • Double and Float
    These types are translated to and from HALCON real values.
  • Guid, String and XmlElement
    These types are represented as HALCON strings. Please note that the OPC UA I/O interface returns and expects all strings in UTF-8 encoding.
  • X.509 certificates
    While X.509 certificates are not an OPC UA data type per se; they are used to identify servers and clients when creating secured connections. X.509 certificates are represented in HALCON as a Base64 encoded string of the DER encoding of the certificate.

    The interface supports the derivative types of the built-in OPC UA data types. These types are converted to and from HALCON data types just like the built-in OPC UA types they are derived from. However, there are some points that need to be consider when working with these types:
  • HALCON I/O interface cannot exchange iconic data, so the OPC UA Image data types are treated like the ByteString built-in type.
  • Some derivative types might have restrictions on the values they accept, please refer to your server documentation as handling these restrictions is left to the user.

    The interface also supports OPC UA complex data types that inherit from Structures, Unions, OptionSet and Enumerations. Please refer to the official documentation PART 3 'Address Space Model', PART 5 'Information Model', and PART 6 'Mappings' by the OPC Foundation if you require additional details. Please consider the following notes:
  • Enumerations
    Represent a list of defined numerical values. The nodes that inherit from this data type are always represented as Int32 by OPC UA. These nodes may have one of the two optional properties EnumStrings or EnumValues that provide the human readable representation the Enumeration values. Please see the example opc_ua_enumeration.hdev for more information.
  • Structures
    These nodes represent a group of variables (fields) that can be of any data type known to the server. Reading or writing to a Structure is done using HALCON dictionaries. The field name is used as key for the dictionary value. Structures can have mandatory and optional fields. If a field is mandatory, it will/must always be present on the dictionary. If a field is optional the value might be absent. In the case that a Structure contains fields with complex data types, the dictionary will/must contain additional dictionaries with the corresponding values. Please see the example opc_ua_structure.hdev for more information.
  • Unions
    These nodes are a special type of Structure that allows to store different data types (built-in or complex) in the same node. There can be unions with many fields, but only one field can be active at any given time. Reading or writing to a union is done using HALCON dictionaries. The 'SwitchField' key must/will always be provided when writing/reading and the value of the node must be provided by using the field name as Key for the value in the dictionary. The switch value and the field name must correspond with each other. Setting or getting a SwitchField of value 0 means that the Union is not set, so no value needs to be provided or be available. Please see the example opc_ua_union.hdev for more information.
  • OptionSet
    These nodes are a special type of Structure to represent a bit mask. Reading or writing to a union is done using HALCON dictionaries. Each OptionSet type has a property 'OptionSetValues' that contains the human-readable representation for the corresponding bit used in the OptionSet. The value of an OptionSet variable is composed of two mandatory fields 'Value' and 'ValidBits'. The field 'Value' is a ByteString representing the bits in the OptionSet. The length of the ByteString depends on the number of bits. The field 'ValidBits' is a ByteString with the same size as 'Value'. When you read an OptionSet the 'ValidBits' provides information of which bits in the bit mask have a meaning. If a bit is 1 then the corresponding bit in the value is valid. If it is set to a 0 it should be ignored. When writing a value to a variable, the 'ValidBits' defines which bits should be written. Only those bits defined in 'ValidBits' (set to 1) are changed in the bit mask, all others are not written. Please see the example opc_ua_option_set.hdev for more information.

  • Arrays
    The interface also supports one dimensional arrays. A variable node with an array of one of the base data types will be mapped to a HALCON tuple. For ByteString arrays, where each array element is mapped to a tuple, the complete array is transformed into a tuple of dictionarys. Each dictionary stores the ByteString under the special key 'h_values'. If doing a multi channel read or write, and one of the channels is an array, the array values are stored in a tuple inside a dictionary under the special key 'h_values'. If calling a method, and one of the input arguments of output arguments is an array, the array values are stored in a tuple inside a dictionary under the special key 'h_values'. Multi dimensional arrays are not supported.

Specifying OPC UA nodes

OPC UA nodes are referenced by using their node ID written as a string following the OPC UA XML schema as the channel parameter in the query_io_device and open_io_channel operators. See the section on converting OPC UA data types above on how to write node IDs. In addition to writing the namespace's index, you can also write the namespace's URI enclosed in ^ characters.

The following are all valid ways to refer to the server's ServerStatus node:

'i=2256'
'ns=0;i=2256'
'ns=^http://opcfoundation.org/UA/^;i=2256'

OPC UA Event Handling

Event handling via message queues is supported on the device-level and on the channel-level. On the device-level this can be used to receive messages when the connection status changes. For a given channel currently the only supported event is DataChange for subscribed variable nodes.

The events are handled using HALCON message queues. You can provide a message queue handle to a channel using the parameter 'event_message_queue' to receive updates as soon as the value changes on the server.

Removing a message queue from the device or from a channel is done by setting the parameter 'event_message_queue' to 0 (or HNULL). This will not cancel the variable subscription itself, the interface will continue to update the cached value in the background. To delete a subscription please refer to the relevant parameters in the documentation.

After dequeuing a message for an event, the information contained in the message can be accessed using the operator get_message_tuple. The message will always contain the following fields of information:
  • id: String composed of the name of the interface plus the address of the server. Eg. 'OPC_UA:opc.tcp://Server:Port'
  • event_name: String with the name of the triggered event. This can be 'DataChange' or 'ConnectionStatusChange'.

    Additional information is dependent on the type of event.
  • For ConnectionStatusChange events:
    • connection_status: The new status of the server connection (same values as available for 'connection_status' with get_io_device_param.
  • For DataChange events:
    • node_id: The node ID of the node that triggered the event.
    • status_code: The status code of the updated value.
    • value: The new updated value of the node.

      Message queues are handled in a FIFO manner, handling multiple variable subscriptions in the same message queue requires that you process all incoming events as they become available.
      Please see the example opc_ua_monitor_subscription.hdev and opc_ua_monitor_connection.hdev for more information.

Operator control_io_interface

control_io_interface(::IOInterfaceName, Action, Argument:Result)
Perform an action on the I/O interface.
Parameter Values Default Type Description
IOInterfaceName 'OPC_UA' [] string HALCON I/O interface name.
Action string Name of the action to perform.
     'create_certificate' Create a self-signed X509 certificate and store it in the file-based OpenSSL certificate store. This action takes 13 arguments.
          Argument '<path to certificate store>', '<basename of certificate>', <keylength>, '<URI>', '<DNS>', <valid time (in seconds)>, '<common name>', '<organization>', '<organization unit>', '<locality>', '<state>', '<country>', '<domain component>' integer, float, string The first argument is the path to the certificate store, followed by the base name to store the certificate under (without the file extension). The third argument is the keylength to use (in bits). The fourth and fifth parameters are a URI and a DNS name, respectively, used to set the "X509v9 Subject Alternative Name". The fifth parameter is the valid time of the certificate in seconds.
The final seven arguments are the common name, organization, organization unit, locality, state, country and domain component to use for the issuer and subject of the certificate.
          Result '<X.509 certificate in DER format, Base64 encoded>' string The X.509 certificate in DER format, encoded as a Base64 string.
     'discovery' Query an OPC UA discovery server to find OPC UA servers. The URL of the server to query must be passed as the only argument.
          Argument '<discovery server URL>' string The URL of the discovery server to query.
          Result 'application_type:<application type>|application_uri:<application URI>|product_uri:<product URI>|application_name:<application name>|gateway_server:<gateway server IP address>|discovery_profile_uri:<uri>|url:<server url>[url:<server url>]' string A list of OPC UA servers.
     'endpoints' If used as a parameter to get_io_device_param, returns all endpoints of the server the device is connected to. It cannot be combined with any other queries.
If used as an action for control_io_interface, returns all endpoints of the server reachable via the URL given as the only argument.
          Argument '<server URL>' string The URL of OPC UA server to query.
          Result 'endpoint_url:<server url>[|server_certificate:<certificate>]|message_security_mode:<mode>|security_policy_uri:<policy>|transport_profile_uri:<profile>|security_level:<level>' string A list of OPC UA endpoints.
     'parse_certificate' Take OpenSSL certificates in DER form and translate them into a human readable string presentation.
          Argument '<X.509 certificate in DER format, Base64 encoded>' string X.509 certificate(s) in DER format, encoded as a Base64 string(s).
          Result 'CommonName:<common name>|Issuer.commonName:<common name of issuer>|Issuer.organization:<organization of issuer>|Issuer.organizationUnit:<organization unit of issuer>|Issuer.state:<state of issuer>|Issuer.country:<country of issuer>|ValidFrom:<valid from date>|ValidTo:<valid to date>' string
     'save_certificate' Save an OpenSSL certificate in the file-based OpenSSL certificate store.
          Argument '<Path to the certificate store>', '<Basename of certificate>', '<X.509 certificate in DER format, Base64 encoded>' string The first argument is the path to the certificate store, followed by the base name of the certificate (i.e., without the file extension). The final argument is the certificate in DER form, passed as a Base64 encoded string.
          Result none
     'status_code_to_string' Return the string representation of a OPC UA status code.
          Result string
     'strerror' Convert OPC UA status codes into human readable strings.
          Argument <error code> integer
          Result '<error string>' string
     'thumbprint_certificate' Returns the SHA1 thumbprints of OpenSSL certificates.
          Argument '<X.509 certificate in DER format, Base64 encoded>' string X.509 certificate(s) in DER format, encoded as a Base64 string(s).
          Result '<hex string>' string
     'validate_certificate' Check the validity of OpenSSL certificates against those stored in the file-based OpenSSL certificate store.
          Argument '<Path to certificate store>', '<X.509 certificate in DER format, Base64 encoded>' string The first argument is the path to the certificate store, followed by the certificates in DER form passed as Base64 encoded strings.
          Result 'false', 'true' string If a certificate is valid, 'true' is returned for it, 'false' otherwise. Note that there will be one less return value than arguments.
Argument [] integer, real, string List of arguments for the action.
Result integer, real, string List of results returned by the action.

Operator query_io_interface

query_io_interface(::IOInterfaceName, Query:Result)
Query information about the specified I/O device interface.
Parameter Values Type Description
IOInterfaceName 'OPC_UA' string HALCON I/O interface name.
Query string Parameter name of the query.
     'io_device_info' ['device:<device URL>'] string Returns a list of device names. The names are determined by making an OPC UA FindServers service call to an OPC UA discovery server that must be listening on TCP port 4840 of the localhost interface.
     'io_device_names' <device URL> string Returns a list of device names that can be passed to open_io_device. The names are determined by making an OPC UA FindServers service call to an OPC UA discovery server that must be listening on TCP port 4840 of the localhost interface.
     'param_name' '<parameter>'[,'<parameter>'...] string List of parameters that can be specified for the operator in question.
     'revision' '<version>.<revision>.<build>' string Revision number of the OPC_UA interface.
Result integer, real, string List of result values (according to Query).

Operator open_io_device

open_io_device(::IOInterfaceName, IODeviceName, GenParamName, GenParamValue:IODeviceHandle)
Open and configure an I/O device.
Parameter Values Default Type Description
IOInterfaceName 'OPC_UA' [] string HALCON I/O interface name.
IODeviceName [] string I/O device name.
GenParamName [] string Dynamic parameter names.
     'application_name' '<name>' 'HALCON OPC UA interface' string The client application name used for the session.
     'application_uri' '<URI>' 'HALCON OPC UA interface' string The client application URI used for the session.
     'certificate_store' '<filesystem path>' string Set the path to the file-based OpenSSL certificate store to use. This should be a directory with the subdirectories 'certs' for the trusted certificates (both server and client), 'crl' for the revocation list(s), and 'private' to store the client private keys.
     'client_certificate_name' '<name>' string When using the file-based OpenSSL certificate store, the name of the client certificate to use. There must exist a name.der and name.pem file for the certificate and the private key, respectively.
     'connect_timeout' <milliseconds> 5000 integer Timeout value in milliseconds for establishing the connection to the OPC UA server.
     'encrypt_password_check' 'disable', 'enable' 'enable' string This parameter prevents the client from sending unencrypted passwords without user interaction. This happens if the ServerNonce(1) is null or if the PasswordEncryptionMode is set to NONE on the server. If a server does not support encryption or does not require it due to an oversight in the configuration then this parameter should be set to 'disable'.
(1) OPC UA Part 4 - Services 1.03.
     'event_message_queue' 0 handle The user can specify a message queue in which to receive a message when certain events are triggered on the server. Setting the value to 0 (or HNULL) unregister the message queue and stops the updates. For more information please refer to the section 'OPC UA Event Handling'.
     'message_security_mode' 'none', 'sign', 'sign/encrypt' 'none' string Security mode to use for the session.
     'product_uri' '<URI>' 'HALCON' string The client product URI used for the session.
     'security_policy' 'http://opcfoundation.org/UA/SecurityPolicy#Basic128Rsa15', 'http://opcfoundation.org/UA/SecurityPolicy#Basic256', 'http://opcfoundation.org/UA/SecurityPolicy#None' 'http://opcfoundation.org/UA/SecurityPolicy#None' string Name of the security policy to use for the session.
     'server_certificate' '<X.509 certificate in DER format, Base64 encoded>' '' string If used as a parameter to open_io_device, sets the server certificate to use for the connection. The certificate should be in DER form, encoded as a Base64 string. The certificate must match that of the server being connected to.
If used as a parameter to get_io_device_param, returns the server certificate (in DER form as a Base64 encoded string) that was passed to open_io_device when the connection was established, or an empty string if no certificate was specified.
     'session_locale' '<RFC3066 locale specifier>' 'en-US' string The locale to use for this session, using a language tag as specified in RFC 3066.
     'session_name' '<unique session name>' string The session name. This should be unique for each instance of the client.
     'session_timeout' <milliseconds> 1.2e6 integer, float Timeout value in milliseconds for the session. If the network connection is broken for longer than the session timeout, the session is considered disconnected.
     'trusted_certificate_for_user_token' 'disable', 'enable' 'enable' string This parameter prevents the client from sending unencrypted passwords without user interaction. The user token on a server must be encrypted with a certificate in the client's trusted list. This is required even if the security of the server is NONE. This flag can be used to disable the check.
     'user_name' '<name>' string The (optional) user name for the session. When used with open_io_device or set_io_device_param, 'user_password' must be set in the same operator call.
     'user_password' '<password>' string The (optional) user password for the session. When used with open_io_device or set_io_device_param, 'user_name' must be set in the same operator call.
     'watchdog_time' <milliseconds> 5000 integer The time between watchdog checks in milliseconds.
     'watchdog_timeout' <milliseconds> 5000 integer The timeout for watchdog calls in milliseconds. After one unsuccessful call the timeout will be two times this value for the next call.
GenParamValue [] integer, real, string Dynamic parameter values.
IODeviceHandle handle Handle of the opened I/O device.

Operator control_io_device

control_io_device(::IODeviceHandle, Action, Argument:Result)
Perform an action on the I/O device.
Parameter Values Default Type Description
IODeviceHandle handle Handle of the opened I/O device.
Action string Name of the action to perform.
     'namespace' Convert the specified namespaces into the corresponding namespace indexes.
          Argument '<namespace>' string The namespace as a text string.
          Result '<namespace index>' integer The namespace index, or -1 if the namespace is undefined.
     'translate' Translate an OPC UA browse path into a node id.
          Argument '<NodeId>', '<browse path>' string If no arguments are given, returns the root of the OPC UA node tree. Otherwise, two arguments are required. The first argument is the ID of the node the path starts at, and the second argument is the path to translate. If an empty string ('') is passed for the start node, the root of the OPC UA node tree is used.
The browse path follows the syntax described in "OPC Unified Architecture, Part 4". A browse path consists of one or more subpaths. Each subpath must be written in one of the following forms:

/[ns:]BrowseName - Follow any subtype of the HierarchicalReferences reference type.
.[ns:]BrowseName - Follow any subtype of the Aggregates reference type.
BrowseName - Follow a reference of type ReferenceType, or a subtype thereof. If '#' is specified, the reference type must match exactly, i.e., subtypes are not followed. If '!' is specified, an inverse lookup is done.
In all forms, [ns:] is an optional namespace index consisting of one or more digits followed by a colon (':'). If no namespace index is given, namespace index 0 is assumed by default. BrowseName is the target node's BrowseName attribute, while ReferenceType is the name of the reference type. If the ReferenceType or BrowseName contains any of the reserved characters '/', '.', '', '#', '!', or '&', it must be escaped by a prefixed '&'.
          Result '<NodeId>' string
Argument [] integer, real, string List of arguments for the action.
Result integer, real, string List of result values returned by the action.

Operator set_io_device_param

set_io_device_param(::IODeviceHandle, GenParamName, GenParamValue:)
Configure a specific I/O device instance.
Parameter Values Default Type Description
IODeviceHandle handle Handle of the opened I/O device.
GenParamName [] string Parameter names.
     'event_message_queue' 0 handle The user can specify a message queue in which to receive a message when certain events are triggered on the server. Setting the value to 0 (or HNULL) unregister the message queue and stops the updates. For more information please refer to the section 'OPC UA Event Handling'.
     'user_name' '<name>' string The (optional) user name for the session. When used with open_io_device or set_io_device_param, 'user_password' must be set in the same operator call.
     'user_password' '<password>' string The (optional) user password for the session. When used with open_io_device or set_io_device_param, 'user_name' must be set in the same operator call.
GenParamValue [] integer, real, string Parameter values to set.

Operator get_io_device_param

get_io_device_param(::IODeviceHandle, GenParamName:GenParamValue)
Query settings of an I/O device instance.

There may exist additional parameter attributes, which can be accessed as 'ParamNames.AttributeName'. The following standard attributes may be available:
  • '.access': This attribute provides the access permissions of the corresponding parameter as a string. Possible values are 'ro' (read-only), 'wo' (write-only), 'rw' (read/write), 'na' (unavailable, perhaps due to insufficient access rights), and 'ni' (unavailable, not defined for this device or channel).
  • '.category': This attribute provides the category of the corresponding parameter as a string. 'I/O interface' for all pre-defined I/O interface parameters.
  • '.default': This attribute provides the default value of the corresponding parameter.
  • '.description': This attribute provides the description of the corresponding parameter as a string.
  • '.displayname': This attribute provides the displayname of the corresponding parameter as a string.
  • '.range': This attribute provides the minimum and maximum, (and the step width, if applicable) for the corresponding integer or float parameter as a tuple with 2 (or 3) elements.
  • '.representation': This attribute provides how the value of the parameter should be displayed in a GUI: 'ip address', 'hex', ...
  • '.tooltip': This attribute provides the tool-tip of the corresponding parameter as a string.
  • '.type': This attribute provides the HALCON value type (integer, real, or string) of the corresponding parameter as a string.
  • '.values': This attribute provides the valid value list for the corresponding parameter as a tuple.
  • '.visibility': This attribute provides the visibility of the corresponding parameter as a string. Possible values are 'common', 'extended', and 'dangerous'.
  • '.unit': This attribute provides the units of the corresponding parameter as a string. For example: 'ns', 'us' and 'ms', or 'mm', 'cm', 'dm' and 'm'.
Parameter Values Type Description
IODeviceHandle handle Handle of the opened I/O device.
GenParamName string Parameter names.
     'application_name' '<name>' string The client application name used for the session.
     'application_uri' '<URI>' string The client application URI used for the session.
     'connect_timeout' <milliseconds> integer Timeout value in milliseconds for establishing the connection to the OPC UA server.
     'connection_status' 'Disconnected', 'Connected', 'NewSessionCreated', 'ConnectionWarningWatchdogTimeout', 'ConnectionErrorApiReconnect', 'ServerShutdown', 'unknown' string Returns the current status of the server connection as a string.
     'encrypt_password_check' 'disable', 'enable' string This parameter prevents the client from sending unencrypted passwords without user interaction. This happens if the ServerNonce(1) is null or if the PasswordEncryptionMode is set to NONE on the server. If a server does not support encryption or does not require it due to an oversight in the configuration then this parameter should be set to 'disable'.
(1) OPC UA Part 4 - Services 1.03.
     'endpoints' 'endpoint_url:<server url>[|server_certificate:<certificate>]|message_security_mode:<mode>|security_policy_uri:<policy>|transport_profile_uri:<profile>|security_level:<level>' string If used as a parameter to get_io_device_param, returns all endpoints of the server the device is connected to. It cannot be combined with any other queries.
If used as an action for control_io_interface, returns all endpoints of the server reachable via the URL given as the only argument.
     'event_message_queue' handle The user can specify a message queue in which to receive a message when certain events are triggered on the server. Setting the value to 0 (or HNULL) unregister the message queue and stops the updates. For more information please refer to the section 'OPC UA Event Handling'.
     'io_device_name' <device URL> string Return the URL of the server the device is connected to.
     'message_security_mode' 'none', 'sign', 'sign/encrypt' string Security mode to use for the session.
     'namespaces' '<namespace>'[,'<namespace>',...] string Returns all OPC UA namespaces as a tuple of strings for the specified connection. The namespaces are returned in the same order as they are defined on the server, i.e., the fourth element of the return tuple corresponds to the fourth namespace on the server.
     'param_name' '<parameter>'[,'<parameter>'...] string List of parameters that can be specified for the operator in question.
     'product_uri' '<URI>' string The client product URI used for the session.
     'security_policy' 'http://opcfoundation.org/UA/SecurityPolicy#Basic128Rsa15', 'http://opcfoundation.org/UA/SecurityPolicy#Basic256', 'http://opcfoundation.org/UA/SecurityPolicy#None' string Name of the security policy to use for the session.
     'server_certificate' '<X.509 certificate in DER format, Base64 encoded>' string If used as a parameter to open_io_device, sets the server certificate to use for the connection. The certificate should be in DER form, encoded as a Base64 string. The certificate must match that of the server being connected to.
If used as a parameter to get_io_device_param, returns the server certificate (in DER form as a Base64 encoded string) that was passed to open_io_device when the connection was established, or an empty string if no certificate was specified.
     'session_locale' '<RFC3066 locale specifier>' string The locale to use for this session, using a language tag as specified in RFC 3066.
     'session_name' '<unique session name>' string The session name. This should be unique for each instance of the client.
     'session_timeout' <milliseconds> integer, float Timeout value in milliseconds for the session. If the network connection is broken for longer than the session timeout, the session is considered disconnected.
     'trusted_certificate_for_user_token' 'disable', 'enable' string This parameter prevents the client from sending unencrypted passwords without user interaction. The user token on a server must be encrypted with a certificate in the client's trusted list. This is required even if the security of the server is NONE. This flag can be used to disable the check.
     'user_name' '<name>' string The (optional) user name for the session. When used with open_io_device or set_io_device_param, 'user_password' must be set in the same operator call.
     'user_password' '<password>' string The (optional) user password for the session. When used with open_io_device or set_io_device_param, 'user_name' must be set in the same operator call.
     'user_token_type' 'Anonymous', 'Certificate', 'IssuedToken', 'UserName' string Returns the type of user token currently used by the connection to the device.
     'watchdog_time' <milliseconds> integer The time between watchdog checks in milliseconds.
     'watchdog_timeout' <milliseconds> integer The timeout for watchdog calls in milliseconds. After one unsuccessful call the timeout will be two times this value for the next call.
GenParamValue integer, real, string Parameter values.

Operator query_io_device

query_io_device(::IODeviceHandle, IOChannelName, Query:Result)
Query information about channels of the specified I/O device.
Parameter Values Type Description
IODeviceHandle handle Handle of the opened I/O device.
IOChannelName string Channel names to query.
Query string Name of the query.
     'access_level' [0..255] integer AccessLevel attribute of the OPC UA node(s). This attribute is mandatory for all Variable node classes.
     'array_dimensions' <number> integer ArrayDimensions attribute of the OPC UA node(s). This attribute is optional for variable and variable type nodes.
     'attributes' 'access_level', 'array_dimensions', 'contains_no_loops', 'data_type', 'description', 'display_name', 'event_notifier', 'historizing', 'inverse_name', 'is_abstract', 'minimum_sampling_interval', 'node_class', 'node_id', 'symmetric', 'user_access_level', 'user_executable', 'user_write_mask', 'value_rank', 'write_mask' string Returns a list of OPC UA attributes defined for the specified node. Only a single node may be specified, and no other queries may be requested in this call to query_io_device.
     'browse' <NodeId>,<NodeClass>,<BrowseName>[,<NodeId>,<NodeClass>,<BrowseName>,...] string Returns a list of subnodes of the specified node. Only a single node may be specified. If an empty node ([]) is specified, browsing starts at the root of the OPC UA node tree. For each node, three HALCON string elements are returned - the node id, the node class, and the browse name. No other queries may be requested in this call to query_io_device. If the node id refers to a node on a different server, it is returned as an ExpandedNodeId, otherwise it is returned as a normal node id that can be used as a channel name for subsequent channel operations.
     'browse_name' '<ns>:<name>' string BrowseName attribute of the OPC UA node(s). The browse name is returned in the form '<ns&gt:<name>', with <ns> being the index of the namespace the browse name is located in. This attribute is mandatory for all node classes.
     'contains_no_loops' 'false', 'true' string ContainsNoLoops attribute of the OPC UA node(s). This attribute is mandatory for view nodes.
     'data_type_definition' handle Information about the datatype of a variable node or about a datatype node. This always includes the datatype name, the metatype and, if available, additional metadata. For structures, optionsets and unions, information about the fields is included (see parameter 'fields'). The available information is returned in a HALCON dictionary.
     'data_type' 'Boolean', 'Byte', 'ByteString', 'DataValue', 'DateTime', 'DiagnosticInfo', 'Double', 'Duration', 'ExpandedNodeId', 'ExtensionObject', 'Float', 'Guid', 'Image', 'ImageBMP', 'ImageGIF', 'ImageJPG', 'ImagePNG', 'Int16', 'Int32', 'Int64', 'Integer', 'LocalizedText', 'LocaleId', 'NodeId', 'Null', 'QualifiedName', 'SByte', 'StatusCode', 'String', 'UInt16', 'UInt32', 'UInt64', 'UInteger', 'Unknown', 'UtcTime', 'Variant', 'XmlElement' string The node's datatype attribute. This attribute is mandatory for data type, variable and variable type nodes.
     'description' '<description>' string Description attribute of the OPC UA node(s). This attribute is optional for all node classes.
     'display_name' '<name>' string DisplayName attribute of the OPC UA node(s). This attribute is mandatory for all node classes.
     'enum_values' handle If the passed node is an enumeration, return the possible numerical values together with the name and description. If the passed node is not an enum an exception will be thrown. The available information is returned in a HALCON dictionary.
     'event_notifier' <number> integer EventNotifier attribute of the OPC UA node(s). This attribute is mandatory for object and view nodes.
     'executable' 'false', 'true' string Executable attribute of the OPC UA node(s). This attribute is mandatory for method nodes.
     'fields' string If the passed node is a Structure, Union or OptionSet return the fields of the datatype definition, otherwise an exception will be thrown. The available information is returned in a HALCON dictionary with a numeric key for each field. The information for each field always includes the datatype name, the metatype and, if available, additional metadata. The OPC UA attributes value_rank and, if available, array_dimensions provide information about the array characteristics of the field.
     'historizing' 'false', 'true' string Historizing attribute of the OPC UA node(s). This attribute is mandatory for variable nodes.
     'inverse_name' '<name>' string InverseName attribute of the OPC UA node(s). This attribute is optional for reference type nodes.
     'io_channel_name' '<name>' string Returns the name this channel was opened with. For OPC UA, this is the node id in XML string representation.
     'is_abstract' 'false', 'true' string IsAbstract attribute of the OPC UA node(s). This attribute is mandatory for object type, reference type and variable type nodes.
     'meta_type' 'Enumeration', 'Structure', 'Union', 'Option Set', ''<BuildIn>'' string Returns if the node can be interpreted as an Enumeration, Structure, Union, OptionSet or other data type.
     'method_arguments' handle Information about the input and output arguments of a method. The available information is returned in a HALCON dictionary with keys 'input_arguments' and 'output_arguments'. If the method has no input or output arguments, an empty tuple is stored under the respective key. Each argument has a name and a description. Additionally, information about the expected type is returned.
     'minimum_sampling_interval' <number> integer, float MinimumSamplingInterval attribute of the OPC UA node(s). This attribute is optional for variable nodes.
     'node_class' 'DataType', 'Method', 'Object', 'ObjectType', 'ReferenceType', 'Unknown', 'Variable', 'VariableType', 'View' string NodeClass attribute of the OPC UA node(s). This attribute is mandatory for all nodes.
     'node_id' '<NodeId>' string NodeId attribute of the OPC UA node(s). The node id is used to uniquely identify every node on a server. Use it as the channel name for query_io_device and open_io_channel.
     'option_set_values' handle If the passed node is a struct of the OptionSet data type, return the description of each bit on the bitmask on the OptionSetValues property. If the passed node is not an OptionSet, an exception will be thrown. The available information is presented in a HALCON dictionary.
     'param_name' '<parameter>'[,'<parameter>'...] string List of parameters that can be specified for the operator in question.
     'symmetric' 'false', 'true' string Symmetric attribute of the OPC UA node(s). This attribute is mandatory for reference type nodes.
     'user_access_level' [0..255] integer UserAccessLevel attribute of the OPC UA node(s). This attribute is mandatory for variable nodes.
     'user_executable' 'false', 'true' string UserExecutable attribute of the OPC UA node(s). This attribute is mandatory for method nodes.
     'user_write_mask' <bitmask> integer UserWriteMask attribute of the OPC UA node(s). This attribute is optional for all node classes.
     'value.access' 'ro', 'wo', 'rw', 'na', 'ni' string Return the access of the value of a Variable node.
     'value_rank' <number> integer ValueRank attribute of the OPC UA node(s). This attribute is mandatory for variable and variable type nodes.
     'write_mask' <bitmask> integer WriteMask attribute of the OPC UA node(s). This attribute is optional for all node classes.
Result integer, real, string List of values (according to Query).

Operator open_io_channel

open_io_channel(::IODeviceHandle, IOChannelName, GenParamName, GenParamValue:IOChannelHandle)
Open and configure I/O channels.
Parameter Values Default Type Description
IODeviceHandle handle Handle of the opened I/O device.
IOChannelName string HALCON I/O channel names of the specified device.
GenParamName [] string Parameter names.
     'cached' 'false', 'true' 'false' string If 'true', the channel's value is not read directly from the server in response to a read_io_channel call; instead the last known value received (either published by the server, or read in response to a previous read_io_channel call) is returned. If no value has been cached for the channel, a read request is sent to the server regardless of the setting of the 'cached' parameter.
The 'cached' parameter is automatically set to 'true' for subscribed channels, and to 'false' for unsubscribed channels. Note that manually setting 'cached' to 'true' for an unsubscribed channel is possible; read_io_channel will then return the cached value instead of reading the current value from the server for this channel as if it where subscribed.
     'discard_oldest' 'false', 'true' 'false' string Discard oldest subscription property. If this parameter is set, at least one of the parameters 'publishing_interval' or 'sampling_interval' must also be set.
     'event_message_queue' 0 handle The user can specify a message queue in which to receive a message when certain events are triggered on the server. Setting the value to 0 (or HNULL) unregister the message queue and stops the updates. For more information please refer to the section 'OPC UA Event Handling'.
     'method_target_node' '<NodeId>' string NodeId of the target object used when calling a method. Methods typically belong to a object, which provides the context for the method invocation. Methods are also allowed to belong to multiple objects. This parameter is used to specify the target object, on which the method should be invoked. To call a method, this parameter must be set, even when the target object is unique.
     'priority' [0..255] 0 integer Priority subscription property. If this parameter is set, at least one of the parameters 'publishing_interval' or 'sampling_interval' must also be set.
     'publishing_interval' <milliseconds> 0 integer, float Interval in which the server should publish the channel's value in milliseconds. If this parameter is set to a value greater than zero, the channel is subscribed from the server; if it is set to 0 the channel is unsubscribed.
If the parameter 'sampling_interval' is set but 'publishing_interval' is not, 'publishing_interval' is set to twice the value of 'sampling_interval' by default.
     'queue_size' <number> 0 integer Queue size subscription property. If this parameter is set, at least one of the parameters 'publishing_interval' or 'sampling_interval' must also be set.
     'sampling_interval' <milliseconds> 0 integer, float Interval in which the server should sample the channel in milliseconds. This value should be less or equal than the value of parameter 'publishing_interval'.
If the parameter 'publishing_interval' is set but 'sampling_interval' is not, 'sampling_interval' is set to half the value of 'publishing_interval' by default.
GenParamValue [] integer, real, string Parameter values.
IOChannelHandle handle Handles of the opened I/O channel.

Operator control_io_channel

control_io_channel(::IOChannelHandle, ParamAction, ParamArgument:GenParamValue)
Perform an action on I/O channels.
Parameter Values Default Type Description
IOChannelHandle handle Handles of the opened I/O channels.
ParamAction string Name of the action to perform.
     'method_call' Call a server method. To find out if a method is executable before calling it, query for the attributes 'executable' and 'user_executable'. To call a method successfully, the provided input tuple must contain values which match the datatypes of the input arguments. The rules in section 'Converting data between HALCON and OPC UA' apply. To know which datatypes the method expects, use the io channel parameter 'arguments'. The output tuple will contain the result of the method. If the server returns a bad status code, an exception will be raised.
ParamArgument [] integer, real, string List of arguments for the action.
GenParamValue integer, real, string List of values returned by the action.

Operator set_io_channel_param

set_io_channel_param(::IOChannelHandle, GenParamName, GenParamValue:)
Set specific parameters of I/O channels.
Parameter Values Default Type Description
IOChannelHandle handle Handles of the opened I/O channels.
GenParamName [] string Parameter names.
     'cached' 'false', 'true' 'false' string If 'true', the channel's value is not read directly from the server in response to a read_io_channel call; instead the last known value received (either published by the server, or read in response to a previous read_io_channel call) is returned. If no value has been cached for the channel, a read request is sent to the server regardless of the setting of the 'cached' parameter.
The 'cached' parameter is automatically set to 'true' for subscribed channels, and to 'false' for unsubscribed channels. Note that manually setting 'cached' to 'true' for an unsubscribed channel is possible; read_io_channel will then return the cached value instead of reading the current value from the server for this channel as if it where subscribed.
     'discard_oldest' 'false', 'true' 'false' string Discard oldest subscription property. If this parameter is set, at least one of the parameters 'publishing_interval' or 'sampling_interval' must also be set.
     'event_message_queue' 0 handle The user can specify a message queue in which to receive a message when certain events are triggered on the server. Setting the value to 0 (or HNULL) unregister the message queue and stops the updates. For more information please refer to the section 'OPC UA Event Handling'.
     'method_target_node' '<NodeId>' string NodeId of the target object used when calling a method. Methods typically belong to a object, which provides the context for the method invocation. Methods are also allowed to belong to multiple objects. This parameter is used to specify the target object, on which the method should be invoked. To call a method, this parameter must be set, even when the target object is unique.
     'priority' [0..255] 0 integer Priority subscription property. If this parameter is set, at least one of the parameters 'publishing_interval' or 'sampling_interval' must also be set.
     'publishing_interval' <milliseconds> 0 integer, float Interval in which the server should publish the channel's value in milliseconds. If this parameter is set to a value greater than zero, the channel is subscribed from the server; if it is set to 0 the channel is unsubscribed.
If the parameter 'sampling_interval' is set but 'publishing_interval' is not, 'publishing_interval' is set to twice the value of 'sampling_interval' by default.
     'queue_size' <number> 0 integer Queue size subscription property. If this parameter is set, at least one of the parameters 'publishing_interval' or 'sampling_interval' must also be set.
     'sampling_interval' <milliseconds> 0 integer, float Interval in which the server should sample the channel in milliseconds. This value should be less or equal than the value of parameter 'publishing_interval'.
If the parameter 'publishing_interval' is set but 'sampling_interval' is not, 'sampling_interval' is set to half the value of 'publishing_interval' by default.
GenParamValue [] integer, real, string, handle Parameter values to set.

Operator get_io_channel_param

get_io_channel_param(::IOChannelHandle, GenParamName:GenParamValue)
Query specific parameters of I/O channels.

There may exist additional parameter attributes, which can be accessed as 'ParamNames.AttributeName'. The following standard attributes may be available:
  • '.access': This attribute provides the access permissions of the corresponding parameter as a string. Possible values are 'ro' (read-only), 'wo' (write-only), 'rw' (read/write), 'na' (unavailable, perhaps due to insufficient access rights), and 'ni' (unavailable, not defined for this device or channel).
  • '.category': This attribute provides the category of the corresponding parameter as a string. 'I/O interface' for all pre-defined I/O interface parameters.
  • '.default': This attribute provides the default value of the corresponding parameter.
  • '.description': This attribute provides the description of the corresponding parameter as a string.
  • '.displayname': This attribute provides the displayname of the corresponding parameter as a string.
  • '.range': This attribute provides the minimum and maximum, (and the step width, if applicable) for the corresponding integer or float parameter as a tuple with 2 (or 3) elements.
  • '.representation': This attribute provides how the value of the parameter should be displayed in a GUI: 'ip address', 'hex', ...
  • '.tooltip': This attribute provides the tool-tip of the corresponding parameter as a string.
  • '.type': This attribute provides the HALCON value type (integer, real, or string) of the corresponding parameter as a string.
  • '.values': This attribute provides the valid value list for the corresponding parameter as a tuple.
  • '.visibility': This attribute provides the visibility of the corresponding parameter as a string. Possible values are 'common', 'extended', and 'dangerous'.
  • '.unit': This attribute provides the units of the corresponding parameter as a string. For example: 'ns', 'us' and 'ms', or 'mm', 'cm', 'dm' and 'm'.
Parameter Values Type Description
IOChannelHandle handle Handles of the opened I/O channels.
GenParamName string Parameter names.
     'access_level' [0..255] integer AccessLevel attribute of the OPC UA node(s). This attribute is mandatory for all Variable node classes.
     'array_dimensions' <number> integer ArrayDimensions attribute of the OPC UA node(s). This attribute is optional for variable and variable type nodes.
     'attributes' 'access_level', 'array_dimensions', 'contains_no_loops', 'data_type', 'description', 'display_name', 'event_notifier', 'historizing', 'inverse_name', 'is_abstract', 'minimum_sampling_interval', 'node_class', 'node_id', 'symmetric', 'user_access_level', 'user_executable', 'user_write_mask', 'value_rank', 'write_mask' string Returns a list of OPC UA attributes defined for the specified node. Only a single node may be specified, and no other queries may be requested in this call to query_io_device.
     'browse_name' '<ns>:<name>' string BrowseName attribute of the OPC UA node(s). The browse name is returned in the form '<ns&gt:<name>', with <ns> being the index of the namespace the browse name is located in. This attribute is mandatory for all node classes.
     'cached' 'false', 'true' string If 'true', the channel's value is not read directly from the server in response to a read_io_channel call; instead the last known value received (either published by the server, or read in response to a previous read_io_channel call) is returned. If no value has been cached for the channel, a read request is sent to the server regardless of the setting of the 'cached' parameter.
The 'cached' parameter is automatically set to 'true' for subscribed channels, and to 'false' for unsubscribed channels. Note that manually setting 'cached' to 'true' for an unsubscribed channel is possible; read_io_channel will then return the cached value instead of reading the current value from the server for this channel as if it where subscribed.
     'contains_no_loops' 'false', 'true' string ContainsNoLoops attribute of the OPC UA node(s). This attribute is mandatory for view nodes.
     'data_type' 'Boolean', 'Byte', 'ByteString', 'DataValue', 'DateTime', 'DiagnosticInfo', 'Double', 'Duration', 'ExpandedNodeId', 'ExtensionObject', 'Float', 'Guid', 'Image', 'ImageBMP', 'ImageGIF', 'ImageJPG', 'ImagePNG', 'Int16', 'Int32', 'Int64', 'Integer', 'LocalizedText', 'LocaleId', 'NodeId', 'Null', 'QualifiedName', 'SByte', 'StatusCode', 'String', 'UInt16', 'UInt32', 'UInt64', 'UInteger', 'Unknown', 'UtcTime', 'Variant', 'XmlElement' string The node's datatype attribute. This attribute is mandatory for data type, variable and variable type nodes.
     'data_type_definition' handle Information about the datatype of a variable node or about a datatype node. This always includes the datatype name, the metatype and, if available, additional metadata. For structures, optionsets and unions, information about the fields is included (see parameter 'fields'). The available information is returned in a HALCON dictionary.
     'description' '<description>' string Description attribute of the OPC UA node(s). This attribute is optional for all node classes.
     'discard_oldest' 'false', 'true' string Discard oldest subscription property. If this parameter is set, at least one of the parameters 'publishing_interval' or 'sampling_interval' must also be set.
     'display_name' '<name>' string DisplayName attribute of the OPC UA node(s). This attribute is mandatory for all node classes.
     'enum_values' handle If the passed node is an enumeration, return the possible numerical values together with the name and description. If the passed node is not an enum an exception will be thrown. The available information is returned in a HALCON dictionary.
     'event_message_queue' handle The user can specify a message queue in which to receive a message when certain events are triggered on the server. Setting the value to 0 (or HNULL) unregister the message queue and stops the updates. For more information please refer to the section 'OPC UA Event Handling'.
     'event_notifier' <number> integer EventNotifier attribute of the OPC UA node(s). This attribute is mandatory for object and view nodes.
     'executable' 'false', 'true' string Executable attribute of the OPC UA node(s). This attribute is mandatory for method nodes.
     'fields' string If the passed node is a Structure, Union or OptionSet return the fields of the datatype definition, otherwise an exception will be thrown. The available information is returned in a HALCON dictionary with a numeric key for each field. The information for each field always includes the datatype name, the metatype and, if available, additional metadata. The OPC UA attributes value_rank and, if available, array_dimensions provide information about the array characteristics of the field.
     'historizing' 'false', 'true' string Historizing attribute of the OPC UA node(s). This attribute is mandatory for variable nodes.
     'inverse_name' '<name>' string InverseName attribute of the OPC UA node(s). This attribute is optional for reference type nodes.
     'io_channel_name' '<name>' string Returns the name this channel was opened with. For OPC UA, this is the node id in XML string representation.
     'is_abstract' 'false', 'true' string IsAbstract attribute of the OPC UA node(s). This attribute is mandatory for object type, reference type and variable type nodes.
     'meta_type' 'Enumeration', 'Structure', 'Union', 'Option Set', ''<BuildIn>'' string Returns if the node can be interpreted as an Enumeration, Structure, Union, OptionSet or other data type.
     'method_arguments' handle Information about the input and output arguments of a method. The available information is returned in a HALCON dictionary with keys 'input_arguments' and 'output_arguments'. If the method has no input or output arguments, an empty tuple is stored under the respective key. Each argument has a name and a description. Additionally, information about the expected type is returned.
     'method_target_node' '<NodeId>' string NodeId of the target object used when calling a method. Methods typically belong to a object, which provides the context for the method invocation. Methods are also allowed to belong to multiple objects. This parameter is used to specify the target object, on which the method should be invoked. To call a method, this parameter must be set, even when the target object is unique.
     'minimum_sampling_interval' <number> integer, float MinimumSamplingInterval attribute of the OPC UA node(s). This attribute is optional for variable nodes.
     'node_class' 'DataType', 'Method', 'Object', 'ObjectType', 'ReferenceType', 'Unknown', 'Variable', 'VariableType', 'View' string NodeClass attribute of the OPC UA node(s). This attribute is mandatory for all nodes.
     'node_id' '<NodeId>' string NodeId attribute of the OPC UA node(s). The node id is used to uniquely identify every node on a server. Use it as the channel name for query_io_device and open_io_channel.
     'option_set_values' handle If the passed node is a struct of the OptionSet data type, return the description of each bit on the bitmask on the OptionSetValues property. If the passed node is not an OptionSet, an exception will be thrown. The available information is presented in a HALCON dictionary.
     'param_name' '<parameter>'[,'<parameter>'...] string List of parameters that can be specified for the operator in question.
     'priority' [0..255] integer Priority subscription property. If this parameter is set, at least one of the parameters 'publishing_interval' or 'sampling_interval' must also be set.
     'publishing_interval' <milliseconds> integer, float Interval in which the server should publish the channel's value in milliseconds. If this parameter is set to a value greater than zero, the channel is subscribed from the server; if it is set to 0 the channel is unsubscribed.
If the parameter 'sampling_interval' is set but 'publishing_interval' is not, 'publishing_interval' is set to twice the value of 'sampling_interval' by default.
     'queue_size' <number> integer Queue size subscription property. If this parameter is set, at least one of the parameters 'publishing_interval' or 'sampling_interval' must also be set.
     'sampling_interval' <milliseconds> integer, float Interval in which the server should sample the channel in milliseconds. This value should be less or equal than the value of parameter 'publishing_interval'.
If the parameter 'publishing_interval' is set but 'sampling_interval' is not, 'sampling_interval' is set to half the value of 'publishing_interval' by default.
     'symmetric' 'false', 'true' string Symmetric attribute of the OPC UA node(s). This attribute is mandatory for reference type nodes.
     'user_access_level' [0..255] integer UserAccessLevel attribute of the OPC UA node(s). This attribute is mandatory for variable nodes.
     'user_executable' 'false', 'true' string UserExecutable attribute of the OPC UA node(s). This attribute is mandatory for method nodes.
     'user_write_mask' <bitmask> integer UserWriteMask attribute of the OPC UA node(s). This attribute is optional for all node classes.
     'value_rank' <number> integer ValueRank attribute of the OPC UA node(s). This attribute is mandatory for variable and variable type nodes.
     'write_mask' <bitmask> integer WriteMask attribute of the OPC UA node(s). This attribute is optional for all node classes.
GenParamValue integer, real, string, handle Parameter values.

Operator read_io_channel

read_io_channel(::IOChannelHandle:Value, Status)
Read a value from the specified I/O channels. If multiple channels are specified, they must all belong to the same device.
Parameter Values Type Description
IOChannelHandle handle Handles of the opened I/O channels.
Value integer, real, string Read value.
Status integer Status of read value. A status of '0' indicates success, while any other value indicates an error condition as returned by the OPC UA communication stack.

Operator write_io_channel

write_io_channel(::IOChannelHandle, Value:Status)
Write a value to the specified I/O channels. If multiple channels are specified, they must all belong to the same device.
Parameter Values Type Description
IOChannelHandle handle Handles of the opened I/O channels.
Value integer, real, string Write values.
Status integer Status of written values. A status of '0' indicates success, while any other value indicates an error condition as returned by the OPC UA communication stack.

Operator close_io_channel

close_io_channel(::IOChannelHandle:)
Close I/O channels.
Parameter Type Description
IOChannelHandle handle Handles of the opened I/O channels.

Operator close_io_device

close_io_device(::IODeviceHandle:)
Close the specified I/O device.
Parameter Type Description
IODeviceHandle handle Handle of the opened I/O device.

Usage of 3rd party libraries

This interface depends on the following 3rd party libraries. See the file third_party_opc_ua.txt in the HALCON base directory for copyright and license information.

OpenSSL

This software uses OpenSSL 1.1 for secure communication with OPC UA servers. It was configured and built with the options no-idea, no-mdc2, no-ntt, and no-rc5 to avoid patent issues.

On Linux, you can use the system-provided OpenSSL libraries if they are binary compatible with OpenSSL 1.1 by removing libcrypto.so.1.1 and libssl.so.1.1 from the directory $HALCONROOT/lib/$HALCONARCH/thirdparty.

If bugs are found in the version of OpenSSL provided by MVTec and you do not want to wait for an update of the interface, you can compile and use your own version.

HDevelop Examples

For this interface the following examples are available:
  • opc_ua_browse_variables.hdev - Shows how to browse the available nodes on an OPC UA server. information about the expected datatypes.
  • opc_ua_channel_access.hdev - Shows how to read and write OPC UA variable nodes.
  • opc_ua_discovery.hdev - Shows how to query an OPC UA discovery server to find OPC UA servers to connect to.
  • opc_ua_enumeration.hdev - Shows how to read and write Enumeration variable nodes on an OPC UA server.
  • opc_ua_methods.hdev - Shows how to call a method on the OPC UA server and how to query
  • opc_ua_monitor_subscription.hdev - Shows how to monitor values by creating a subscription to a variable node.
  • opc_ua_monitor_connection.hdev - Shows how to asynchronously monitor the status of the server connection.
  • opc_ua_option_set.hdev - Shows how to read and write OptionSet variable nodes on an OPC UA server.
  • opc_ua_parameters.hdev - Shows how to determine which parameters are supported.
  • opc_ua_security.hdev - Shows how to connect to an OPC UA server using OPC UA's security features.
  • opc_ua_structure.hdev - Shows how to read and write Structure variable nodes on an OPC UA server.
  • opc_ua_union.hdev - Shows how to read and write Union variable nodes on an OPC UA server.

Release Notes

  • Revision 19.11.4 (Oct 20, 2021):
    • Closing multiple channel handles using a single call to close_io_channel crashed or locked the application. This problem has been fixed.
    • On Linux the OpenSSL library was linked statically into the interface. This problem has been fixed.
    • The distribution package of this interface now contains files providing meta information for the HDevelop example browser.
    • When a server pushed a monitored item update for a variable that the client has already unregistered the interface crashed. This problem has been fixed.
  • Revision 19.11.3 (Oct 27, 2020):
    • This interface couldn't be loaded from .NET Core applications on Linux and macOS. This problem has been fixed.
  • Revision 19.11.2 (Aug 27, 2020):
    • Support for OPC UA server methods has been added.
    • The new HDevelop examples opc_ua_methods.hdev has been added to show how to call method nodes and how to query the arguments.
    • OpenSSL has been updated to version 1.1.1g.
    • The Unified Automation OPC UA SDK has been updated to version 1.7.2.
    • Support for "OPC UA Amendment 11 - Spatial Types" data types RationalNumber, 3DVector, 3DCartesianCoordinates, 3DOrientation and 3DFrame has been added.
  • Revision 19.11.1 (Oct 9, 2019):
    • This version of the OPC UA interface will only work in its complete form for HALCON versions starting from 19.11 and higher.
    • The new parameter 'status_code_to_string' has been added. It returns the string representation of an OPC UA status code.
    • The new parameter 'data_type_definition' has been added. It returns the data type definition of the value of a variable node (channel).
    • The parameters 'fields', 'enum_values' and 'option_set_values' now return the information inside a HALCON dictionary. In older versions of this interface, the information was returned inside a tuple.
    • The parameters 'fields', 'enum_values' and 'option_set_values' now throw an exception, if used on a channel which is not of the correct meta type. In older versions of this interface, an empty tuple was returned.
    • It is now possible to query information about DataType nodes directly using query_io_device and the node ID. The parameters 'data_type_definition', 'fields', 'enum_values' and 'option_set_values' are now available for this purpose.
    • OpenSSL has been updated to version 1.1.1c.
    • The Unified Automation OPC UA SDK has been updated to version 1.7.0.
    • The new HDevelop example opc_ua_monitor_connection.hdev has been added to show how to monitor connection status changes of an OPC UA Server by using message queues.
    • The new HDevelop example opc_ua_structure.hdev has been added to show how to read and write Structure variable nodes.
    • The new HDevelop example opc_ua_enumeration.hdev has been added to show how to read and write Enumeration variable nodes.
    • The new HDevelop example opc_ua_union.hdev has been added to show how to read and write Union variable nodes.
    • The new HDevelop example opc_ua_option_set.hdev has been added to show how to read and write OptionSet variable nodes.
    • The file third_party_opc_ua.txt has been added to the distribution package of this interface.
    • The section Usage of 3rd party libraries has been added to this document.
    • The section Copyright Information has been updated.
    • The HDevelop examples opc_ua_read_struct.hdev and opc_ua_read_write_complex_data_types.hdev have been removed in favor of simpler examples for each complex type.
    • The HDevelop example opc_ua_browse_variables.hdev has been updated to provide additional information of each node when browsing and to have a simpler interface.
    • The HDevelop examples opc_ua_monitor_subscription.hdev, opc_ua_channel_access.hdev have been updated to handle complex data types.
    • The limitation of doing multi-channel read and write operations with arrays of ByteStrings, Structures, OptionSets and Unions values has been removed. The values are now read or written as HALCON dictionaries with a single key 'h_values' that contain the node values.
    • Complex types Structures, OptionSets and Unions now use HALCON dictionaries for read and write.
    • The limitation of not being able to read or write complex types that contain other complex types or arrays as one of their fields has been removed. In those cases that value will be returned as a HALCON dictionary.
    • The read support for "OPC UA Part 8: Data Access" data types Range, EUInformation, XVType, ComplexNumberType, DoubleComplexNumberType and AxisInformation has been added.
  • Revision 13.0.7 (Jun 11, 2019):
    • The param_names parameter on query_io_device and get_io_channel_param did not return a correct result. This problem has been fixed.
    • Opening a channel failed if the value of the node was Null. This problem has been fixed.
    • When creating a self signed certificate using 'create_certificate' on Windows, HALCON crashed. This problem has been fixed.
  • Revision 13.0.6 (Nov 30, 2018):
    • The string transcoding between HALCON and OPC UA was not taken into account for all cases. Now UTF-8 encoding is ensured for all OPC UA strings.
    • It was not possible to write a node with a derived data type outside of the built-in type. This limitation has been removed.
    • query_io_device crashed when querying the attributes of a node without specifying it. This problem has been fixed.
    • Add support for 'DataChange' event on OPC UA variable nodes with HALCON message queues.
    • Add example to show how to subscribe to variable value changes using HALCON message queues.
    • Update OpenSSL to version 1.0.2p
    • Update to version 1.6.2 of the Unified Automation OPC UA SDK.
    • Allow the user to disable the security checks that prevents the client for sending unencrypted passwords without user interaction. This can be caused by server misconfiguration or lack of encryption support. The added parameters are encrypt_password_check and trusted_certificate_for_user_token.
  • Revision 13.0.5 (Nov 28, 2017):
    • The technical dependency from the HALCON Library has been removed.
    • When browsing a node with a lot of references if it required a continuation point a crash occurred. This problem has been fixed.
    • If the certificate data was set to null on an OPC UA server HALCON crashed. This problem has been fixed.
  • Revision 13.0.4 (Sep 29, 2017):
    • Moved libcrypto.so.1.0.0, libssl.so.1.0.0, and libuastack.so to a subdirectory on Linux systems.
    • Add support for flat Structures, OptionSets, Unions and Enumerations.
    • Add examples for the new data types.
    • Fix connectivity problem with Prosys servers.
    • Update OpenSSL to version 1.0.2l
    • Update to version 1.5.5 of the Unified Automation OPC UA SDK.
  • Revision 13.0.3 (Apr 28, 2017):
    • Accept expanded node IDs for nodes located on the same server.
  • Revision 13.0.2 (Mar 6, 2017):
    • Fix bug setting 'float' variables to values <= 0.
    • Update OpenSSL to version 1.0.2j
    • Update to version 1.5.4 of the Unified Automation OPC UA SDK
  • Revision 13.0.1 (Oct 28, 2016):
    • HALCON 13 version of the interface.