jdk.dio.gpio

Interface GPIOPort

All Superinterfaces:

java.lang.AutoCloseable, java.nio.channels.Channel, java.io.Closeable, Device<GPIOPort>

public interface GPIOPort
extends Device<GPIOPort>

The GPIOPort interface provides methods for controlling a GPIO port.

Each GPIO port is identified by a numeric ID and optionally by a name.

A GPIO port is a platform-defined or an ad-hoc grouping of GPIO pins that may be configured for output or input. Output ports are both writable and readable while input ports are only readable. Whether GPIO pins that are part of a platform-defined GPIO port can be retrieved and controlled individually as GPIOPin instances depends on the hardware and platform configuration (and especially whether the GPIO pins can be shared through different abstractions).

A GPIO port may be identified by the numeric ID and by the name (if any defined) that correspond to its registered configuration. A GPIOPort instance can be opened by a call to one of the DeviceManager.open(id,...) methods using its ID or by a call to one of the DeviceManager.open(name,...) methods using its name. When a GPIOPort instance is opened with an ad-hoc GPIOPortConfig configuration (which includes its hardware addressing information) using one of the DeviceManager.open(config,...) methods it is not assigned any ID nor name.

Once opened, an application can obtain the current value of a GPIO port by calling the getValue method and set its value by calling the setValue method.
A GPIO port has a minimum/maximum value range. The minimum value is zero. An application can check the maximum value by calling getMaxValue method. An attempt to set a GPIO port with a value that exceeds its maximum range value will result in an IllegalArgumentException being thrown.

An application can either monitor a GPIO port value changes using polling or can register a PortListener instance which will get asynchronously notified of any value changes. To register a PortListener instance, the application must call the setInputListener method. The registered listener can later on be removed by calling the same method with a null listener parameter. Asynchronous notification is only supported for GPIO port configured for input. An attempt to set a listener on a GPIO port configured for output will result in an UnsupportedOperationException being thrown.

When an application is no longer using a GPIO port it should call the close method to close the GPIO port. Any further attempt to set or get the value of a GPIO port which has been closed will result in a ClosedDeviceException been thrown.

The initial direction of a GPIO port which may be used for output or input as well as the initial value of a GPIO port set for output is configuration-specific. An application should always initially set the GPIO port's direction; or first query the GPIO port's direction then set it if necessary.

The underlying platform configuration may allow for some GPIO ports to be set by an application for either output or input while others may be used for input only or output only and their direction cannot be changed by an application. Asynchronous notification of port value changes is only loosely tied to hardware-level interrupt requests. The platform does not guarantee notification in a deterministic/timely manner.

Permission Requirement For Ad Hoc GPIO Ports

Opening a GPIOPort instance with an ad-hoc configuration is subject to GPIOPortPermission.OPEN permission checks.
When opening an instance of GPIOPort defined as an ad-hoc grouping of GPIO pins the target of the GPIOPortPermission.OPEN permissions designate the controller or controllers of the GPIO pins that compose the port; therefore if a GPIO port is composed with pins from different controllers then the GPIOPortPermission.OPEN permissions for each of these controllers has to be granted. Opening such an ad-hoc grouping of GPIO pins is, in addition, subject to GPIOPinPermission.OPEN permission checks on all the GPIO pins that compose the port.

Opening a GPIOPort with the following ad hoc sample configuration:

 GPIOPinConfig.Builder builder = new GPIOPinConfig.Builder()
     .setDirection(GPIOPinConfig.DIR_OUTPUT_ONLY)
     .setDriveMode(GPIOPinConfig.MODE_OUTPUT_PUSH_PULL);
 GPIOPortConfig config = new GPIOPortConfig(GPIOPortConfig.DIR_OUTPUT_ONLY, 0x0,
      builder.setControllerNumber(1).setPinNumber(0).build(),
      builder.setControllerNumber(4).setPinNumber(7).build()
 );
 

requires the following permissions to be granted:

 GPIOPortPermission("1", "open")
 GPIOPortPermission("4", "open")
 GPIOPinPermission("1:0", "open")
 GPIOPinPermission("4:7", "open")
 

Since:

1.0

See Also:

PortListener, GPIOPortPermission, GPIOPinPermission

Field Summary

Fields

Modifier and Type	Field and Description
static int	INPUT Input port direction.
static int	OUTPUT Output port direction.

Fields inherited from interface jdk.dio.Device

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN

Method Summary

Methods

Modifier and Type	Method and Description
int	getDirection() Returns the current direction of this GPIO port.
int	getMaxValue() Returns the maximum value of this GPIO port.
GPIOPin[]	getPins() Gets the pins composing the port (in the exact same order they compose the port).
int	getValue() Returns the current value of this GPIO port.
void	setDirection(int direction) Sets this GPIO port for output or input.
void	setInputListener(PortListener listener) Registers a PortListener instance which will get asynchronously notified when this GPIO port's value changes and according to its trigger mode.
void	setValue(int value) Sets the value of this GPIO port.

Methods inherited from interface jdk.dio.Device

close, getByteOrder, getDescriptor, isOpen, tryLock, unlock

Field Detail

INPUT

static final int INPUT

Input port direction.

See Also:

Constant Field Values

OUTPUT

static final int OUTPUT

Output port direction.

See Also:

Constant Field Values

Method Detail

getDirection

int getDirection()
                 throws java.io.IOException,
                        UnavailableDeviceException,
                        ClosedDeviceException

Returns the current direction of this GPIO port. If the direction was not set previously using setDirection the device configuration-specific default value is returned.

Returns:

OUTPUT if this GPIO port is currently set as output; INPUT otherwise (the GPIO port is set as input).

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

getMaxValue

int getMaxValue()
                throws java.io.IOException,
                       UnavailableDeviceException,
                       ClosedDeviceException

Returns the maximum value of this GPIO port. The value returned should be interpreted as an unsigned 32-bit integer.

Returns:

the maximum value this GPIO port can handle.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

getValue

int getValue()
             throws java.io.IOException,
                    UnavailableDeviceException,
                    ClosedDeviceException

Returns the current value of this GPIO port. The value returned should be interpreted as an unsigned 32-bit integer. If the value was not set previously using setValue the device configuration-specific default value is returned.

This method can be called on both output and input ports.

Returns:

the current value of this GPIO port.

Throws:

java.io.IOException - if an I/O error occurred such as the port is not readable.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

setDirection

void setDirection(int direction)
                  throws java.io.IOException,
                         UnavailableDeviceException,
                         ClosedDeviceException

Sets this GPIO port for output or input. The direction can only be set to INPUT if the GPIO port is configured for input-only (see GPIOPortConfig.DIR_INPUT_ONLY) or is configured as bidirectional (see GPIOPortConfig.DIR_BOTH_INIT_INPUT and GPIOPortConfig.DIR_BOTH_INIT_OUTPUT). The direction can only be set to OUTPUT if the GPIO pin is configured for output-only (see GPIOPortConfig.DIR_OUTPUT_ONLY) or is configured as bidirectional (see GPIOPortConfig.DIR_BOTH_INIT_INPUT and GPIOPortConfig.DIR_BOTH_INIT_OUTPUT).

Parameters:

direction - OUTPUT for output; INPUT for input.

Throws:

java.lang.IllegalArgumentException - if direction is not equal to OUTPUT or INPUT.

java.lang.UnsupportedOperationException - if this GPIO port cannot be configured for the desired direction.

java.lang.SecurityException - if the caller does not have the required permission.

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

setInputListener

void setInputListener(PortListener listener)
                      throws java.io.IOException,
                             ClosedDeviceException

Registers a PortListener instance which will get asynchronously notified when this GPIO port's value changes and according to its trigger mode. Notification will automatically begin after registration completes.

A listener can only be registered for a GPIO port currently configured for input.

If this GPIOPort is open in DeviceManager.SHARED access mode and if this GPIOPort is currently configured for input, the listeners registered by all the applications sharing the underlying GPIO port will get notified when its value changes.

If listener is null then the previously registered listener is removed.

Only one listener can be registered at a particular time.

Parameters:

listener - the PortListener instance to be notified when this GPIO port's value changes.

Throws:

java.io.IOException - if some other I/O error occurs.

java.lang.UnsupportedOperationException - if this GPIO port is currently configured for output.

java.lang.IllegalStateException - if listener is not null and a listener is already registered.

ClosedDeviceException - if the device has been closed.

setValue

void setValue(int value)
              throws java.io.IOException,
                     UnavailableDeviceException,
                     ClosedDeviceException

Sets the value of this GPIO port. The value passed should be interpreted as an unsigned 32-bit integer.

An attempt to set the value on a GPIO port currently configured for input will result in a UnsupportedOperationException being thrown.

Parameters:

value - the new port value.

Throws:

java.lang.IllegalArgumentException - if the new value exceeds this GPIO port's maximum value.

java.lang.UnsupportedOperationException - if trying to set the value for a port configured for input.

java.io.IOException - if an I/O error occurred such as the port is not writable.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

getPins

GPIOPin[] getPins()

Gets the pins composing the port (in the exact same order they compose the port).

A concurrent runtime change of the dynamic configuration parameters of any of the pins composing the port (such as of its direction) may result in IOException being thrown by port operations.

Returns:

the pins composing the port (a defensive copy is returned); or null if the composing pins cannot be individually retrieved.

Since:

1.1