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.
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 |
---|---|
|
Ad-hoc configuration of peripheral devices |
|
Registration of peripheral devices |
|
Unregistration of peripheral devices |
|
Listing of registered peripheral devices |
|
Analog-to-Digital Converter (ADC) APIs |
|
Access to AT devices and modems as a whole |
|
Opening data connections with AT devices |
|
Pulse counter APIs |
|
Digital-to-Analog Converter (DAC) APIs |
|
Generic APIs |
|
Access to GPIO pins and ports as a whole |
|
Changing the direction of a GPIO pin |
|
Changing the direction of a GPIO port |
|
I²C slave devices as a whole |
|
Memory-mapped IO devices |
|
Power management functionality |
|
Serial Peripheral Interface bus devices |
|
UART devices |
|
Watchdog timers |
For individual peripheral mappings, see the appropriate appendix in the Getting Started Guide for your hardware development platform.
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.
This constant represents big-endian byte or bit ordering.
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.
This method returns the numerical ID of the underlying peripheral device.
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.
This method indicates whether this peripheral is open or available to the calling application.
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.
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 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 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:
The time (in milliseconds) when this event occurred. If events were coalesced then the time is that of the first event.
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.
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
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.
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 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
.
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