Interface Documentation
OPC_Classic I/O Interface for OPC Classic compliant devices
| Interface: | OPC_Classic |
| Revision: | 20.11.4 |
| Date: | 2024-04-18 |
- General
- System Requirements
- Installation
- Upgrading From Version 20.11.3 Or Earlier
- Features
- Limitations
- Connecting to an OPC Classic server
- Converting data between HALCON and OPC Classic
- Specifying OPC Classic variables
- Operator control_io_interface
- Operator query_io_interface
- Operator open_io_device
- Operator control_io_device
- Operator set_io_device_param
- Operator get_io_device_param
- Operator query_io_device
- Operator open_io_channel
- Operator control_io_channel
- Operator set_io_channel_param
- Operator get_io_channel_param
- Operator read_io_channel
- Operator write_io_channel
- Operator close_io_channel
- Operator close_io_device
- Usage of third-party libraries
- OpenSSL
- HDevelop Examples
- Release Notes
General
This page provides the documentation of the HALCON OPC Classic 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.
Registered customers can download the latest revision of this interface from the MVTec WWW server.
System Requirements
- Intel compatible PC with Windows 10 (64-bit) or newer that is also supported by the vendor-specific SDK, Linux with kernel 6.X (or higher).
- OPC Core Components Redistributable package for Windows x64. If this package is not installed, please download and install it from the OPC Foundation website.
- Windows: HALCON I/O device interface hioOPC_Classic.dll
or hioOPC_Classicxl.dll, respectively. Also required are
libcrypto-3-x64.dll, libssl-3-x64.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. Please note
that the HALCON OPC_UA interface uses the same DLLs.
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.
Upgrading From Version 20.11.3 Or Earlier
Starting with version 20.11.4, this interface uses OpenSSL 3.
Features
- Implementation of an OPC Classic (also known as OPC DA, OPC ComDA) client.
Limitations
- Only OPC Data Access (OPC DA) is supported.
- No OPC device discovery. OPC Classic server name must be set according to the setup of the server.
- No support for public groups.
- The OPC Classic I/O interface returns and expects all strings in UTF-8 encoding.
- All dates and times are assumed to be UTC.
- The OPC Classic I/O interface only supports one-dimensional arrays, and it can only do so if a single OPC 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).
- On 32-bit systems, 64-bit OPC 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.
Connecting to an OPC Classic server
The open_io_device operator is used to connect to an OPC Classic server. Specify the URL of the server to connect to with the IODeviceName
parameter. The server URL is generally in the form
'opcda://<machine name>/<server ProgID>[/<CLSID>]'.
Converting data between HALCON and OPC Classic
OPC Classic 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. The
HALCON OPC Classic I/O device interface supports the following built-in OPC
data types:
- 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. - 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. - String
This type is represented as a HALCON string. Please note that the OPC Classic I/O interface returns and expects all strings in UTF-8 encoding.
Specifying OPC Classic variables
OPC Classic items are referenced by using their item ID written as a string as the channel parameter in the query_io_device and open_io_channel
operators.
Operator control_io_interface
Not supported by this interface.
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_Classic' | string | HALCON I/O interface name. |
| Query | string | Parameter name of the query. | |
| 'param_name' | string | Returns the possible parameter names. | |
| 'revision' | string | Revision number of the OPC COM DataAccess 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_Classic' | [] | string | HALCON I/O interface name. |
| IODeviceName | [] | string | I/O device name. | |
| GenParamName | [] | string | Dynamic parameter names. | |
| 'browse_interface' | 'Default', 'ComDA2', 'ComDA3' | 'Default' | string | Override automatic choice of interface to use for browsing. |
| 'keep_alive_time' | <milliseconds> | integer | Time interval to do cyclic keep-alive read. | |
| 'locale_id' | 'en-US' | string | Locale to set for the connection. | |
| 'reconnect_after_connection_error' | 'true', 'false' | 'true' | bool | Flag to indicate if the server shall do an automatic reconnect after the connection was interrupted. |
| GenParamValue | [] | integer, real, string | Dynamic parameter values. | |
| IODeviceHandle | handle | Handle of the opened I/O device. |
Operator control_io_device
Not supported by this interface.
Operator set_io_device_param
Not supported by this interface.
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:
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. | |
| 'browse_interface' | 'Default', 'ComDA2', 'ComDA3' | string | Override automatic choice of interface to use for browsing. |
| 'io_device_name' | <device URL> | string | Returns the name of the device. |
| 'keep_alive_time' | <milliseconds> | integer | Time interval to do cyclic keep-alive read. |
| 'locale_id' | string | Locale to set for the connection. | |
| 'param_name' | string | Returns the possible parameter names. | |
| 'reconnect_after_connection_error' | 'true', 'false' | bool | Flag to indicate if the server shall do an automatic reconnect after the connection was interrupted. |
| 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_rights' | 'Readable', 'Writeable', 'ReadWriteable', 'Unknown' | string | Item access rights. |
| 'browse' | <ItemId>,<IsItem>,<HasChildren>[,<ItemId>,<IsItem>,<HasChildren>,...] | 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 COM DA node tree. For each node the OPC ItemId is returned. The ItemId can be used as a channel name for subsequent channel operations. No other queries may be requested in this call to query_io_device. |
| 'data_type' | 'Boolean', 'Byte', 'DateTime', 'Double', 'Float', 'Int16', 'Int32', 'Int64', 'SByte', 'String', 'UInt16', 'UInt32', 'UInt64', 'Unknown' | string | Canonical datatype of the OPC item on the server. |
| 'param_name' | string | Returns the possible parameter names. | |
| 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. | |
| 'deadband' | <number> | float | Minimum interval between 2 updates for this item in milliseconds. 0 means the item is not added to a subscription. | |
| 'read_from_cache' | 'true', 'false' | 'false' | bool | Read values from cache instead of reading directly from the server. Read from the server anyway if the updaterate = 0 or if no value is available. |
| 'update_rate' | <milliseconds> | integer | Interval in milliseconds to receive datachange updates from the server. 0 means the item is not added to a subscription. | |
| GenParamValue | [] | integer, real, string | Parameter values. | |
| IOChannelHandle | handle | 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, 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. | |
| 'deadband' | <number> | float | Minimum interval between 2 updates for this item in milliseconds. 0 means the item is not added to a subscription. | |
| 'read_from_cache' | 'true', 'false' | 'false' | bool | Read values from cache instead of reading directly from the server. Read from the server anyway if the updaterate = 0 or if no value is available. |
| 'update_rate' | <milliseconds> | integer | Interval in milliseconds to receive datachange updates from the server. 0 means the item is not added to a subscription. | |
| 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:
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_rights' | 'Readable', 'Writeable', 'ReadWriteable', 'Unknown' | string | Item access rights. |
| 'data_type' | 'Boolean', 'Byte', 'DateTime', 'Double', 'Float', 'Int16', 'Int32', 'Int64', 'SByte', 'String', 'UInt16', 'UInt32', 'UInt64', 'Unknown' | string | Canonical datatype of the OPC item on the server. |
| 'deadband' | <number> | float | Minimum interval between 2 updates for this item in milliseconds. 0 means the item is not added to a subscription. |
| 'io_channel_name' | string | Return the name of the channel. | |
| 'param_name' | string | Returns the possible parameter names. | |
| 'read_from_cache' | 'true', 'false' | bool | Read values from cache instead of reading directly from the server. Read from the server anyway if the updaterate = 0 or if no value is available. |
| 'update_rate' | <milliseconds> | integer | Interval in milliseconds to receive datachange updates from the server. 0 means the item is not added to a subscription. |
| 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.
| 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. |
Operator write_io_channel
write_io_channel(::IOChannelHandle, Value:Status)
Write a value to the specified I/O channels.
| 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. |
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 third-party libraries
This interface depends on third-party libraries. See the file third_party_opc.txt
in the HALCON base directory for copyright and license information.
Libraries are used without modifications unless explicitly stated in the file.
You can request the source for those third-party libraries licensed under GPL or LGPL via email to info@mvtec.com with the subject âRequest source code of third-party librariesâ.
OpenSSL
This software uses OpenSSL 3 for secure communication with OPC Classic servers. It was configured and built with the options no-idea,
no-mdc2, no-ntt, and no-rc5 to avoid patent
issues.
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_browse_variables.hdev - Shows how to browse the available items on an OPC Classic server.
- opc_channel_access.hdev - Shows how to read and write OPC Classic items.
- opc_parameters.hdev - Shows how to determine which parameters are supported.
Release Notes
- Revision 20.11.4 (Apr 18, 2024):
- OpenSSL has been updated to version 3.2.1.
- The Unified Automation OPC UA SDK has been updated to version 1.8.3.
- Revision 20.11.3 (Aug 1, 2023):
- OpenSSL has been updated to version 1.1.1k.
- The Unified Automation OPC UA SDK has been updated to version 1.7.6.
- third_party_opc.txt now contains links to the corresponding software location. See also Usage of third-party libraries.
- The distribution package of this interface now contains files providing meta information for the HDevelop example browser.
- Revision 19.11.2 (Aug 27, 2020):
- OpenSSL has been updated to version 1.1.1g.
- The Unified Automation OPC UA SDK has been updated to version 1.7.2.
- Revision 19.11.1 (Oct 15, 2019):
- This version of the OPC Classic interface will only work in its complete form for HALCON versions starting from 19.11 and higher.
- Update OpenSSL to version 1.1.1c
- Update to version 1.7.0 of the Unified Automation OPC UA SDK
- Revision 13.0.4 (Oct 11, 2018):
- Update OpenSSL to version 1.0.2p
- Update to version 1.6.2 of the Unified Automation OPC UA SDK
- Revision 13.0.3 (Nov 28, 2017):
- The technical dependency from the HALCON Library has been removed.
- Revision 13.0.2 (Mar 6, 2017):
- 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.
- Update OpenSSL to version 1.0.1u.
- Update to version 1.5.2 of the Unified Automation OPC UA SDK.
- 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.
- Fix potential memory leak when dealing with byte strings.
- Revision 1.1 (May 11, 2015):
- Fixed interface crashing when passing incorrect number of values to write_io_channel.
- Fixed problem with reading value arrays.
- Revision 1.0 (Sep 22, 2014):
- First official release.