com.oracle.deviceaccess.gpio

Interface GPIOPin

All Superinterfaces:

java.lang.AutoCloseable, java.nio.channels.Channel, java.io.Closeable, Peripheral<GPIOPin>

public interface GPIOPin
extends Peripheral<GPIOPin>

The GPIOPin interface provides methods for controlling a GPIO pin.

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

A GPIO pin may be configured for output or input. Output pins are both writable and readable while input pins are only readable.

Once opened, an application can obtain the current value of a GPIO pin by calling the getValue() method and set its value by calling the setValue(boolean) method.

An application can either monitor a GPIO pin value changes using polling or can register a PinListener instance which will get asynchronously notified of any pin value changes. To register a PinListener instance, the application must call the setInputListener(PinListener) 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 pin configured for input. An attempt to set a listener on a GPIO pin configured for output will result in an UnsupportedOperationException being thrown.

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

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

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

See Also:

PinListener, GPIOPinPermission

Field Summary

Fields

Modifier and Type	Field and Description
static int	INPUT Input port direction.
static int	OUTPUT Output port direction.
static int	TRIGGER_BOTH_EDGES Rising edge trigger.
static int	TRIGGER_BOTH_LEVELS Both levels trigger.
static int	TRIGGER_FALLING_EDGE Falling edge trigger.
static int	TRIGGER_HIGH_LEVEL High level trigger.
static int	TRIGGER_LOW_LEVEL Low level trigger.
static int	TRIGGER_NONE No interrupt trigger.
static int	TRIGGER_RISING_EDGE Rising edge trigger.

Fields inherited from interface com.oracle.deviceaccess.Peripheral

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN

Method Summary

Methods

Modifier and Type	Method and Description
int	getDirection() Returns the current direction of this GPIO pin.
int	getTrigger() Returns the current pin interrupt trigger.
boolean	getValue() Returns the current value of this GPIO pin.
void	setDirection(int direction) Sets this GPIO pin for output or input.
void	setInputListener(PinListener listener) Registers a PinListener instance which will get asynchronously notified when this GPIO pin's value changes and according to the current trigger mode (see getTrigger()).
void	setTrigger(int trigger) Sets this GPIO pin trigger mode.
void	setValue(boolean value) Sets the value of this GPIO pin.

Methods inherited from interface com.oracle.deviceaccess.Peripheral

close, 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

TRIGGER_BOTH_EDGES

static final int TRIGGER_BOTH_EDGES

Rising edge trigger.

See Also:

Constant Field Values

TRIGGER_BOTH_LEVELS

static final int TRIGGER_BOTH_LEVELS

Both levels trigger.

See Also:

Constant Field Values

TRIGGER_FALLING_EDGE

static final int TRIGGER_FALLING_EDGE

Falling edge trigger.

See Also:

Constant Field Values

TRIGGER_HIGH_LEVEL

static final int TRIGGER_HIGH_LEVEL

High level trigger.

See Also:

Constant Field Values

TRIGGER_LOW_LEVEL

static final int TRIGGER_LOW_LEVEL

Low level trigger.

See Also:

Constant Field Values

TRIGGER_NONE

static final int TRIGGER_NONE

No interrupt trigger.

See Also:

Constant Field Values

TRIGGER_RISING_EDGE

static final int TRIGGER_RISING_EDGE

Rising edge trigger.

See Also:

Constant Field Values

Method Detail

getDirection

int getDirection()
                 throws java.io.IOException,
                        UnavailablePeripheralException,
                        ClosedPeripheralException

Returns the current direction of this GPIO pin. If the direction was not set previously using setDirection(int) the peripheral configuration-specific default value is returned.

Returns:

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

Throws:

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

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.

getTrigger

int getTrigger()
               throws java.io.IOException,
                      UnavailablePeripheralException,
                      ClosedPeripheralException

Returns the current pin interrupt trigger. If the trigger mode was not set previously using setTrigger(int) the peripheral configuration-specific default value is returned. Note that setting the trigger mode to TRIGGER_NONE disables the notification of the PinListener instance (see setInputListener(PinListener) without unregistering it.

Returns:

the current pin interrupt trigger, one of: TRIGGER_NONE, TRIGGER_FALLING_EDGE, TRIGGER_RISING_EDGE, TRIGGER_BOTH_EDGES, TRIGGER_HIGH_LEVEL, TRIGGER_LOW_LEVEL, TRIGGER_BOTH_LEVELS.

Throws:

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

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.

getValue

boolean getValue()
                 throws java.io.IOException,
                        UnavailablePeripheralException,
                        ClosedPeripheralException

Returns the current value of this GPIO pin. If the value was not set previously using setValue(boolean) the peripheral configuration-specific default value is returned.

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

Returns:

true if this pin is currently high.

Throws:

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

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.

setDirection

void setDirection(int direction)
                  throws java.io.IOException,
                         UnavailablePeripheralException,
                         ClosedPeripheralException

Sets this GPIO pin for output or input.

An attempt to set the direction of a GPIO pin to a value that is not supported by the platform configuration will result in a UnsupportedOperationException being thrown.

Parameters:

direction - OUTPUT for output; INPUT for input.

Throws:

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

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

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

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

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.

setTrigger

void setTrigger(int trigger)
                throws java.io.IOException,
                       UnavailablePeripheralException,
                       ClosedPeripheralException

Sets this GPIO pin trigger mode.

Parameters:

trigger - the interrupt trigger events, one of: TRIGGER_NONE, TRIGGER_FALLING_EDGE, TRIGGER_RISING_EDGE, TRIGGER_BOTH_EDGES, TRIGGER_HIGH_LEVEL, TRIGGER_LOW_LEVEL, TRIGGER_BOTH_LEVELS.

Throws:

java.io.IOException - if an IO error occurred.

java.lang.UnsupportedOperationException - if this GPIO pin cannot be configured with the desired trigger mode.

java.lang.IllegalArgumentException - if trigger is not one of the defined values.

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

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.

setInputListener

void setInputListener(PinListener listener)
                      throws java.io.IOException,
                             UnavailablePeripheralException,
                             ClosedPeripheralException

Registers a PinListener instance which will get asynchronously notified when this GPIO pin's value changes and according to the current trigger mode (see getTrigger()). Notification will automatically begin after registration completes.

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

If listener is null or if the pin's direction is changed from input to output then the previously registered listener is removed.

Only one listener can be registered at a particular time.

Parameters:

listener - the PinListener instance to be notified when this GPIO pin's value changes.

Throws:

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

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

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

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.

setValue

void setValue(boolean value)
              throws java.io.IOException,
                     UnavailablePeripheralException,
                     ClosedPeripheralException

Sets the value of this GPIO pin.

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

Parameters:

value - the new pin value: true for high, false for low.

Throws:

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

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

UnavailablePeripheralException - if this peripheral is not currently available - such as it is locked by another application.

ClosedPeripheralException - if the peripheral has been closed.