MVTec header with diamond

Interface Documentation

Linux-GPIO I/O Interface for interacting with the Linux GPIO character device

Interface: Linux-GPIO
Revision: 18.11.3
Date: 2021-10-20

General

This page provides the documentation of the HALCON Linux-GPIO interface for accessing GPIO lines on hardware running Linux. 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.

Disclaimer

Only a subset of the GPIO lines may be attached to accessible pins broken out of the hardware. GPIO lines can also be connected to peripheral devices directly on the board. Opening and writing values to the wrong lines may damage such peripheral devices and/or the board. It is the users responsibility to check in the data sheets of the used hardware which lines are safe to use.

System Requirements

  • Linux single board computer with architecture armv7a or aarch64.
  • Linux kernel version 4.8 (or higher).
  • HALCON I/O device interface hioLinux-GPIO.so or hioLinux-GPIOxl.so, respectively. Also required is the 3rd party library libgpiod.so.2. If you have properly installed the interface, the shared objects should reside in lib/$HALCONARCH, and the 3rd party shared libraries in lib/$HALCONARCH/thirdparty within the HALCON base directory $HALCONROOT you have chosen during the installation of HALCON.
  • The Linux user must have read and write access to the gpiochip devices. Those are represented by files inside the /dev folder, for example /dev/gpiochip0, /dev/gpiochip1 and so on.

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 multiple Linux GPIO lines as input or output.
  • Reading and writing linux GPIO line values.
  • Accessing the lines via their alias name, if your Linux distribution includes this information for your hardware.

Limitations

  • The interface does not support port functionality, i.e., opening multiple channels at once by using 'di_0' as channel name.
  • The interface does not support events, i.e., getting notified on a rising or falling edge on a line.

Port naming and mapping to GPIO lines

Linux organizes GPIO functionality into chips and lines. Every hardware running Linux can have multiple GPIO chips. Those chips are represented by devices inside the /dev folder (e.g. gpiochip0, gpiochip1, etc.). Every GPIO chip can have multiple lines. Each line can be used as either input or output. HALCON I/O devices represent pins on the physical I/O device as channels, which can be grouped into ports. This information is encoded in the name of the channel. For example the channel do_0.0 represents the first pin of the first port, and it is an output pin. The channel di_1.1 represents the second pin of the second port, and it is an input pin. For the Linux GPIO interface we map the chip number to the port number, and the line number to the pin number. Additionally for each GPIO line, the interface provides two channels, one input channel and one output channel. This means di_1.1 is the second line of the second gpiochip, configured as input. do_0.0 is the first line of the first gpiochip, configured as output. Reconfiguring the line direction while the channel is opened is not supported. To change the line direction first close the do_0.0 channel and afterwards open the di_0.0 channel.

Alias names for GPIO lines

To the Linux kernel all GPIO lines are equal, this means the kernel does not know what peripheral devices might be connected to a line. The kernel does not know if the line is broken out of the mainboard or single board computer as a physicall pin that the end user can access. However, your Linux distribution can assign names to the lines which provide information about them. The Linux-GPIO interface allows to query the alias names. Please refer to the channel parameter 'channel_alias' and the device parameter 'alias_names'. The alias name can also be used directly as input to open_io_channel. In this case the generic parameter 'direction' can be used to configure the line as input or output. If no value is given, the default direction is input. Per default this interface only allows access to named lines. This means there can be gaps in the channel names (next input after di_1.10 is di_1.25 for example). To enable access to all lines, use the generic parameter 'all_channels' when opening the device. When using this option it is the users responsibility to check wether or not opening a line may have undesired side effects.

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 'Linux-GPIO' string HALCON I/O interface name.
Query string Parameter name of the query.
     'io_device_info' ['device:<device> | chips:<chip count> | lines:<line count> | named_lines:<named line count> status:<device status>'] string Returns a list of available devices with additional information about the number of channels and the device status ('available', 'no_access').
     'io_device_names' '<name>' string Returns a 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 'Linux-GPIO' [] string HALCON I/O interface name.
IODeviceName [] string I/O device name.
GenParamName [] string Dynamic parameter names.
     'all_channels' 'enable', 'disable' 'disable' string Allows to access all GPIO pins known to the operating system. Per default this feature is disabled, which means only named pins will be accessible.
     'application_identifier' 'HALCON' string The operating system will make this string available for other applications to query who is using a gpio line.
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.
     'all_channels' 'enable', 'disable' string Allows to access all GPIO pins known to the operating system. Per default this feature is disabled, which means only named pins will be accessible.
     'application_identifier' string The operating system will make this string available for other applications to query who is using a gpio line.
     'io_device_name' '<name>' string Returns the name of the device.
     'param_name' '<parameter>'[,'<parameter>'...] string Returns the possible parameter names.
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.
     'alias_names' '<name>' string Returns a list of channel alias names which are assigned by the operating system. This is useful for identifying specific pins which may be labeled on the hardware or mentioned in the manual of your board. This list allows to map the alias name to the HALCON I/O interface standard name. Channels without an alias name have an empty string in this position of the tuple. It also possible that there are no alias names assigned at all.
     'channel_alias' string Returns the alias name for the gpio line, or an empty string if no name is assigned.
     'channel_type' 'digital_input', 'digital_output' string Returns the type of a channel.
     'consumer' string Returns information about who is owning the line.
     'io_channel_names' '<name>' string Returns a list of channels provided by the device, e.g., 'di_0.2' describes input port channel 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).
     'is_used' <true|false> string Returns true or false, indicating if the gpio line is owned by a different process and therefore can not be opened.
     '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.
     'direction' 'input', 'output' 'input' string Specifies if the gpio line should be configured as input or as output.
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

Not supported by this interface.

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_alias' string Returns the alias name for the gpio line, or an empty string if no name is assigned.
     'channel_type' 'digital_input', 'digital_output' string Returns the type of a channel.
     'consumer' string Returns information about who is owning the line.
     'io_channel_name' '<name>' string Returns the name of the channel.
     'is_used' <true|false> string Returns true or false, indicating if the gpio line is owned by a different process and therefore can not be opened.
     'param_name' '<parameter>'[,'<parameter>'...] string Returns the possible parameter names.
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 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 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.

Usage of 3rd party libraries

This interface depends on the following 3rd party libraries. See the file third_party_linux-gpio.txt in the HALCON base directory for copyright and license information.

HDevelop Examples

For this interface the following examples are available:
  • linux-gpio_digital_read.hdev - Example to show how to read values from a GPIO line.
  • linux-gpio_digital_write.hdev - Example to show how to write values to a GPIO line.
  • linux-gpio_list_channels.hdev - Example to enumerate channels and their parameters.

Release Notes

  • Revision 18.11.3 (Oct 20, 2021):
    • The distribution package of this interface now contains files providing meta information for the HDevelop example browser.
  • Revision 18.11.2 (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.1 (Feb 1, 2020):
    • First official release.