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.

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.

• 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 third-party library libgpiod.so.2. If you have properly installed the interface, the shared objects should reside in lib/$HALCONARCH, and the third-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.

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:

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

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

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

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.

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.

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.

Not supported by this interface.

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)

Open and configure I/O channels.

Not supported by this interface.

Not supported by this interface.

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)

Read a value from the specified I/O channels.

write_io_channel(::IOChannelHandle, Value:Status)

Write a value to the specified I/O channels.

close_io_channel(::IOChannelHandle:)

Close I/O channels.

close_io_device(::IODeviceHandle:)

Close the specified I/O device.

This interface depends on third-party libraries. See the file third_party_linux-gpio.txt in the HALCON base directory for copyright and license information. Libraries are used without modifications unless explicitly stated in the file.

You can request the source for those third-party libraries licensed under GPL or LGPL via email to info@mvtec.com with the subject “Request source code of third-party libraries”.

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.

• Revision 20.11.4 (Aug 1, 2023):
  • third_party_linux-gpio.txt now contains links to the corresponding software location. See also Usage of third-party libraries.
• 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.