Interface Documentation
Linux-GPIO I/O Interface for interacting with the Linux GPIO character device
| Interface: | Linux-GPIO |
| Revision: | 20.11.4 |
| Date: | 2023-08-01 |
- General
- Disclaimer
- System Requirements
- Interface Versioning
- Installation
- Features
- Limitations
- Port naming and mapping to GPIO lines
- Alias names for GPIO lines
- 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
- Usage of third-party libraries
- HDevelop Examples
- Release Notes
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 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.
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:
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, 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. | |
| '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:
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, 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)
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, 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:)
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 third-party libraries
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â.
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 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.