LOG OUT
interfaces mvtec

Interface Documentation

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

Interface: NIDAQmx
Revision: 1.6
Date: 2016-10-28
HALCON Version: 12.0

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 Vista/7/8, Windows Vista/7/8 x64, 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.

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.

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 integer 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, 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.
     '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.
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.
     '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 integer 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' 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: There are some devices which only support one type of edge.
     'ctr_initial_value' <number> integer The initial value of the counter.
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.
     '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: There are some devices which only support one type of edge.
     'ctr_initial_value' <number> 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.
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.
     '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: There are some devices which only support one type of edge.
     '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.
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.
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.

Operator write_io_channel

write_io_channel(::IOChannelHandle, Value:Status)
Write a value to the specified I/O channels.
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.

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.

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 serveral parameters and values.
  • nidaqmx_counter.hdev - Example to show how to use the counter function of some interfaces.

Release Notes

  • Revision 1.6 (Oct 28, 2016):
    • 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 behavior has been adapted to all other I/O interfaces that 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', ... et cetera.
      • 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.
Products/MVTec Interfaces