登出
interfaces mvtec

资料

NIDAQmx I/O Interface for National Instruments digital I/O devices

Interface: NIDAQmx
Revision: 20.11.4
Date: 2023-08-01

General

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

System Requirements

  • Intel compatible PC with Windows 7 (32-bit or 64-bit) or newer that is also supported by the vendor-specific SDK, also WoW64 (using 32-bit HALCON on 64-bit Windows).
  • Installed NI-DAQmx with version 9.7.5 (or higher).
  • Windows: HALCON I/O device interface hioNIDAQmx.dll or hioNIDAQmxxl.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.

Interface Versioning

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

Installation

Only when installing or updating the interface manually follow these steps:
  • Windows: Extract the archive containing the interface files to the HALCON base directory %HALCONROOT% (Note: Administrator privileges may be required for this step). Additionally, you have to move the interface examples to the directory %HALCONEXAMPLES% manually.

Features

  • Opening and using of one or several channels provided by the interface.
  • Reading and writing of one or several I/O channels.
  • Using of one or several channels as an event counter.

Limitations

  • No support of analog channels.
  • No support of timers.
  • No support of other NI-DAQmx features.
  • NI-USB devices are not hot pluggable. Unplugging of an NI-USB device while running your application will crash your application.
  • For devices where a pin can be used either as a digital output or a digital input channel, the first read or write operation after opening the channel may take substantially longer.

Specifying virtual NIDAQmx channels

NIDAQmx physical channels can be aggregated to virtual channels. The physical channels address single lines at a specific port and can be queried with the operator call query_io_device and the parameter name 'io_channel_names'. The format of the channels follows the following pattern: '&ltchannel_type&gt_&ltport&gt.&ltline&gt', e.g., 'di_1.2' for a digital input line 2 on port 1.
Line aggregation is obtained by specifying a range of lines at the same port, like 'di_0.1-3' for the physical lines 'di_0.1', 'di_0.2', and 'di_0.3'. When aggregating all lines of a single port, like 'di_0.0-7' of a 8-bit port 0, the port 0 can be addressed instead, like 'di_0'.

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 'NIDAQmx' string HALCON I/O interface name.
Query string Parameter name of the query.
     'io_device_info' ['device:<device id> | model:<model name> | serial:<serial number>'], ['device:<device id> | model:<model name> | simulated:true'] string Returns a list of available devices with information about their device ID, model name and serial number. In case of simulated devices, the serial number is replaced by 'simulated:true'.
     'io_device_names' '<name>' string Returns a list of available devices.
     'nidaqmx_revision' '<major version>.<minor version>.<update>' string Revision number of the used NIDAQmx sdk.
     'param_name' '<parameter>'[,'<parameter>'...] string Returns the possible parameter names.
     'revision' '<version>.<revision>.<build>' string Revision number of this HALCON 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 'NIDAQmx' [] 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

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:
  • '.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.
     'is_simulated' 'false', 'true' string If 'true', the device is a simulated one, not a real 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' 'counter', 'digital_input', 'digital_output' string Returns the type of a channel.
     'io_channel_names' '<name>' string Returns a list of physical channels provided by the device, e.g., 'di_0.2' describes digital input line 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.
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.
     'ctr_count_direction' 'count_down', 'count_up' 'count_up' string Describes whether the counter increments or decrements the initial value.
     'ctr_edge_type' 'falling_edge', 'rising_edge' 'falling_edge' string The type of edge which will be used to count the event.
Attention: When opening a channel, if no initial value is provided, the interface first try to set the value falling_edge if this fails it will then try to use rising_edge. If an unsupported initial value is indicated in open_io_device an exception will be thrown.
     'ctr_initial_value' <number> 0 integer The initial value of the counter.
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.
     'ctr_count_direction' 'count_down', 'count_up' 'count_up' string Describes whether the counter increments or decrements the initial value.
     'ctr_edge_type' 'falling_edge', 'rising_edge' 'falling_edge' string The type of edge which will be used to count the event.
Attention: When opening a channel, if no initial value is provided, the interface first try to set the value falling_edge if this fails it will then try to use rising_edge. If an unsupported initial value is indicated in open_io_device an exception will be thrown.
     'ctr_initial_value' <number> 0 integer The initial value of the counter.
     'ctr_reset' integer Writing any value to this parameter resets the counter to the value given by ctr_initial_value.
     'ctr_running' 0, 1 integer If the parameter is used with get_io_channel_param it shows whether the counter is running or not. Used with set_io_channel_param it starts or stops the counter.
     'task_control' 'start', 'stop', 'verify', 'commit', 'reserve', 'unreserve', 'abort' string In context with set_io_channel_param this parameter alters the state of the task according to the action specified. E.g., 'start' sets the NI acquisition engine into run state which will result in a better sample rate. In context with get_io_channel_param the last action on the task control performed by the HALCON NIDAQmx interface is returned.
GenParamValue [] integer, real, string, handle Parameter values to set.

Operator get_io_channel_param

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

There may exist additional parameter attributes, which can be accessed as 'ParamNames.AttributeName'. The following standard attributes may be available:
  • '.access': This attribute provides the access permissions of the corresponding parameter as a string. Possible values are 'ro' (read-only), 'wo' (write-only), 'rw' (read/write), 'na' (unavailable, perhaps due to insufficient access rights), and 'ni' (unavailable, not defined for this device or channel).
  • '.category': This attribute provides the category of the corresponding parameter as a string. 'I/O interface' for all pre-defined I/O interface parameters.
  • '.default': This attribute provides the default value of the corresponding parameter.
  • '.description': This attribute provides the description of the corresponding parameter as a string.
  • '.displayname': This attribute provides the displayname of the corresponding parameter as a string.
  • '.range': This attribute provides the minimum and maximum, (and the step width, if applicable) for the corresponding integer or float parameter as a tuple with 2 (or 3) elements.
  • '.representation': This attribute provides how the value of the parameter should be displayed in a GUI: 'ip address', 'hex', ...
  • '.tooltip': This attribute provides the tool-tip of the corresponding parameter as a string.
  • '.type': This attribute provides the HALCON value type (integer, real, or string) of the corresponding parameter as a string.
  • '.values': This attribute provides the valid value list for the corresponding parameter as a tuple.
  • '.visibility': This attribute provides the visibility of the corresponding parameter as a string. Possible values are 'common', 'extended', and 'dangerous'.
  • '.unit': This attribute provides the units of the corresponding parameter as a string. For example: 'ns', 'us' and 'ms', or 'mm', 'cm', 'dm' and 'm'.
Parameter Values Type Description
IOChannelHandle handle Handles of the opened I/O channels.
GenParamName string Parameter names.
     'channel_type' 'counter', 'digital_input', 'digital_output' string Returns the type of a channel.
     'ctr_count_direction' 'count_down', 'count_up' string Describes whether the counter increments or decrements the initial value.
     'ctr_edge_type' 'falling_edge', 'rising_edge' string The type of edge which will be used to count the event.
Attention: When opening a channel, if no initial value is provided, the interface first try to set the value falling_edge if this fails it will then try to use rising_edge. If an unsupported initial value is indicated in open_io_device an exception will be thrown.
     'ctr_initial_value' <number> integer The initial value of the counter.
     'ctr_running' 0, 1 integer If the parameter is used with get_io_channel_param it shows whether the counter is running or not. Used with set_io_channel_param it starts or stops the counter.
     'io_channel_name' '<name>' string Returns the name of the channel.
     'param_name' '<parameter>'[,'<parameter>'...] string Returns the possible parameter names.
     'task_control' 'start', 'stop', 'verify', 'commit', 'reserve', 'unreserve', 'abort' string In context with set_io_channel_param this parameter alters the state of the task according to the action specified. E.g., 'start' sets the NI acquisition engine into run state which will result in a better sample rate. In context with get_io_channel_param the last action on the task control performed by the HALCON NIDAQmx interface is returned.
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, 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 specified I/O channels.
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.

HDevelop Examples

For this interface there are the following examples available:
  • nidaqmx_digital_read.hdev - Example to show how to read several parameters and values.
  • nidaqmx_digital_write.hdev - Example to show how to write several parameters and values.
  • nidaqmx_counter.hdev - Example to show how to use the counter function of some interfaces.

Release Notes

  • Revision 20.11.4 (Aug 1, 2023):
    • The distribution package of this interface now contains files providing meta information for the HDevelop example browser.
  • Revision 13.0.3 (Jul 19, 2018):
    • The 'param_name' query of a counter type channel via get_io_channel_param did not return all the available parameters. This problem has been fixed.
    • open_io_device forced internally the edge active direction ('ctr_edge_type') to 'falling_edge'. If the device did not support this edge active direction, open_io_device failed. Now if no edge active direction was specified, open_io_device will silently try to set 'rising_edge'.
    • 'ctr_reset' reset the value of the counter to 0 and not to the value given by 'ctr_initial_value'. This problem has been fixed.
    • In some cases close_io_device may fail due to device timing problems. This problem has been fixed.
    • If you open a channel multiple times and then close one of them all other channels became invalid and generated a crash. This problem has been fixed.
  • Revision 13.0.2 (Nov 28, 2017):
    • The technical dependency from the HALCON Library has been removed.
  • Revision 13.0.1 (Oct 28, 2016):
    • HALCON 13 version of the interface.
    • read_io_channel and write_io_channel expected the value for the channel on the specific bit corresponding to the addressed line of the channel. This behaviour has been adapted to the behaviour of all other I/O interfaces. I.e., the operators expect the values 0 or 1 for single lines, independent of the position of the line.
  • Revision 1.5 (Jul 06, 2016):
    • read_io_channel did not read digital input channels correctly. This problem has been fixed.
  • Revision 1.4 (Jun 29, 2016):
    • The interface has been revised and the achievable sample rate of the operators read_io_channel and write_io_channel has been improved.
    • A channel can aggregate lines of a port or address a complete port.
    • set_io_channel_param and get_io_channel_param support the new parameter name 'task_control'. It allows the direct control of the NIDAQmx task state model.
    • open_io_channel supports the parameter names 'ctr_count_direction', 'ctr_edge_type', 'ctr_initial_value' for counters.
    • The parameter 'ctr_reset' of set_io_channel_param did not reset the counter to its initial value properly. This problem has been fixed.
    • The parameter 'parameter_names' of the operator query_io_device did not return the parameter names correctly. This problem has been fixed.
    • In very rare cases, the return of multiple parameter values in the operators query_io_* and get_io_*_param led to a crash. This problem has been fixed.
    • The parameter 'ctr_value' of the operator get_io_channel_param is legacy. It is still operable but not listed in the documentation anymore. Use the operator read_io_channel instead.
    • Compatibility Notes: please, adapt an existing application accordingly.
      • The naming of channels of type 'counter' changed. NI enumerates counters and omits the line number within the channel name, therefore. E.g., use 'ctr_0', 'ctr_1', ... instead of former 'ctr_0.24', ... etcetera.
      • The channel type 'digital_io' is not supported anymore. I.e., neither the parameter name 'io_channel_names' of the operator query_io_device supports the attribute '.digital_io' nor does open_io_channel support channel names starting with 'dio'. Applications that already use this former type have to open these channels as 'digtal_input' and/or 'digital_output' channel. E.g., split a former 'dio_0.0' channel name into the two channels 'di_0.0' for digital input and/or 'do_0.0' for digital output.
  • Revision 1.3 (Mar 29, 2016):
    • query_io_interface now supports the query 'io_device_info' which returns a list of the available devices with additional information.
    • query_io_device should return an error when querying the channel type without specifying a channel. This problem has been fixed.
  • Revision 1.2 (Aug 27, 2015):
    • Devices with only digital input channels or only digital output channels were not supported. This problem has been fixed.
    • The HDevelop example nidaqmx_digital_read.hdev and nidaqmx_digital_write.hdev showed only how to read input channels or how to write output channels. Now they also show how to read and write I/O channels.
  • Revision 1.1 (Jan 28, 2015):
  • Revision 1.0 (Jan 10, 2014):
    • First official release.
我们的产品/MVTec 接口