How to use GPIOs
Eclipse Kura provides a GPIO Service that allows applications to interact with the system’s GPIOs.
GPIO Service
Access to GPIO resources is granted by the GPIOService. Once obtained, this service can be used to list the GPIOs available in the system and to acquire sets or individual GPIO Pins, configuring them either as digital inputs or digital outputs.
To retrieve the list of GPIOs available on the system, this method is provided by the GPIOService:
The KuraGPIODescription class contains a map of GPIO properties (such as name, controller, line, etc.) and provides a human-readable name for the pin through the getDisplayName method.
To acquire one or more GPIO pins, use one of the following methods:
public List<KuraGPIOPin> getPins(Map<String, String> description);
public List<KuraGPIOPin> getPins(Map<String, String> description, KuraGPIODirection direction, KuraGPIOMode mode, KuraGPIOTrigger trigger);
The description map includes the properties used to identify the pin and they are implementation-specific. The second method additionally attempts to configure the pin using the given direction, mode and trigger.
The KuraGPIOPin object is used to manipulate GPIO Pins and exposes methods to read the status of an input, or set the status of digital output as shown below.
//sets digital output value to high
thePin.setValue(true);
//get value of a digital input pin
boolean active = thePin.getValue();
//listen for status change on a digital input pin
try {
thePin.addPinStatusListener(new PinStatusListener() {
@Override
public void pinStatusChange(boolean value) {
// Perform tasks when pin status changes
}
});
} catch (KuraClosedDeviceException e) {
// Here if GPIO cannot be acquired
} catch (IOException e) {
// Here on I/O error
}
Warning
Starting from Kura 6.0.0, the following GPIOService methods have been deprecated: getPinByName, getPinByTerminal and getAvailablePins.
LibGpiod GPIOService implementation
Beginning with Kura 6.0.0, the default GPIOService implementation is based on the LibGpiod linux library. It provides a low-level library, bindings and tools for interacting with the GPIO lines on Linux systems. Both versions 1.6.x and 2.x.x are supported.
Kura implements the GPIOService interface using a JNA wrapper of the LibGpiod C APIs.
The properties used to describe and identify a GPIO are listed below:
- controller: the gpiochip the pin belongs to
- line: the line offset of the pin in the gpiochip
- name: the optional pin name. If not provided, it defaults to "unknown"
- displayName: the pin name used to present the pin, with the default format "name:controller:line"
Applications can use the getAvailablePinDescriptions method to retrieve all the available GPIO descriptions and use it to get the desired KuraGPIOPin or directly fill the properties above and pass the map to the getPins method.
To get the gpiochip, line numbers and names, use the following command that lists all the GPIOS available on the system:
For example, to get the KuraGPIOPin of the gpio with controller 3, line 5 and name "PIN1" use the method below:
Map<String, String> description = new HashMap<>();
description.put("name", "PIN1");
description.put("controller", "3");
description.put("line", "5");
List<KuraGPIOPin> pins = this.gpioService.getPins(description);
If one or more properties (controller, line or name) are omitted, all GPIOs matching the specified criteria are returned. For example, if only the controller property is set, all the GPIOs belonging to that gpiochip are retrieved.
For backward compatibility, the deprecated getPinByTerminal can still be used. In this case, the pin is identified by a numeric value calculated as follows: