MVTec Software GmbH
 

Documentation

Hilscher-cifX / HALCON / MVTec Software GmbH

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

Interface: Hilscher-cifX
Revision: 13.0.2
Date: 2017-11-30

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.

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.

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

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:
  • '.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 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, ParamAction, ParamArgument:GenParamValue)
Perform an action on I/O channels.
Parameter Values Default Type Description
IOChannelHandle handle Handles of the opened I/O channels.
ParamAction 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
ParamArgument [] integer, real, string List of arguments for the action.
GenParamValue 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:
  • '.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.

Parameter Values Type Description
IOChannelHandle handle 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)
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.

Parameter Values Type Description
IOChannelHandle handle 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:)
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 13.0.2 (Nov 30, 2018):
    • First official release.