interfaces mvtec

Interface Documentation

Advantech I/O Interface for Advantech digital I/O devices

Interface: Advantech
Revision: 20.11.5
Date: 2023-08-01

General

This page provides the documentation of the HALCON Advantech interface for accessing the Advantech Digital I/O cards. 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).
  • Installed Advantech DAQNavi SDK version 3.1.6 (or higher). See Limitations section for version 4.0 (or higher).
  • Windows: HALCON I/O interface hioAdvantech.dll or hioAdvantechxl.dll, respectively. 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.

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.

Features

  • Opening and using of multiple Advantech I/O ports.
  • Opening and using of multiple specific channels (specific port values).

Limitations

  • No support of event counters
  • No support of pattern matching
  • No support of analog functions
  • In case of DAQNavi SDK version 4.0 (or higher), the device settings defined in the Advantech Navigator are not automatically stored and loaded from the registry anymore, but from a configuration file. Since the current interface does not support loading a configuration file, the default settings of the device are used instead. This may be critical for bidirectional devices, since the port direction can not be changed.

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 'Advantech' string HALCON I/O interface name.
Query string Parameter name of the query.
     'io_device_names' '<name>' string Returns a list of available devices.
     'param_name' '<parameter>'[,'<parameter>'...] string Returns the possible parameter names.
     'revision' '<version>.<revision>.<build>' string Revision number of the 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 'Advantech' [] string HALCON I/O interface name.
IODeviceName [] string I/O device name.
GenParamName [] string Dynamic parameter names.
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

Set the device parameters. Currently, no parameters are defined.

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.
     'io_device_name' '<name>' string Returns the name of the device.
     'param_name' '<parameter>'[,'<parameter>'...] string Returns the possible parameter names.
GenParamValue integer, real, string, handle 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.
     'channel_type' 'digital_input', 'digital_output' string Returns the type of the passed channel.
     'io_channel_names' '<name>' string Returns a list of channels provided by the device, e.g., 'di_0.2' describes input port channel 2 on port 0. To list only the channels of a specific type, use the special form io_channel_names.<channel_type> (for a list of valid channel types, see the description of the channel_type parameter).
     'param_name' '<parameter>'[,'<parameter>'...] string Returns the possible parameter names.
     'value.range' [<min>,<max>,<step>] string Return the possible range of the used I/O channel name parameter
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.
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

Not supported by this interface.

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.
     'channel_type' 'digital_input', 'digital_output' string Returns the type of the passed channel.
     'data_mask' 0,<channel_width> integer Returns the data mask. This information specifies the format of the data that could be read out via read_io_channel or that could be set via write_io_channel. If a channel is opened, the range of possible values is 0 and 1 because of the data mask with the value 1. If a complete port is used all channels of a port will be accessed. In this case the format of the data mask depends also on the port size. A port with 8 channels (8bit) has the format 0xFF in this case e.g. a value of 255 could be used with write_io_channel to set the complete port (all channels) to 1. With 0 the complete port will be set to 0. Of course, any other values between 0 and 255 could also be written to the port.
     'io_channel_name' '<name>' string Returns the name of the channel.
     'param_name' '<parameter>'[,'<parameter>'...] string Returns the possible parameter names.
     'programmable' 'true', 'false' string Specifies if the used channel parameter is programmable or not.
GenParamValue integer, real, string, handle Parameter values.

Operator read_io_channel

read_io_channel(::IOChannelHandle:Value, Status)
Read the value from the specific I/O channel or from a port.
Parameter Values Type Description
IOChannelHandle handle Handles of the opened I/O channels.
Value integer, real, string, handle 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 specific I/O channel or to a port. If several handles are passed, an atomically write is only supported if the order of the handles is not arbitrary. Ports and channels will be written atomically if an ascending order with no gaps is given, e.g. if the following handle values will be passed (the name (do_x.x) represents the handle queried via open_io_channel) ['do_0.1', 'do_0.5', 'do_1.4', 'do_2.0']. In case of ['do_0.0','do_2.0'] or ['do_1.0','do_0.0'] the execution is not atomically and two write calls will be executed internally.
Parameter Values Type Description
IOChannelHandle handle Handles of the opened I/O channels.
Value integer, real, string, handle 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.
Query the requested information from the specified I/O channels. The parameter 'ParameterNode' is not used by this interface.

HDevelop Examples

For this interface the following examples are available:
  • advantech_digital_read.hdev - Example to show how to read several parameters and values.
  • advantech_digital_write.hdev - Example to show how to write several parameters and values.

Release Notes

  • Revision 20.11.5 (Aug 1, 2023):
    • The distribution package of this interface now contains files providing meta information for the HDevelop example browser.
    • If the device description or name contained UNICODE characters HALCON was unable to set them correctly. This problem has been fixed.
  • Revision 13.0.4 (Nov 22, 2017):
    • The technical dependency from the HALCON Library has been removed.
    • DAQNavi SDK version 4.0 (or higher) is not fully supported. A compatibility note has been added to the Limitations section.
  • Revision 13.0.3 (Oct 4, 2017):
    • With DAQNavi SDK version 4, the output ports could not be retrieved when querying 'io_channel_names' or 'io_channel_names.digital_output' in query_io_device. This problem has been fixed.
  • Revision 13.0.2 (Feb 22, 2017):
    • After a channel is initialized, the first call of write_io_channel could result in wrong output values. This problem has been fixed.
  • Revision 13.0.1 (Oct 28, 2016):
    • HALCON 13 version of the interface.
  • Revision 1.2 (May 13, 2016):
    • In read_io_channel, when reading an input port, the value of the returned Status parameter was always 1 (failure). This problem has been fixed.
  • Revision 1.1 (Apr 25, 2016):
    • When querying the channels list with query_io_device, the current port direction configuration was not taking into account for bi-directional ports. This problem has been fixed.
    • When querying the channel list of unsupported channel types an error message was returned. This problem has been fixed and now an empty tuple is returned.
    • The query of the possible parameter names accepted by query_io_device returned an error. This problem has been fixed.
    • query_io_device returned an empty tuple when querying the channel type without specifying a channel. This problem has been fixed and now an error is returned.
    • query_io_device crashed when querying 'value.range' without specifying a channel name. This problem has been solved and now an error is returned.
  • Revision 1.0 (Jan 10, 2014):
    • First official release.