Skip Headers
Oracle® Java ME Embedded Device Access API Guide
Release 3.3
E35134-02
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

7 General Purpose Input/Output (GPIO)

This chapter discusses the interfaces and classes for reading from and writing to the General Purpose Input/Output (GPIO) pins and ports of the embedded device board.

A GPIO pin is a generic pin whose value consists of one of two voltage settings (high or low) and whose behavior can be programmed through software. A GPIO port is a platform-defined grouping of GPIO pins (often 4 or more pins). However, GPIO pins that are part of a GPIO port cannot be retrieved or controlled individually as GPIO pins.

In order to use a specific pin or port, an application should first open and obtain a GPIOPin or GPIOPort instance for the pin or port it wants to use, using its numerical ID, name, type (interface), or properties.

Here is an example of obtaining a GPIOPin and a GPIOPort using its ID:

  GPIOPin pin = (GPIOPin) PeripheralManager.open(1);
  GPIOPort port = (GPIOPort) PeripheralManager.open(0);

Here is an example of using its name and interface:

  GPIOPin pin = (GPIOPin) PeripheralManager.open("LED_PIN", GPIOPin.class, null);
  GPIOPort port = (GPIOPort) PeripheralManager.open("LCD_DATA_PORT",
      GPIOPort.class, null);

Once a pin is opened, an application can obtain the current value of a GPIO pin by calling the GPIOPin.getValue() method and set its value by calling the GPIOPin.setValue(boolean) method. Likewise, once a port opened, an application can obtain the current value of a GPIO port by calling the GPIOPort.getValue() method and set its value by calling the GPIOPort.setValue(int) method.

  pin.setValue(true);
  port.setValue(0xFF);

When done, the application should call the GPIOPin.close() or GPIOPort.close() method to release the pin or port, respectively.

  pin.close();
  port.close();

Example 7-1 gives an demonstration of using the GPIO API. First, it registers a pin listener for the GPIO input pin that a switch button is attached to. When the button is pressed, the listener is notified. The listener then turns the LED on or off by setting the GPIO output pin that the LED is attached to accordingly.

Example 7-1 Using the GPIO APIs

import com.oracle.deviceaccess.PeripheralManager;
import com.oracle.deviceaccess.PeripheralNotAvailableException;
import com.oracle.deviceaccess.PeripheralNotFoundException;
import com.oracle.deviceaccess.gpio.GPIOPin;
import com.oracle.deviceaccess.gpio.PinEvent;
import com.oracle.deviceaccess.gpio.PinListener;
import java.io.IOException;
 
public class GPIODemo {
 
    GPIOPin switchPin = null;
    GPIOPin ledPin = null;
 
    public GPIODemo() {
        try {
            switchPin = (GPIOPin) PeripheralManager.open(1);
            ledPin = (GPIOPin) PeripheralManager.open(3);
            switchPin.setInputListener(new PinListener() {
                public void valueChanged(PinEvent event) {
                    try {
                        ((GPIOPin) event.getPeripheral()).
                            setValue(event.getValue()); // turn LED on or off
                    } catch (IOException ex) {
                        // Ignored
                    } catch (PeripheralNotAvailableException ex) {
                        // Ignored
                    }
                }
            });
        } catch (IOException ex) {
            // Handle exception
        } catch (PeripheralNotFoundException ex) {
            // Handle exception
        } catch (PeripheralNotAvailableException ex) {
            // Handle exception
        } finally {
            if (switchPin != null) {
                try {
                    switchPin.close();
                } catch (IOException ex) {
                }
            }
            if (ledPin != null) {
                try {
                    ledPin.close();
                } catch (IOException ex) {
                }
            }
        }
    }
}

Note that the underlying platform configuration may allow for some GPIO pins or 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. Note also that asynchronous notification of pin or port value changes is only loosely tied to hardware-level interrupt requests. The platform does not guarantee notification in a deterministic or timely manner.

Because of performance issue, procedures handling GPIO pins, and especially event listeners, should be implemented to be as fast as possible.

GPIO pins and ports are opened by invoking one of the com.oracle.deviceaccess.PeripheralManager.open() methods. The permissions in Table 7-1 allow access to be granted to GPIO pins and ports. as a whole as well as to some of their protected functions. These permissions must be requested in the JAD file under MIDlet-Permissions or MIDlet-Permissions-Opt, and the application must be digitally signed by a trusted authority to gain access to the APIs. Alternatively, the permissions may be allowed for all applications in the untrusted domain of the security policy file (policy.txt).

Table 7-1 GPIO API Permissions

Permission Description

com.oracle.deviceaccess.gpio

Access to GPIO pins and ports (as a whole)

com.oracle.deviceaccess.gpio.GPIOPin.setDirection

Changing the direction of a GPIO pin

com.oracle.deviceaccess.gpio.GPIOPort.setDirection

Changing the direction of a GPIO port


The GPIOPin Interface

The GPIOPin interface provides methods for controlling a GPIO pin. A GPIO pin can be configured for output or input. Output pins are both writable and readable while input pins are only readable. The interface contains two constants, as shown in Table 7-2:

Table 7-2 GPIOPin Direction Constants

Constant Description

GPIOPin.INPUT

The GPIO pin is configured for input and is only readable.

GPIOPin.OUTPUT

The GPIO pin is configured for output and is both readable and writable.


Each GPIO pin is identified by a numerical ID and by a name. A GPIOPin instance can be opened by a call to one of the PeripheralManager.open() methods. 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 be 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 pins configured for input. An attempt to set a listener on a GPIO pin configured for output will throw an InvalidOperationException.

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

The initial direction of a GPIO pin which may be used for output or input. 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 or timely manner.

The GPIOPin interface consists of the following methods:

The GPIOPort Interface

The GPIOPort interface provides methods for controlling a GPIO port. A GPIO port is a platform-defined grouping of GPIO pins that can be configured for output or input. Like GPIO pins, each GPIO port is identified by a numerical ID and by a name. Output ports are both writable and readable while input ports are only readable. GPIO pins that are part of a GPIO port cannot be retrieved or controlled as individual GPIOPin instances.

The GPIOPort interface contains two constants, as shown in Table 7-3:

Table 7-3 GPIOPort Direction Constants

Constant Description

GPIOPort.INPUT

The GPIO port is configured for input, and is only readable.

GPIOPort.OUTPUT

The GPIO port is configured for output, and is both readable and writable.


A GPIOPort instance can be opened by a call to one of the PeripheralManager.open() methods. 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(int) method. A GPIO port has a minimum and 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 throw an IllegalArgumentException.

An application can either monitor a GPIO port value changes using polling or can register a PortListener instance, which will be asynchronously notified of any value changes. To register a PortListener instance, the application must call the setInputListener(PortListener) 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 throw an InvalidOperationException.

When an application is no longer using a GPIO port, it should call the GPIOPort.close() method to release the GPIO port. Any further attempt to set or get the value of a GPIO port which has been closed will throw a PeripheralNotAvailableException.

The initial direction of a GPIO port which may be used for output or input. 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.

Note that the 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. Note also that asynchronous notification of port value changes is only loosely tied to hardware-level interrupt requests. The platform does not guarantee notification in a deterministic or timely manner.

The GPIOPort interface consists of the following methods:

The PinListener Interface

The PinListener interface provides a means of notification if a GPIO pin value changes. A PinListener can be registered using the GPIOPin.setInputListener(com.oracle.deviceaccess.gpio.PinListener) method.

The interface consists of only one method, void valueChanged(PinEvent event), which is invoked when a GPIO pin's value has changed.

The PortListener Interface

The PortListener interface provides a means of notification if a GPIO port value changes. A PortListener can be registered using the GPIOPort.setInputListener(com.oracle.deviceaccess.gpio.PortListener) method.

The interface consists of only one method, void valueChanged(PortEvent event), which is invoked when a GPIO port's value has changed.

The GPIOPinConfig Class

The GPIOPinConfig class encapsulates the configuration parameters of a GPIO pin. An instance of GPIOPinConfig can be passed to the PeripheralManager.open(PeripheralConfig) method to open the designated GPIO pin with the specified configuration.

The GPIOPinConfig class consists of several constants. The first four represent possible directions for the GPIO pin, and are shown inTable 7-4.

Table 7-4 Direction Constants in the GPIOPinConfig Class

Constant Description

DIR_INPUT_ONLY

Input direction

DIR_OUTPUT_ONLY

Output direction

DIR_BOTH_INIT_INPUT

Bidirectional with initial input direction.

DIR_BOTH_INIT_OUTPUT

Bidirectional with initial output direction.


The next four are possible values for the mode, and are shown in Table 7-5. Note that the mode can also be PeripheralConfig.DEFAULT.

Table 7-5 Mode Constants in the GPIOPinConfig Class

Constant Description

MODE_INPUT_PULL_UP

Input pull-up drive mode.

MODE_INPUT_PULL_DOWN

Input pull-down drive mode.

MODE_OUTPUT_PUSH_PULL

Output push-pull drive mode.

MODE_OUTPUT_OPEN_DRAIN

Output open-drain drive mode.


Finally, the last seven are possible values for the trigger, and are shown in Table 7-6.

Table 7-6 Trigger Constants in the GPIOPinConfig Class

Constant Description

TRIGGER_NONE

No interrupt trigger.

TRIGGER_FALLING_EDGE

Falling edge trigger.

TRIGGER_RISING_EDGE

Rising edge trigger.

TRIGGER_BOTH_EDGES

Both edges trigger.

TRIGGER_HIGH_LEVEL

High level trigger.

TRIGGER_LOW_LEVEL

Low level trigger.

TRIGGER_BOTH_LEVELS

Both levels trigger.


The GPIOPinConfig class consists of one constructor and six methods:

The GPIOPortConfig Class

The GPIOPortConfig class encapsulates the configuration parameters of a GPIO port. An instance of GPIOPortConfig can be passed to the PeripheralManager.open(PeripheralConfig) method to open the designated GPIO port with the specified configuration. Note that the interrupt trigger of a GPIO port is defined by the interrupt triggers configured for its pins. For more information, see GPIOPinConfig.getTrigger().

The GPIOPortConfig class contains four constants, representative of the direction of the port. The constants are shown in Table 7-7.

Table 7-7 Direction Constants in the GPIOPortConfig Class

Constant Description

DIR_INPUT_ONLY

Input port direction.

DIR_OUTPUT_ONLY

Output port direction.

DIR_BOTH_INIT_INPUT

Bidirectional port direction with initial input direction.

DIR_BOTH_INIT_OUTPUT

Bidirectional port direction with initial output direction.


The GPIOPortConfig class consists of one constructor and three methods:

The PinEvent Class

The PinEvent class encapsulates GPIO pin value changes. If value change events for the same GPIO pin are coalesced, the value returned is that of the last occurrence. The class consists of two constructors and one accessor.

The PortEvent Class

The PortEvent class encapsulates GPIO port value changes. If value change events for the same GPIO port are coalesced, the value returned is that of the last occurrence.