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
 

6 Generic Input/Output Classes

The com.oracle.deviceaccess.generic package contains interfaces and classes for controlling devices using generic I/O operations.

The generic device API allows for accessing peripheral devices when there are no more specific standard Java APIs, such as I2CDevice, SPIDevice, GPIOPin or GPIOPort. This API offers three primary interfaces to encapsulate these devices:

In order to access a device using its generic interface, an application should first open and obtain a GenericDevice instance for the device using its numerical ID, name, type (interface) and properties.

This is an example of using its ID.

GenericDevice device = (GenericDevice) PeripheralManager.open(17);

This is an example of using its name and interface.

GenericStreamIODevice device = (GenericDevice) PeripheralManager.open("STORAGE", GenericStreamIODevice.class, null);
 

Once the peripheral is opened, the application can set and get its controls, as well as read and write data using methods of the GenericDevice, GenericBufferIODevice or GenericStreamIODevice interfaces.

 device.read(buffer, 0, buffer.length);
 

When completed, the application should call the GenericDevice.close() method to release the device.

device.close();

Example 6-1 and Example 6-2 show how to use the generic API to communicate with Real Time Clock device and an audio capture microphone, which may be accessible over USB.

Example 6-1 Creating an Alarm using the Generic APIs

import com.oracle.deviceaccess.PeripheralException;
import com.oracle.deviceaccess.PeripheralManager;
import com.oracle.deviceaccess.generic.GenericDevice;
import com.oracle.deviceaccess.generic.GenericEvent;
import com.oracle.deviceaccess.generic.GenericEventListener;
import java.io.IOException;
 
public class GenericAlarm {
 
    public static final int EVT_ALARM = 0;
    public static final int SECONDS = 0;
    public static final int SEC_ALARM = 1;
    public static final int MINUTES = 2;
    public static final int MIN_ALARM = 3;
    public static final int HR_ALARM = 4;
    public static final int HOURS = 5;
    public static final int ALARM_ENABLED = 6;
    private GenericDevice rtc = null;
 
    // Sets the daily alarm for after some delay
    public void setAlarm(byte delaySeconds, byte delayMinutes, byte delayHours)
        throws IOException, PeripheralException
   {
        rtc = (GenericDevice) PeripheralManager.open("RTC",
              GenericDevice.class, (String[]) null);
        byte currentSeconds = ((Byte) rtc.getControl(SECONDS)).byteValue();
        byte currentMinutes = ((Byte) rtc.getControl(MINUTES)).byteValue();
        byte currentHours = ((Byte) rtc.getControl(HOURS)).byteValue();
        byte i = (byte) ((currentSeconds + delaySeconds) % 60);
        byte j = (byte) ((currentSeconds + delaySeconds) / 60);
        rtc.setControl(SEC_ALARM, new Byte(i));
        i = (byte) ((currentMinutes + delayMinutes + j) % 60);
        j = (byte) ((currentMinutes + delayMinutes + j) / 60);
        rtc.setControl(MIN_ALARM, new Byte(i));
        i = (byte) ((currentHours + delayHours + j) % 24);
        rtc.setControl(HR_ALARM, new Byte(i));
 
        rtc.setEventListener(EVT_ALARM, new GenericEventListener() {
            public void eventDispatched(GenericEvent event) {
                GenericDevice rtc = (GenericDevice) event.getPeripheral();
                // Notify application of alarm
            }
        });
        // Enable alarm.
        rtc.setControl(ALARM_ENABLED, Boolean.TRUE);
    }
 
    public void close() {
        try {
            rtc.close();
        } catch (IOException ex) {
        }
    }
}

Example 6-2 An Audio Capture Using the Generic APIs

import com.oracle.deviceaccess.PeripheralException;
import com.oracle.deviceaccess.PeripheralManager;
import com.oracle.deviceaccess.PeripheralNotAvailableException;
import com.oracle.deviceaccess.generic.GenericBufferIODevice;
import com.oracle.deviceaccess.generic.GenericDevice;
import com.oracle.deviceaccess.generic.GenericEvent;
import com.oracle.deviceaccess.generic.GenericEventListener;
import java.io.IOException;
 
public class GenericAudioCapture {
 
    public static final int EVT_VOLUME_CHANGED = 0;
    public static final int MIC_VOLUME = 0;
    public static final int MIC_SAMPLE_RATE = 1;
    public static final int MIC_AUTOMATIC_GAIN = 2;
    public static final int MIC_MUTE = 3;
 
    public void audioCapture(byte[] buffer, float sampleRate, boolean agc) throws IOException, PeripheralException {
        GenericBufferIODevice mic = null;
        try {
            mic = (GenericBufferIODevice) PeripheralManager
                    .open("MICROPHONE", GenericBufferIODevice.class,
                        (String[]) null);
            mic.setControl(MIC_SAMPLE_RATE, new Float(sampleRate));
            mic.setControl(MIC_AUTOMATIC_GAIN, agc ?
                    Boolean.TRUE : Boolean.FALSE);
            mic.setControl(MIC_MUTE, Boolean.FALSE);
 
            mic.setEventListener(EVT_VOLUME_CHANGED, new GenericEventListener() {
                public void eventDispatched(GenericEvent event) {
                    GenericDevice mic = (GenericDevice) event.getPeripheral();
                    try {
                        float currentVolume = ((Float)
                             mic.getControl(MIC_VOLUME)).floatValue();
                        // ...
                    } catch (IOException ex) {
                        ex.printStackTrace();
                    } catch (PeripheralNotAvailableException ex) {
                        ex.printStackTrace();
                    }
                }
            });
            mic.read(buffer, 0, buffer.length);
        } finally {
            if (mic != null) {
                mic.close();
            }
        }
    }
}

Generic devices are opened by invoking one of the com.oracle.deviceaccess.PeripheralManager.open() methods. The com.oracle.deviceaccess.generic permission allows access to be granted to generic devices as a whole. This permission 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 permission may be allowed for all applications in the untrusted domain of the security policy file (policy.txt).

The GenericBufferIODevice Interface

The GenericBufferIODevice interface defines generic methods for accessing and controlling peripheral devices using read and write operations.

A platform implementer may allow access and control of peripheral devices for which there exist no other more specific APIs through this interface.

The GenericBufferIODevice interface contains three methods.

The GenericDevice Interface

The GenericDevice interface defines methods for setting and getting peripheral device-specific configuration and access (I/O) controls as well as registering event listeners.

An application can use this interface to set and get configuration and access (I/O) controls. A control is identified by a numerical ID and can be set or gotten using the setControl(int, java.lang.Object) and getControl(int) methods. Controls can be used to configured a peripheral device a well as performing basic input/output operations. The list of controls supported by a peripheral device is peripheral-device-specific.

An application can also register an GenericEventListener instance to monitor native events of the designated type fired by the peripheral device. To register a GenericEventListener instance, the application must call the setEventListener(int, GenericEventListener) method. The registered listener can later on be removed by calling the same method with a null listener parameter. Asynchronous notification may not be supported by all devices. An attempt to set a listener on a device which does not supports it will result in an InvalidOperationException being thrown.

A platform implementer may allow through this interface access and control of peripheral devices which do not require byte stream or buffer I/O (read, write) and for which there exist no other more specific API.

The GenericDevice interface consists of three methods:

The GenericEventListener Class

The GenericEventListener interface defines methods for being notified of events fired by peripheral devices that implement the GenericDevice interface. A GenericEventListener can be registered using the GenericDevice.setEventListener(int, GenericEventListener) method.

The GenericEventListener interface consists of one method:

The GenericStreamIODevice Class

The GenericStreamIODevice interface defines generic methods for accessing and controlling peripheral devices capable of working with input and output streams. A platform implementer may allow access and control of peripheral devices for which there exist no other more specific API through this interface.

The GenericStreamIODevice interface consists of two methods:

The GenericEvent Class

The GenericEvent class encapsulates events fired by peripherals that implement the GenericDevice interface.

The GenericEvent interface consists of three constants:

The GenericEvent interface consists of two constructors and one method: