The com.oracle.deviceaccess.adc
package contains interfaces and classes for reading analog inputs using an Analog-to-Digital Converter (ADC). An ADC converts a continuous physical input quantity, such as a voltage, to a digital number. The conversion involves quantization of the input, so it typically introduces a small amount of error.
One ADC converter can have several channels. Each channel can sample a continuous input voltage and convert it to a numerical value. In order to access and control a specific ADC channel, an application should first open and obtain an ADCChannel
instance for the ADC channel using its numerical ID, name, type (interface) and/or properties.
ADC channels are opened by invoking one of the PeripheralManager.open()
methods. This is an example of using its ID.
ADCChannel channel = (ADCChannel) PeripheralManager.open(8);
This is an example of using its name and interface.
ADCChannel channel = (ADCChannel) PeripheralManager.open("TEMPERATURE", ADCChannel.class, null);
Once the peripheral is opened, the application can read or monitor sampled input values using methods of the ADCChannel
interface, such as the getValue()
method:
int temp = channel.getValue();
When done, the application should call the ADCChannel.close()
method to release ADC channel.
channel.close();
Example 2-1 demonstrates two ways of using the ADC APIs.
Example 2-1 Using the ADC APIs
import com.oracle.deviceaccess.PeripheralManager; import com.oracle.deviceaccess.PeripheralNotAvailableException; import com.oracle.deviceaccess.PeripheralNotFoundException; import com.oracle.deviceaccess.adc.ADCChannel; import com.oracle.deviceaccess.adc.AcquisitionEvent; import com.oracle.deviceaccess.adc.AcquisitionListener; import java.io.IOException; class ADCAcquisition implements AcquisitionListener { private ADCChannel channel = null; public void start(int channelID) throws IOException, PeripheralNotAvailableException, PeripheralNotFoundException { channel = (ADCChannel) PeripheralManager.open(channelID); channel.setSamplingInterval(100); // every 100 milliseconds int[] values = new int[10]; channel.startAcquisition(values, 0, values.length, false, this); } public void inputAcquired(AcquisitionEvent event) { for (int i = 0; i < event.getCount(); i++) { int value = event.getValues()[event.getOffset() + i]; // Handle value... } } public void stop() throws IOException, PeripheralNotAvailableException { if (channel != null) { channel.stopAcquisition(); channel.close(); } } } class ADCThreshold implements MonitoringListener { private ADCChannel channel = null; public void start(int channelID, int low, int high) throws IOException, PeripheralNotAvailableException, PeripheralNotFoundException { channel = (ADCChannel) PeripheralManager.open(channelID); channel.setSamplingInterval(100); // every 100 milliseconds channel.startMonitoring(low, high, this); } public void thresholdReached(MonitoringEvent event) { if (event.getType() == MonitoringEvent.OUT_OF_RANGE) { int value = event.getValue(); // Handle condition... } } public void stop() throws IOException, PeripheralNotAvailableException { if (channel != null) { channel.stopMonitoring(); channel.close(); } } }
Note that the com.oracle.deviceaccess.adc
permission allows access to be granted to ADC channels 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 ADC APIs. Alternatively, the permission may be allowed for all applications in the untrusted
domain of the security policy file (policy.txt
).
Because of performance issue, any procedures that handle analog inputs, and especially event listeners, should be optimized to be as fast as possible.
The AcquisitionListener
interface contains methods for being notified of the availability of sampled values. An AcquisitionListener
can be registered using the ADCChannel.startAcquisition(int[], int, int, boolean, com.oracle.deviceaccess.adc.AcquisitionListener)
method.
The AcquisitionListener
interface contains only one method.
The ADCChannel
interface provides methods for controlling an ADC (Analog to Digital Converter) channel. One ADC device can have several channels. Analog input are sampled and converted according to the ADC device resolution to raw digital values between getMinValue()
and getMaxValue()
. Actual input voltage values can be calculated from raw digital values and the reference voltage value as returned by getVRefValue()
. Each ADC channel is identified by a numerical ID and by a name. An ADCChannel
instance can be opened by a call to one of the PeripheralManager.open()
methods. Once opened, an application can read the current sampled input value of an ADC channel by calling the getValue()
method or can acquire the input values sampled over a period of time by calling the getValues(int[], int, int)
method. An application can also asynchronously acquire the input values sampled over a period of time by calling the startAcquisition()
methods with an AcquisitionListener
instance which will get cyclicly and asynchronously notified when the desired number of samples have been acquired. The input acquisition can be stopped by calling the stopAcquisition()
method. An application can monitor the input value by calling the startMonitoring()
method with a low and a high threshold value and MonitoringListener
instance which will get asynchronously notified when the input value gets out of or back in the defined range. The monitoring can be stopped by calling the stopMonitoring()
method. Only one acquisition (synchronous or asynchronous) and one monitoring can occur at any time. One acquisition and one monitoring can be performed concurrently at the same sampling rate (see getSamplingInterval()
). They therefore respectively acquire and monitor the same sampled input values. When an application is no longer using an ADC channel, it should call the ADCChannel.close()
method to release the ADC channel. Any further attempt to set or get the value of a ADC channel which has been closed will throw a PeripheralNotAvailableException
. Note that asynchronous notification of range conditions or input acquisition is only loosely tied to hardware-level interrupt requests. The platform does not guarantee notification in a deterministic or timely manner.
The ADCChannel
interface consists of several methods:
int getMinValue()
throws java.io.IOException, PeripheralNotAvailableException
This method returns the minimum raw value this channel can sample. If the ADC device resolution is n
then the minimum value returned by getMinValue()
and the maximum value returned by getMaxValue()
are such that (max - min) == (2^n - 1)
.
int getMaxValue() throws java.io.IOException, PeripheralNotAvailableException
This method returns the maximum raw value this channel can sample. If the ADC device resolution is n
then the minimum value returned by getMinValue()
and the maximum value returned by getMaxValue()
are such that (max - min) == (2^n - 1)
.
double getVRefValue()
throws java.io.IOException, PeripheralNotAvailableException
This method returns the reference voltage value of this ADC channel. If the reference voltage is vRef
and the ADC device resolution is n
then the actual input voltage value corresponding to a raw sampled value value read on this channel can be calculated as follows: vInput = (value * vRef) / (2^n)
int getValue() throws java.io.IOException, PeripheralNotAvailableException
This method reads the current raw sampled input value of this channel. This method may be invoked at any time. If another thread has already initiated an I/O operation upon this channel, however, then an invocation of this method will block until the first operation is complete. Only one acquisition (synchronous or asynchronous) can be going on at any time.
void getValues(int[] buffer, int offset, int count) throws java.io.IOException, PeripheralNotAvailableException
This method reads count
raw sampled input values from this channel and copies them into the designated array. The input will be sampled according to the current sampling interval as returned by getSamplingInterval()
. This method may be invoked at any time. If another thread has already initiated an I/O operation upon this channel, however, then an invocation of this method will block until the first operation is complete. Only one acquisition (synchronous or asynchronous) can be going on at any time.
void startAcquisition(int[] buffer, int offset, int count, boolean doubleBuffering, AcquisitionListener listener) throws java.io.IOException, PeripheralNotAvailableException
This method starts sampling this channel input and asynchronously notifies the provided AcquisitionListener
instance when count raw sampled input values have been read from this channel. The read values are copied into the designated section of the provided buffer. Once count raw sampled input values have been read, reading will be suspended and in the event of continuous sampling, subsequent sampled input values may be lost. Reading into the buffer and notification will only resume once the event has been handled. Reading and notification will immediately start and will repeat until it is stopped by a call to stopAcquisition()
.
If double buffering is enabled, notification will happen when (count / 2)
raw sampled input values have been read and reading will proceed with the other half of the designated section of the provided buffer. Reading will only be suspended if the previous event has not yet been handled (this may result in the case of continuous sampling in subsequent sampled input values to be lost). If count
is not even then one part of the designated buffer section may be longer (by 1) than the other one.
The input will be sampled according to the current sampling interval as returned by getSamplingInterval()
. Note that only one acquisition (synchronous or asynchronous) can be going on at any time.
void stopAcquisition()
throws java.io.IOException, PeripheralNotAvailableException
This method stops the asynchronous sampling of this channel input as started by a call to one of the startAcquisition()
methods.
void startMonitoring(int low, int high, MonitoringListener listener) throws java.io.IOException, PeripheralNotAvailableException
This method starts monitoring this channel input and asynchronously notifies the provided MonitoringListener
instance when this channel's raw sampled input value gets out of or back in the specified range (as defined by a low and a high threshold value). Monitoring and notification will immediately start and will repeat until it is stopped by a call to stopMonitoring()
. Range notification operates in toggle mode: once notified of an out-of-range condition the application will next only get notified of a back-in-range condition and so on.
The sampled input value will be monitored according to the current sampling interval as returned by getSamplingInterval()
. To only be notified when the input value gets over some threshold, call this method with the low parameter set to the value of getMinValue()
. Conversely, to only be notified when the input value gets under some threshold, call this method with the high parameter set to the value of getMaxValue()
. If low
is lower than the minimum value returned by getMinValue(),
then the minimum value is assumed. If high
is higher the maximum value returned by getMaxValue()
, then the maximum value is assumed. Only one monitoring can occur at any time.
This method stops the range monitoring of this channel input as started by a call to the startMonitoring()
method.
void setSamplingInterval(int interval) throws java.io.IOException, PeripheralNotAvailableException
This method sets the sampling interval, in microseconds.
int getSamplingInterval() throws java.io.IOException, PeripheralNotAvailableException
This method returns the sampling interval, in microseconds. If the sampling interval was not set previously using setSamplingInterval(int)
, the peripheral configuration-specific default value is returned.
int getMinSamplingInterval()
throws java.io.IOException, PeripheralNotAvailableException
This method returns the minimum sampling interval, in microseconds, that can be set using setSamplingInterval(int)
.
The MonitoringListener
interface defines a method for being notified of ADC channel under- and over-threshold input value conditions. A MonitoringListener
can be registered using the ADCChannel.startMonitoring(int, int, MonitoringListener)
method.
The MonitoringListener
interface consists of only one method:
The AcquisitionEvent
class encapsulates ADC channel input acquisition conditions. Note that this kind of event is never coalesced.
There are two constructors in the AcquisitionEvent
class:
public AcquisitionEvent(ADCChannel channel, int[] values, int offset, int number)
This method creates a new AcquisitionEvent
with the specified raw sampled values and time-stamped with the current time.
public AcquisitionEvent(ADCChannel channel, int[] values, int offset, int number, long timeStamp, int timeStampMicros)
This method creates a new AcquisitionEvent
with the specified raw sampled values and timestamp.
There are three methods in this class as well.
The ADCChannelConfig
class encapsulates the hardware addressing information, and static and dynamic configuration parameters, of an ADC channel. Some hardware addressing parameter, and static and dynamic configuration parameters, may be set to PeripheralConfig.DEFAULT
. Whether such default settings are supported is both platform-dependent and peripheral driver-dependent.
An instance of ADCChannelConfig
can be passed to the PeripheralManager.open(PeripheralConfig)
or PeripheralManager.open(Class, PeripheralConfig)
method to open the designated ADC channel with the specified configuration. A PeripheralConfigInvalidException
is thrown when attempting to open a peripheral device with an invalid or unsupported configuration.
The ADCChannelConfig
class consists of one constructor and several methods.
public ADCChannelConfig(int converterNumber, int channelNumber, int resolution, int samplingInterval, int samplingTime)
This constructor creates a new ADCChannelConfig
with the specified hardware addressing information and configuration parameters.
This method returns the configured channel number.
This method returns the configured resolution.
public int getConverterNumber()
This method returns the configured converter number.
public int getSamplingInterval()
This method returns the configured default/initial sampling interval (the amount of time between two samples) in microseconds.
This method returns the configured sampling time (the amount of time to take a sample) in microseconds.
The MonitoringEvent
class encapsulates ADC channel under- and over-threshold value conditions. If range events for the same ADC channel are coalesced, the value and the type (either in or out of range) are that of the last occurrence.
The PeripheralManager
class contains two constants:
public static final int OUT_OF_RANGE
Indicates that the ADC channel value exceeded the defined range.
public static final int BACK_TO_RANGE
Indicates that the ADC channel value returned to the defined range.
The PeripheralManager
class consists of the following constructors and methods:
public MonitoringEvent(ADCChannel channel, int type, int value)
This constructor creates a new MonitoringEvent
with the specified raw sampled value. It will automatically be time-stamped with the current time.
public MonitoringEvent(ADCChannel channel, int type, int value, long timeStamp, int timeStampMicros)
This constructor creates a new MonitoringEvent
with the specified raw sampled value and the specified timestamp.
This method returns the type of range condition being notified.
This method returns the new ADC channel's value.
The com.oracle.deviceaccess.adc
package consists of one exception, which is shown in Table 2-1: