1 Introduction

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.

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.

• static final int LITTLE_ENDIAN

  This constant represents little-endian byte or bit ordering.

• static final int BIG_ENDIAN

  This constant represents big-endian byte or bit ordering.

• static final int MIXED_ENDIAN

  This constant represents mixed-endian (non-standard) byte ordering.

• static final int UNIDENTIFIED_ID

  This constant is used to signify an unidentified peripheral numerical ID.

The interface also has five methods.

• void close() throws java.io.IOException

  This method releases the underlying peripheral device, making it available to other applications. Once released, subsequent operations on the same Peripheral instance will throw a PeripheralNotAvailableException. This method has no effects if the peripheral device has been released.

• int getID()

  This method returns the numerical ID of the underlying peripheral device.

• java.lang.String getName()

  This method returns the given name of the underlying peripheral device. A name is a descriptive version of the peripheral ID, such as "LED1" or "BUTTON2".

• java.lang.String[] getProperties()

  This method returns the properties of the peripheral device.

• boolean isOpen()

  This method indicates whether this peripheral is open or available to the calling application.

The PeripheralConfig Interface

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

• Hardware Addressing Information

  Information required to address the peripheral device. Examples are an I2C bus number and slave device address, or a GPIO controller number and pin index.

• Static Configuration Parameters

  Static configuration parameters are configuration parameters that must be set before the peripheral device is opened and may not be changed afterwards. Examples of static configuration parameters are an SPI slave device clock mode or word length.

• Dynamic Configuration Parameters

  Dynamic configuration parameters are configuration parameters for which a default value may be set before the peripheral device is opened, and which may still be changed while the peripheral is open. Dynamic configuration parameters can be changed after the peripheral device is open through methods of the Peripheral sub-interfaces. Examples of dynamic configuration parameters are a UART baud rate or the current direction of a bidirectional GPIO pin.

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.

• static final int DEFAULT

  This constant indicates that the default value of a configuration parameter should be used.

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:

• void begin() throws java.io.IOException, PeripheralNotAvailableException

  Demarcates the beginning of a transaction. This method may throw an InvalidStateException if a transaction is already in progress.

• void end() throws java.io.IOException, PeripheralNotAvailableException

  Demarcates the end of a transaction. This method may throw an InvalidStateException if a transaction is not already in progress.

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:

• protected long timeStamp

  The time (in milliseconds) when this event occurred. If events were coalesced then the time is that of the first event.

• protected long lastTimeStamp

  The time (in milliseconds) when the last coalesced event occurred. If events were not coalesced then the time is the same as that of the first event.

• protected int timeStampMicros

  The additional microseconds to the timestamp for when this event first occurred. If events were coalesced then this is that of the first event. The actual timestamp in microseconds is equal to: (timeStamp * 1000) + timeStampMicros.

• protected int lastTimeStampMicros

  The additional microseconds to the timestamp for when the last coalesced event occurred. If events were not coalesced then this is the same as that of the first event. The actual last timestamp in microseconds is equal to: (lastTimeStamp * 1000) + lastTimeStampMicros

• protected int count

  The number of underlying coalesced hardware interrupts or software signals this event may represent.

• protected Peripheral peripheral

  The Peripheral instance that fired this event or for which this event was fired.

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

• public final long getTimeStamp()

  Returns the time (in milliseconds) when this event first occurred. If events were coalesced then the time is that of the first event.

• public final int getTimeStampMicros()

  Returns the additional microseconds to the timestamp for when this event first occurred. If events were coalesced then the time is that of the first event.

• public final long getLastTimeStamp()

  Returns the time (in milliseconds) when the last coalesced event occurred. If events were not coalesced then the time is the same as that of the first event.

• public final int getLastTimeStampMicros()

  Returns the additional microseconds to the timestamp for when the last coalesced event occurred. If events were not coalesced then this is the same as that of the first event.

• public final int getCount()

  Returns the number of underlying coalesced hardware interrupts or software signals this event may represent.

• public final Peripheral getPeripheral()

  Returns the Peripheral instance that fired this event or for which this event was fired.

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:

• public static int register(int id, java.lang.Class intf, PeripheralConfig config, java.lang.String name, java.lang.String[] properties) throws java.io.IOException, PeripheralConfigInvalidException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, PeripheralNotAvailableException, PeripheralExistsException

  This method registers a new peripheral device under the specified ID (and optionally name and properties) supporting the provided configuration. The designated peripheral may be probed to check if the provided configuration is valid.

• public static void unregister(int id)

  This method unregisters the peripheral device associated with the specified ID. Some peripheral devices are registered by the underlying platform and cannot be unregistered.

• public static Peripheral open(int id) throws java.io.IOException, PeripheralNotFoundException, PeripheralNotAvailableException

  This method looks up and opens a Peripheral instance for the provided numerical ID. A new Peripheral instance is returned upon each call.

• public static Peripheral open(int id, java.lang.Class intf) throws java.io.IOException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, PeripheralNotAvailableException

  This method looks up and opens a Peripheral instance for the provided numerical ID and type. A new Peripheral instance is returned upon each call.

• public static Peripheral open(java.lang.String name, java.lang.Class intf, java.lang.String[] properties) throws java.io.IOException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, PeripheralNotAvailableException

  This method looks up and opens a Peripheral instance for the specified name, type and/or properties. A new Peripheral instance is returned upon each call. Property-based lookup only uses exact (case-insensitive) matching and does not perform any semantic interpretation.

• public static Peripheral open(PeripheralConfig config) throws java.io.IOException, PeripheralConfigInvalidException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, PeripheralNotAvailableException, PeripheralExistsException

  This method opens a Peripheral instance with the specified hardware addressing information and configuration. Note that the returned Peripheral instance's ID and name are undefined. A new instance is returned upon each call.

• public static Peripheral open(java.lang.Class intf, PeripheralConfig config) throws java.io.IOException, PeripheralConfigInvalidException, PeripheralTypeNotSupportedException, PeripheralNotFoundException, PeripheralNotAvailableException, PeripheralExistsException

  This method opens a Peripheral instance of the specified type with the specified hardware addressing information and configuration. Note that the returned Peripheral instance's ID and name are undefined. A new instance is returned upon each call.

• public static Peripheral[] list()

  This method lists all platform- and user-registered peripheral devices. The Peripheral instances returned are in a closed state and a call to Peripheral.isOpen() will return false.

• public static Peripheral[] list(java.lang.Class inf) throws PeripheralTypeNotSupportedException

  This method lists all platform- and user-registered peripheral devices of the designated type. The Peripheral instances returned are in a closed state; a call to Peripheral.isOpen() will return false.

Exceptions

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