Hilscher cifX I/O Interface for Hilscher PCI and PCIe cards

This page provides the documentation of the HALCON Hilscher-cifX interface for accessing the Hilscher PCI and PCIe 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.

• Intel compatible PC with Windows 7 (32-bit or 64-bit) or newer that is also supported by the vendor-specific SDK. Intel or Arm Linux (64-bit) that is also supported by the vendor-specific SDK.
• Installed Hilscher cifX Device Driver (NXDRV-WIN) version 1.3.0.0 (or higher) on windows or Hilscher NetX Card driver UIO_NETX on linux. Additionally, on linux, libcifx.so.3 must be available.
• Installed SYCON.net or Slave Configuration Tool to configure the Hilscher device, on linux using e.g. cifX tcp-server.
• Windows: HALCON I/O interface hioHilscher-cifX.dll or hioHilscher-cifXxl.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.
  

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.

Only when installing or updating the interface manually follow these steps:

• 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.

• Implementation of a cifX Device Driver general interface.

• Windows and Linux are not considered as deterministic real time operating systems. The response times can't be guaranteed and are affected by multiple factors including hardware, installed drivers and other services running in parallel.
• Support only for official firmware provided by Hilscher.
• Protocol specific functions are not supported.
• The interface has been tested to work with PROFINET, EtherCat and Ethernet/IP firmware, other protocols should work but were not tested.
• The 'Ethernet Interface' channel is not supported.
• On Linux, support is limited to one Hilscher Card per system. The card will be restarted by the used libcifx implementation during the open_io_device and all hardware related query_io_interface operator calls.

To correctly use this interface it is required that in addition to this interface documentation at a minimum the user reviews the following basic Hilscher documentation files:

• cifX Manuals for your respective device
• Configuration Manuals for SYCON.net or the Slave Configuration Tool
• Device Driver Manuals

You can find all of this manuals in the documentation section of the Hilscher DVD or their website.

• Linux: Documentation of Hilscher github project 'cifX device driver for linux' https://github.com/HilscherAutomation/nxdrvlinux/

It is possible to automatically convert the input and output data 'to' and 'from' HALCON types (long, double, string) by specifying a data conversion format. The conversion format is specified by means of a string of qualified chars that is loosely based on the one used by the HALCON sockets interface. The conversion is very straight forward but there are some important things to consider:

• The conversion can't be executed if the size of the input or output data doesn't coincide with the expected size for the conversion.
• When converting bytes into strings the size must always be specified. Null termination will be added to the string in case it is not present.
• Only ASCII strings are currently supported.

Each supported type has a qualified character assigned. The format string is created by appending the qualified character plus an optional repetition count. For example the float data type is of size 4 and is represented by the letter 'f' if you want to specify the data conversion of five floats you can use the string 'fffff' or a 'f5' and you will need to have a buffer of size 20 to do the conversion, this floats will the be converted to an appropriated HALCON type. The available types and their qualifiers are as follows:

TYPE	SIZE	QUALIFIER
char	1	'c'
uchar	1	'C'
short	2	's'
ushort	2	'S'
int32	4	'i'
uint32	4	'I'
int64	8	'q'
uint64	8	'Q'
float	4	'f'
double	8	'd'
string	x	'z'

Note: int64 and uint64 are only available on 64bit architectures.

There are some additional characters that can be used as part of the format string and are used to solve special cases:

QUALIFIER	DESCRIPTION
'-'	A single byte is written as binary zero or when reading a byte is skipped. It is also possible to specify a repetition value with this qualifier.
'n'	Convert all the following numerical values (int, float, double, ...) when reading or writing from little endian to host byte order.(1)
'N'	Convert all the following numerical values (int, float, double, ...) when reading or writing from big endian to host byte order.(1)

(1) On Windows systems the most common host endianness is little endian.

Please refer to the example hilscher-cifx_data_conversion.hdev provided with this interface.

Not supported by this interface.

query_io_interface(::IOInterfaceName, Query:Result)

Query information about the specified I/O device interface.

open_io_device(::IOInterfaceName, IODeviceName, GenParamName, GenParamValue:IODeviceHandle)

Open and configure an I/O device.

control_io_device(::IODeviceHandle, Action, Argument:Result)

Perform an action on the I/O device.

Not supported by this interface.

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'.

query_io_device(::IODeviceHandle, IOChannelName, Query:Result)

Query information about channels of the specified I/O device.

open_io_channel(::IODeviceHandle, IOChannelName, GenParamName, GenParamValue:IOChannelHandle)

When you open a channel the interface will try to change the following parameters on the channel:

• host_state to 'ready'
• config_lock to 'unlock'
  
  

control_io_channel(::IOChannelHandle, Action, Argument:Result)

Perform an action on I/O channels.

set_io_channel_param(::IOChannelHandle, GenParamName, GenParamValue:)

Set specific parameters of I/O channels.

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'.

read_io_channel(::IOChannelHandle:Value, Status)

If no data conversion format is specified, reading a channel will return a tuple array of unsigned bytes of the specified input size on the device configuration. To get the expected size use the parameter 'input_data_size'.

Read operations are always expected to return multiple values. Because of this it is not allowed to use multiple channel handles, so you must read from each channel individually.

write_io_channel(::IOChannelHandle, Value:Status)

If no data conversion format is specified, writing to a channel must be done by providing an array of tuples of unsigned byte of the output size on the device configuration. To get the expected size use the parameter 'output_data_size'.

Write operations are always expected to require multiple values. Because of this it is not allowed to use multiple channel handles, you must write to each channel individually.

close_io_channel(::IOChannelHandle:)

When you close a channel the interface will try to change the following parameters on the channel:

• bus_state to 'off',
• host_state to 'not_ready'
• config_lock to 'unlock'
• dma_mode to 'off'
  
  

close_io_device(::IODeviceHandle:)

Close the specified I/O device.

For this interface the following examples are available:

• hilscher-cifx_read.hdev - Example to show how to read input data from a Hilscher device.
• hilscher-cifx_write.hdev - Example to show how to write output data to a Hilscher device.
• hilscher-cifx_data_conversion.hdev - Example to show how to read and write data from a Hilscher device using a data conversion format.
• hilscher-cifx_simple_diagnostic.hdev - Example to show how to get diagnostic information from your Hilscher device.

• Revision 24.11.7 (Mar 3, 2026):
  • A parameter 'synchronous_read' has been added to open_io_channel and set_io_channel_param to switch read_io_channel between low-latency operator return or fieldbus synchronous data reading.
  • This interface now is also available for Linux and Linux for Arm (64-bit) systems.
• Revision 24.11.6 (Oct 8, 2025):
  • A Software Bill of Materials (SBOM) in the System Package Data Exchange (SPDX) format has been added next to each binary file with the same name extended by ".spdx.json".
• Revision 20.11.5 (Aug 1, 2023):
  • The operator open_io_channel crashed when using the output of query_io_device(..., 'io_channels_info',...) as an argument. This problem has been fixed.
  • The distribution package of this interface now contains files providing meta information for the HDevelop example browser.
• Revision 18.11.4 (Oct 27, 2020):
  • This interface couldn't be loaded from .NET Core applications on Linux and macOS. This problem has been fixed.
• Revision 13.0.3 (Jun 11, 2019):
  • Multi-channel operations on get_io_channel_param and set_io_channel_param did not reference the correct channel in some cases. This problem has been fixed.
• Revision 13.0.2 (Nov 30, 2018):
  • First official release.