Dokumentation
Hilscher cifX I/O Interface for Hilscher PCI and PCIe cards
Interface: | Hilscher-cifX |
Revision: | 20.11.5 |
Date: | 2023-08-02 |
- General
- System Requirements
- Interface Versioning
- Installation
- Features
- Limitations
- Hilscher Reference Documentation
- Converting the Input and Output Data to HALCON Types
- 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
- HDevelop Examples
- Release Notes
General
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.
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.
- Installed Hilscher cifX Device Driver (NXDRV-WIN) version 1.3.0.0 (or higher).
- Installed SYCON.net or Slave Configuration Tool to configure the Hilscher device.
- 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.
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
- Implementation of a cifX Device Driver general interface.
Limitations
- Windows is not a deterministic real time operating system. 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.
Hilscher Reference Documentation
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.
Converting the Input and Output Data to HALCON Types
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:
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:
(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.
- 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.
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.
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 | 'Hilscher-cifX' | string | HALCON I/O interface name. |
Query | string | Parameter name of the query. | |
'io_channels_info' | [' device:<device> | ch_name:<channel> | firmware:<firmware> | version:<version> | build_date:<dd-mm-yy>'] | string | List of all available channels on all devices or a single device with relevant information. |
'io_device_info' | ['device:<device> | alias:<alias> | dev_number:<device number> | serial:<serial number> | dev_id:<device id>| channel_count:<number of channels>'] | string | List of available devices with additional information, including the device name, alias (if available), device number, serial number, device id (rotary switch) and the number of channels. |
'io_device_names' | '<name>' | string | 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 | 'Hilscher-cifX' | [] | 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
control_io_device(::IODeviceHandle, Action, Argument:Result)
Perform an action on the I/O device.
Parameter | Values | Default | Type | Description |
---|---|---|---|---|
IODeviceHandle | handle | Handle of the opened I/O device. | ||
Action | string | Name of the action to perform. | ||
'restart_firmware' | Restart the firmware on netX board. All communication channels will stop and reset. In some special cases the complete board can also be reset. You can specify a timeout in milliseconds to wait for restart to complete, if no value is specified the default timeout is one second. | |||
Argument | 1000 | |||
Result | 1000 | integer | ||
Argument | [] | integer, real, string | List of arguments for the action. | |
Result | integer, real, string | List of result values returned by the action. |
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. | |
'cpu_load' | integer | The current CPU load of the device in 0.01 units. (Eg. 10000 = 100%) | |
'device_error' | integer | The current device error code. If no errors have occurred or the problem has been solve the return value will be zero. To identify the meaning of the error please 'Error Codes' manual provided by Hilscher. | |
'io_device_name' | '<name>' | string | The name of the device. |
'param_name' | '<parameter>'[,'<parameter>'...] | string | Returns the possible parameter names. |
'time_since_startup' | integer | The total operation time since start up in seconds. | |
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. | |
'io_channel_names' | '<channel>' | string | List of channels provided by the device. |
'io_channels_info' | [' device:<device> | ch_name:<channel> | firmware:<firmware> | version:<version> | build_date:<dd-mm-yy>'] | string | List of all available channels on all devices or a single device with relevant information. |
'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)
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'
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. | |
'use_plc_image_functions' | 'false', 'true' | 'false' | string | Flag that activates special PLC image functions on the Hilscher device. This flag is NOT required to be set by most applications. If your PLC program is using its own process data image layout then this function can be activated to save the copy between the device I/O process data image and the local function buffers. For more information please refer to the official Hilscher documentation. Activating this flag changes the behavior of read and write operations. |
GenParamValue | [] | integer, real, string | Parameter values. | |
IOChannelHandle | handle | Handles of the opened I/O channel. |
Operator control_io_channel
control_io_channel(::IOChannelHandle, Action, Argument:Result)
Perform an action on I/O channels.
Parameter | Values | Default | Type | Description |
---|---|---|---|---|
IOChannelHandle | handle | Handles of the opened I/O channels. | ||
Action | string | Name of the action to perform. | ||
'reset_channel' | Reset the channel. It is possible to specify a wait timeout in milliseconds, if no value was specified the default timeout is one second. | |||
Argument | 1000 | |||
Result | 1000 | integer | ||
Argument | [] | integer, real, string | List of arguments for the action. | |
Result | integer, real, string | List of values returned by the action. |
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. | |
'bus_state' | 'on', 'off' | string | The channel bus state. Used for start and stop the channel communication. | |
'config_lock' | 'lock', 'unlock' | string | The channel configuration lock. Once this flag is set to 'lock' the configuration of the channel can't be changed. | |
'control_timeout' | 1000 | integer | Gets or sets the current control timeout in milliseconds. This timeout affects some actions for the communication channel. (Eg. bus_state, host_state, etc.) | |
'dma_mode' | 'on', 'off' | string | This flags is used to change I/O data transfer from DPM to DMA mode. This function is only available for PCI and PCIe devices. | |
'host_state' | 'ready', 'not_ready' | string | The channel host state. | |
'input_conversion_format' | string | Specifies the conversion format from the input data to HALCON types. The provided format must coincide with the current data size specified by input_size and input_offset. Please refer to our documentation section 'Converting the input and output data to HALCON Types' for more information on how to use this feature. | ||
'input_offset' | 0 | integer | The offset on the input data in bytes. | |
'input_size' | 0 | integer | The number of bytes to read from the input data. If set to zero the complete input data minus the input_offset can be read. | |
'operation_timeout' | 500 | integer | The current operation timeout in milliseconds. This timeout only affects read and write on a channel. Note: The device data is updated at most once per bus cycle, calls faster than that will return old data. |
|
'output_conversion_format' | string | Specifies the conversion format from HALCON types to the output data. The provided format must coincide with the current data size specified by output_size and output_offset. Please refer to our documentation section 'Converting the input and output data to HALCON Types' for more information on how to use this feature. | ||
'output_offset' | 0 | integer | The offset on the output data in bytes. | |
'output_size' | 0 | integer | The number of bytes to write to the output data. If set to zero the complete output data minus the input_offset can be written. | |
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. | |
'bus_state' | 'on', 'off' | string | The channel bus state. Used for start and stop the channel communication. |
'channel_error' | integer | The current channel error code. If no errors have occurred or the problem has been solve the return value will be zero. To identify the meaning of the error please 'Error Codes' manual provided by Hilscher. | |
'communication_cos' | 'ready', 'running', 'bus_on', 'dma_mode_on', 'new_config_available', 'restart_required', 'restart_enable', 'config_locked' | string | The communication channel 'Change of State' flag. Every time there is a state change on the current channel or the device this flag will be updated to reflect those changes. This flag reflects general and not time critical information. |
'communication_error' | string | The current communication error code from the channel. If no errors have occurred or the problem has been solve the return value will be zero. To identify the meaning of the error please 'Error Codes' manual provided by Hilscher. | |
'communication_error_count' | integer | The total number of errors since the last device powered up. | |
'communication_state' | 'offline', 'stop', 'idle', 'operate', 'unknown' | string | The current communication state of the channel |
'config_lock' | 'lock', 'unlock' | string | The channel configuration lock. Once this flag is set to 'lock' the configuration of the channel can't be changed. |
'control_timeout' | integer | Gets or sets the current control timeout in milliseconds. This timeout affects some actions for the communication channel. (Eg. bus_state, host_state, etc.) | |
'dma_mode' | 'on', 'off' | string | This flags is used to change I/O data transfer from DPM to DMA mode. This function is only available for PCI and PCIe devices. |
'firmware_name' | string | The firmware of the channel. | |
'host_state' | 'ready', 'not_ready' | string | The channel host state. |
'input_conversion_format' | string | Specifies the conversion format from the input data to HALCON types. The provided format must coincide with the current data size specified by input_size and input_offset. Please refer to our documentation section 'Converting the input and output data to HALCON Types' for more information on how to use this feature. | |
'input_data_size' | integer | The total size of the input data in bytes. Specified on the device configuration. | |
'input_offset' | integer | The offset on the input data in bytes. | |
'input_size' | integer | The number of bytes to read from the input data. If set to zero the complete input data minus the input_offset can be read. | |
'io_channel_info' | [' firmware:<name> | version:<version> | build_date:<dd-mm-yy>'] | string | Information about the firmware of the channel. Including name, version and build date. |
'io_channel_name' | '<channel>' | string | The name of the channel. |
'operation_timeout' | integer | The current operation timeout in milliseconds. This timeout only affects read and write on a channel. Note: The device data is updated at most once per bus cycle, calls faster than that will return old data. |
|
'output_conversion_format' | string | Specifies the conversion format from HALCON types to the output data. The provided format must coincide with the current data size specified by output_size and output_offset. Please refer to our documentation section 'Converting the input and output data to HALCON Types' for more information on how to use this feature. | |
'output_data_size' | integer | The total size of the output data in bytes. Specified on the device configuration. | |
'output_offset' | integer | The offset on the output data in bytes. | |
'output_size' | integer | The number of bytes to write to the output data. If set to zero the complete output data minus the input_offset can be written. | |
'param_name' | '<parameter>'[,'<parameter>'...] | string | Returns the possible parameter names. |
'plc_is_read_ready' | 'false', 'true' | string | If the 'use_plc_image_functions' parameter is set to 'true'. This parameter has to be queried to determine if it is currently possible to read the I/O data. The recommend way to check this parameter is to read it in a loop before calling read_io_channel. |
'plc_is_write_ready' | 'false', 'true' | string | If the 'use_plc_image_functions' parameter is set to 'true'. This parameter has to be queried to determine if it is currently possible to write the I/O data. The recommend way to check this parameter is to read it in a loop before calling write_io_channel. |
'use_plc_image_functions' | 'false', 'true' | string | Flag that activates special PLC image functions on the Hilscher device. This flag is NOT required to be set by most applications. If your PLC program is using its own process data image layout then this function can be activated to save the copy between the device I/O process data image and the local function buffers. For more information please refer to the official Hilscher documentation. Activating this flag changes the behavior of read and write operations. |
GenParamValue | integer, real, string, handle | Parameter values. |
Operator read_io_channel
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.
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.
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)
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.
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.
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:)
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'
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 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.
Release Notes
- Revision 20.11.5 (Aug 2, 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.