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
 

1 Introduction

The Device Access APIs provides interfaces and classes for communicating with and controlling peripheral devices attached to the embedded board. This chapter gives an introduction to the common interfaces and classes that are used throughout the Device Access API packages.


WARNING:

Any IMlet that accesses the Device Access APIs must be digitally signed using a trusted certificate authority, or the appropriate permissions of the Device Access APIs must be added to the policy file for your platform. An IMlet that is not signed or is not granted the appropriate permissions will encounter an authentication error when attempting to access the Device Access APIs. See the Getting Started Guide for your target platform for more information..


Device Access API Permissions

In order to utilize the Device Access APIs, applications must present the proper permissions. These permission must be requested in the application's JAD file under either the MIDlet-Permissions or MIDlet-Permissions-Opt entry and the application must be digitally signed by a trusted authority, or the permission may be granted to all applications by adding it to the untrusted domain of the Java security policy file (policy.txt).

Peripheral devices are registered, un-registered, configured and listed by invoking one of the open(), register(), unregister() and list() methods of PeripheralManager. The four PeripheralManager permissions allow access to be granted for registration, configuration, un-registration and listing of peripheral devices. Note that these permissions must be granted in addition to the permissions granting access to a specific peripheral type. For example, opening a GPIO pin with an ad-hoc configuration requires both the com.oracle.deviceaccess.gpio and com.oracle.deviceaccess.PeripheralManager.configure to be granted. Similarly, registering a GPIO pin with an ad-hoc configuration requires both the com.oracle.deviceaccess.gpio and com.oracle.deviceaccess.PeripheralManager.register to be granted.

Table 1-1 shows the API Permissions that are required in an application's JAD file or security policy file in order to access the various Device Access APIs.

Table 1-1 Device Access API Permissions

Device Access API Description

com.oracle.deviceaccess.PeripheralManager.configure

Ad-hoc configuration of peripheral devices

com.oracle.deviceaccess.PeripheralManager.register

Registration of peripheral devices

com.oracle.deviceaccess.PeripheralManager.unregister

Unregistration of peripheral devices

com.oracle.deviceaccess.PeripheralManager.list

Listing of registered peripheral devices

com.oracle.deviceaccess.adc

Analog-to-Digital Converter (ADC) APIs

com.oracle.deviceaccess.atcmd

Access to AT devices and modems as a whole

com.oracle.deviceaccess.atcmd.ATDevice.openDataConnection

Opening data connections with AT devices

com.oracle.deviceaccess.counter

Pulse counter APIs

com.oracle.deviceaccess.dac

Digital-to-Analog Converter (DAC) APIs

com.oracle.deviceaccess.generic

Generic APIs

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

com.oracle.deviceaccess.i2c

I²C slave devices as a whole

com.oracle.deviceaccess.mmio

Memory-mapped IO devices

com.oracle.deviceaccess.power

Power management functionality

com.oracle.deviceaccess.spi

Serial Peripheral Interface bus devices

com.oracle.deviceaccess.uart

UART devices

com.oracle.deviceaccess.watchdog

Watchdog timers


For individual peripheral mappings, see the appropriate appendix in the Getting Started Guide for your hardware development platform.

The Peripheral Interface

The Peripheral interface provides generic methods for handling any peripheral. All peripherals must implement this interface. There are four constants in the interface.

The interface also has five methods.

The PeripheralConfig Interface

The PeripheralConfig interface is a tagging interface for all peripheral configuration classes. It contains the following elements.

PeripheralConfig instances should be immutable. A compliant implementation of this specification must ensure that information encapsulated in a PeripheralConfig instance cannot be altered while it is being accessed. It should either create its own private copy of the instance, or a copy of the information it contains.

Some hardware addressing parameters, as well as static and dynamic configuration parameters, may be set to PeripheralConfig.DEFAULT. Whether default settings are supported are both platform-dependent as well as peripheral driver-dependent.

An instance of PeripheralConfig can be passed to the PeripheralManager.open(PeripheralConfig) or PeripheralManager.open(Class, PeripheralConfig) method to open the designated peripheral device with the specified configuration. A PeripheralConfigInvalidException is thrown if the user attempts to open a peripheral device with an invalid or unsupported configuration.

The PeripheralConfig interface contains one constant.

The PeripheralEventListener Interface

The PeripheralEventListener interface is a tagging interface that all event listeners must implement. It contains no constants or methods. Event listeners provide methods for notifying applications of the occurrence of events, such as hardware interrupts or software signals, on peripheral devices.

The Transactional Interface

The Transactional interface contains methods for providing a communication transaction. If a Peripheral instance implements this interface, then a transaction will be demarcated by a call to begin() and a call to end(). The read and write operations between these two calls will be part of a single transaction. A peripheral device driver may then use this transaction demarcation to qualify the sequence of read and write operations accordingly. For example, an I2C driver will treat the sequence of read and write operations to the same I2C slave device as a combined message. An SPI driver will treat the sequence of read and write operations to the same SPI slave device as a single transaction and will assert the Slave Select line during the entire transaction.

Note that in order to ensure that the end() method is always invoked, these methods should be used within a try ... finally block:

 try {
      peripheral.begin();
      // read and write operations
 } finally {
      peripheral.end();
 }
 

There are two methods in the Transactional interface:

The PeripheralEvent Class

The PeripheralEvent class encapsulates events fired by or on behalf of a peripheral device. Such an event may correspond to a hardware interrupt or a software signal.

An event burst occurs when more events are fired than can be handled. When this happens, events may be coalesced. Coalescing of events is platform and peripheral-dependent.

The PeripheralEvent class consists of the following fields:

There are several methods in this class, which acts as accessors for the protected fields.

The PeripheralManager Class

The PeripheralManager class provides static methods for opening and registering peripheral devices. These devices can then be handled as Peripheral instances. A Peripheral instance of a particular type can be opened using its platform-specific numerical ID or name as well as its properties.

Peripheral instances are uniquely identified by a numerical ID. This ID is unrelated to the hardware number (hardware addressing information) that may be used to identify a device such as a GPIO pin number or an I2C slave device address. The numerical ID of a peripheral device must be an integer greater than or equal to 0 and must be unique. Yet the same peripheral device may be directly and indirectly mapped through several IDs; each ID may correspond to a different configuration, representation or abstraction for the same underlying peripheral device hardware resource.

The PeripheralManager class consists of the following methods:

Exceptions

The com.oracle.deviceaccess package consists of eight exceptions, which are shown in Table 1-2:

Table 1-2 Exceptions of the com.oracle.deviceaccess Package

Suite Type Description

InvalidOperationException

Thrown by an instance of Peripheral to indicate that an attempted operation is not allowed for the peripheral.

InvalidStateException

Thrown by an instance of Peripheral to indicate that an operation as been attempted at an inappropriate time. In other words, the peripheral device is not in an appropriate state for the requested operation.

PeripheralConfigInvalidException

Thrown to indicate that the provided peripheral configuration is invalid/is not supported.

PeripheralException

Thrown to indicate that a general exception occurred on a peripheral operation.

PeripheralExistsException

Thrown by the PeripheralManager to indicate that a peripheral device is already registered for the specified ID.

PeripheralNotAvailableException

Thrown by an instance of Peripheral to indicate that an operation is attempted on a peripheral which is not yet available.

PeripheralNotFoundException

Thrown to indicate that there is no peripheral matching the provided peripheral numerical ID or name.

PeripheralTypeNotSupportedException

Thrown to indicate permanent unavailability of the looked up peripheral.