MVTec Software GmbH
 
OPC_UA / HALCON 12.0 / MVTec Software GmbH

OPC_UA I/O Interface for OPC UA compliant devices

Interface: OPC_UA
Revision: 1.7
Date: 2017-09-29
HALCON Version: 12.0
This product includes cryptographic software written by Eric Young (eay@cryptsoft.com).

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).

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 Vista/7/8, Windows Vista/7/8 x64, 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 libeay32.dll, ssleay32.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 libcrypto.1.0.0.so, libssl.1.0.0.so, and libuastack.so. If you have properly installed the interface, the shared objects should reside in lib/$HALCONARCH within the HALCON base directory $HALCONROOT you have chosen during the installation of HALCON.
    OS X: HALCON I/O device interface hioOPC_UA.dylib or hioOPC_UAxl.dylib, respectively. Also required are libcrypto.1.0.0.dylib, libssl.1.0.0.dylib, 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.

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 /Users/Shared/Library/Application Support/HALCON-12.0
    • The doc folder to /Library/Application Support/HALCON-12.0

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.
  • OPC UA allows multi-dimensional arrays of the basic OPC UA data types. HALCON supports only one-dimensional arrays, and it can only do so if a single OPC UA value is being read or written (i.e., if read_io_channel or write_io_channel are used with multiple channel handles, only scalar values are allowed in each channel).
  • Structures and Unions with arrays or other nested Structures or Unions are not supported.
  • Structures, OptionSets and Unions can only be read and written one at a time. The use of multiple channel handles is not allowed.
  • 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 method calls 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 opcua_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:
  • 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>'

    <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 datatype 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 simple OPC UA data types Duration, ImageBMP, ImageGIF, ImageJPG, ImagePNG, LocaleId, and UtcTime. These types are converted to and from HALCON data types just like the built-in OPC UA types they are derived from. Note that the HALCON I/O interface cannot exchange iconic data, so the OPC UA image data types are treated like the ByteString built-in type. The interface also supports OPC UA complex data types that inherit from Structures, Unions, OptionSet and Enumerations with some limitations. 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.
  • Structures
    These nodes represent a group of variables (fields) that can be of any data type known to the server. The HALCON OPC UA interface currently only supports flat structures made of built-in data types with no arrays as they can't be properly represented in HALCON. Structures have ModelingRules for each of their fields, marking them as optional or mandatory. When reading a structure if a field is marked as optional and a value is not set, HALCON OPC UA interface will ignore this value. When writing to a structure you must provide a value for all fields including those marked as optional.
  • Unions
    These nodes are a special kind of structures where you can select only one field to read at a time. In OPC UA unions consist of a switch field and the value (selected field). The switch field is the index that selects one of the available union fields staring with '1'. A switch field with value '0' represents that the union value is not set and as such the returned value should be ignored. Unions are representation in HALCON with a size two tuple in the following format [SwitchField,Value].
  • OptionSet
    These nodes are a special kind of structures that is used to represent a bit mask. OptionSet contain two ByteString fields 'validBits' and 'value'. These nodes have the property 'OptionSetValues', that contains the human readable representation of each bit of the bit mask. The format in which HALCON works with OptionSets is by alternating between the 'value' and the 'validBits', one Byte at the time, until the whole length of the ByteStrings is returned [value[0],validBits[0],value[1],validBits[1],...].

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'

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
     '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.
     '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.
     '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 integer 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 integer 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.
<[#][!][ns:]ReferenceType>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, ParamName, ParamValue:)
Configure a specific I/O device instance.
Parameter Values Default Type Description
IODeviceHandle integer Handle of the opened I/O device.
ParamName [] string Parameter names.
     '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.
ParamValue [] integer, real, string Parameter values to set.

Operator get_io_device_param

get_io_device_param(::IODeviceHandle, ParamName:ParamValue)
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 integer Handle of the opened I/O device.
ParamName 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.
     '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.
     '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.
     '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.
ParamValue 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 integer 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>:<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' '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' '<NumericalValue>','<EnumString>','<EnumDescription>' integer, string If the passed node is an enumeration, return the possible numerical values and if definition contains an EnumStrings or EnumValues properties return the corresponding information.
     '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' '<DisplayName>','<DataType>','<ModelingRule>' string If the passed node is a Structure, Union or OptionSet return the fields of the data type definition.
     '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.
     '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' string 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.
     '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 integer 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.
     '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 integer Handles of the opened I/O channel.

Operator control_io_channel

Not supported by this interface.

Operator set_io_channel_param

set_io_channel_param(::IOChannelHandle, ParamName, ParamValue:)
Set specific parameters of I/O channels.
Parameter Values Default Type Description
IOChannelHandle integer Handles of the opened I/O channels.
ParamName [] 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.
     '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.
ParamValue [] integer, real, string Parameter values to set.

Operator get_io_channel_param

get_io_channel_param(::IOChannelHandle, ParamName:ParamValue)
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 integer Handles of the opened I/O channels.
ParamName 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>:<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.
     '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' '<NumericalValue>','<EnumString>','<EnumDescription>' integer, string If the passed node is an enumeration, return the possible numerical values and if definition contains an EnumStrings or EnumValues properties return the corresponding information.
     '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' '<DisplayName>','<DataType>','<ModelingRule>' string If the passed node is a Structure, Union or OptionSet return the fields of the data type definition.
     '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.
     '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' string 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.
     '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.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.
ParamValue integer, real, string 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 and be of the simple built-in data types. Structures, Unions and OptionSet can only be written one at a time.
Parameter Values Type Description
IOChannelHandle integer 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 and be of the simple built-in data types. Structures, Unions and OptionSet can only be written one at a time.
Parameter Values Type Description
IOChannelHandle integer 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 integer 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 integer Handle of the opened I/O device.

OpenSSL

This software uses OpenSSL 1.0.2l 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.0.2l by removing libcrypto.1.0.0.so and libssl.1.0.0.so from the directory $HALCONROOT/lib/$HALCONARCH.

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:
  • opcua_browse_variables.hdev - Shows how to browse the available nodes on an OPC UA server.
  • opcua_channel_access.hdev - Shows how to read and write OPC UA variable nodes.
  • opcua_discovery.hdev - Shows how to query an OPC UA discovery server to find OPC UA servers to connect to.
  • opcua_parameters.hdev - Shows how to determine which parameters are supported.
  • opcua_security.hdev - Shows how to connect to an OPC UA server using OPC UA's security features.
  • opcua_read_struct.hdev - Shows how to read a simple structure node on an OPC UA server.
  • opcua_read_write_complex_data_types.hdev - Shows how to read and write different complex data types on an OPC UA server.

Release Notes

  • Revision 1.7 (Sep 29, 2017):
    • 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 1.6 (Apr 28, 2017):
    • Accept expanded node IDs for nodes located on the same server.
  • Revision 1.5 (Mar 06, 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 1.4 (Oct 28, 2016):
    • Add 'connection_status' device parameter.
    • Add 'serializer_settings' interface parameter.
    • Update OpenSSL to version 1.0.1u.
    • Update to version 1.5.2 of the Unified Automation OPC UA SDK.
  • Revision 1.3 (Mar 23, 2016):
  • Revision 1.2 (Feb 15, 2016):
    • Update OpenSSL to version 1.0.1r.
    • Update to version 1.5 of the Unified Automation OPC UA SDK.
    • It is now possible to specify the namespace of a node with the namespace URI.
    • Fix potential memory leak when dealing with byte strings.
  • Revision 1.1 (Jun 10, 2015):
    • The interface can now automatically reconnect to a server after a connection loss.
    • Fixed 'cached' status not being set to true by default if a node is subscribed in open_io_channel.
    • Fixed interface crashing when passing incorrect number of values to write_io_channel.
    • Fixed problem reading an empty arrayDimensions attribute.
    • Correct documentation regarding the retrieval of a server's namespaces.
  • Revision 1.0 (Jan 16, 2014):
    • First official release.