2 Analog-to-Digital Converter

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

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.

void inputAcquired(AcquisitionEvent event)

This method is invoked when a buffer of ADC sampled values has been filled and is available for processing.

The ADCChannel Interface

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.
void stopMonitoring()

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

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:

void thresholdReached(MonitoringEvent event)

This method is invoked when the input value has reached the low or high threshold.

The AcquisitionEvent Class

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.

public int[] getValues()

This method returns the buffer containing the sampled values.
public int getOffset()

This method returns the offset in the values buffer where the sampled values start.
public int getNumber()

This method returns the number of sampled values.

The ADCChannelConfig Class

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.
public int getChannelNumber()

This method returns the configured channel number.
public int getResolution()

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.
public int getSamplingTime()

This method returns the configured sampling time (the amount of time to take a sample) in microseconds.

The MonitoringEvent Class

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.
public int getType()

This method returns the type of range condition being notified.
public int getValue()

This method returns the new ADC channel's value.

Exceptions

The com.oracle.deviceaccess.adc package consists of one exception, which is shown in Table 2-1:

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

Suite Type	Description
`InvalidSamplingRateException`	Thrown by an instance of `ADCChannel` when the requested sampling rate is higher than the maximum sampling rate the ADC device can support.