5 Digital-to-Analog Converter

The com.oracle.deviceaccess.dac package contains interfaces and classes for writing analog outputs using a Digital to Analog Converter (DAC). A DAC is a device that converts a digital, typically binary, code to an analog signal, such as a current, voltage, or electric charge.

One DAC converter can have several channels. Each channel can sample an analog output from numerical values that are converted to output voltages. In order to access and control a specific DAC channel, an application should first open and obtain an DACChannel instance for the DAC channel the application wants to access and control, using its numerical ID, name, type (interface) and properties.

This is an example of using its ID.

 DACChannel channel = (DACChannel) PeripheralManager.open(5);

This is an example of using its name and interface.

 DACChannel channel = (DACChannel) PeripheralManager.open("LED", DACChannel.class, null);

Once the peripheral is opened, an application can write output values to a DAC channel using methods of the DACChannel interface, such as the setValue() method.

 channel.setValue(brightness);

When completed, the application should call the DACChannel.close() method to release the DAC channel.

channel.close();

Example 5-1 shows how to use the DAC API.

Example 5-1 Using the DAC API

import com.oracle.deviceaccess.InvalidStateException;
import com.oracle.deviceaccess.PeripheralManager;
import com.oracle.deviceaccess.PeripheralNotAvailableException;
import com.oracle.deviceaccess.PeripheralNotFoundException;
import com.oracle.deviceaccess.dac.DACChannel;
import com.oracle.deviceaccess.dac.GenerationEvent;
import com.oracle.deviceaccess.dac.GenerationListener;
import java.io.IOException;
 
class VaryingDimmer implements GenerationListener {
 
     private DACChannel channel = null;
 
     public void start(int channelID) throws IOException,
       PeripheralNotAvailableException, PeripheralNotFoundException
     {
         if (channel != null) {
             throw new InvalidStateException();
         }
         channel = (DACChannel) PeripheralManager.open(channelID);
         channel.setSamplingInterval(1000); // every 1000 milliseconds
         // Creates a series of samples varying from min value to max value
         int[] values = new int[10];
         int min = channel.getMinValue();
         int max = channel.getMaxValue();
         for (int i = 0; i < values.length; i++) {
             values[i] = min + (((max - min) / (values.length - 1)) * i);
         }
         channel.startGeneration(values, 0, values.length, false, this);
     }
 
     public void outputGenerated(GenerationEvent event) {
         event.setActualNumber(event.getNumber());
              // Replay the same sample series
     }
 
     public void stop() throws IOException, PeripheralNotAvailableException {
         if (channel != null) {
             channel.stopGeneration();
             channel.close();
         }
     }
 }

Because of performance issue, procedures handling analog outputs should be optimized to be as fast as possible.

DAC channels are opened by invoking one of the com.oracle.deviceaccess.PeripheralManager.open() methods. Note that the com.oracle.deviceaccess.dac permission allows access to be granted to DAC 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 APIs. Alternatively, the permission may be allowed for all applications in the untrusted domain of the security policy file (policy.txt).

The DACChannel Interface

The DACChannel interface provides methods for controlling a DAC (Digital to Analog Converter) channel.

One DAC device can have several channels. Raw digital output values are converted to analog output values according to the DAC channel resolution. According to the DAC channel resolution, the raw digital output values may range from getMinValue() to getMaxValue(). Actual output voltage values can be calculated from raw digital values and the Reference Voltage value as returned by getVRefValue().

Each DAC channel is identified by a numerical ID and by a name. A DACChannel instance can be opened by a call to one of the PeripheralManager.open() methods. Once opened, an application can write an output value to a DAC channel by calling the setValue(int) method or can write a series of output values to be sampled over a period of time by calling the setValues(int[], int, int) method. An application can also asynchronously write a series of output values to be sampled over a period of time by calling by calling the startSampling() methods with a SamplingListener instance which will get cyclicly and asynchronously notified when the requested number of samples have been written.

The output sampling can be stopped by calling the stopSampling() method. Only one output operation (synchronous or asynchronous) can occur at any time. When an application is no longer using an DAC channel, it should call the DACChannel.close() method to release the DAC channel. Any further attempt to set or get the value of a DAC channel which has been closed will result in a PeripheralNotAvailableException been thrown.

Note that asynchronous notification of output sampling completion is only loosely tied to hardware-level interrupt requests. The platform does not guarantee notification in a deterministic or timely manner.

The DACChannel interface contains ten methods.

int getMinValue() throws java.io.IOException, PeripheralNotAvailableException

This method returns the minimum raw value this channel can sample. If the DAC 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 DAC 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 DAC channel. If the reference voltage is vRef and the DAC device resolution is n, then the actual output voltage value corresponding to a raw value value written to this channel can be calculated as follows: vOutput = (value * vRef) / (2^n)
void setValue(int value) throws java.io.IOException, PeripheralNotAvailableException

This method writes the provided raw output value to this channel. The corresponding converted analog output value will be held until it is overwritten by another output operation. This method may be invoked at any time. If another thread has already initiated a synchronous output operation upon this channel then an invocation of this method will block until the first operation is complete. Only one conversion,. synchronous or asynchronous, can occur at any time.
void setValues(int[] buffer, int offset, int count) throws java.io.IOException, PeripheralNotAvailableException

This method writes count raw output values from the designated array to this channel for sampling. The analog output 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 conversion, synchronous or asynchronous, can occur at any time.
void startGeneration(int[] buffer, int offset, int count, boolean doubleBuffering, GenerationListener listener) throws java.io.IOException, PeripheralNotAvailableException

This method starts asynchronous analog output generation on this channel from a series of raw output values (samples). More values to be converted are asynchronously fetched by notifying the provided GenerationListener instance once the initial count raw output values have been converted. The initial raw output values to be converted are read from the designated section of the provided buffer. Values subsequently fetched using the provided GenerationListener instance are read from the same buffer section. Analog output generation can be stopped by a call to stopGeneration().

If double buffering is enabled, notification will happen when (count / 2) raw output values have been written and writing will proceed with the other half of the designated section of the provided buffer. Writing will only be suspended if the previous event has not yet been handled. if count is not even then one part of the designated buffer section may be longer (by 1) than the other one. The analog output will be sampled according to the current sampling interval as returned by getSamplingInterval(). Only one conversion, synchronous or asynchronous, can occur at any time.
void stopGeneration() throws java.io.IOException, PeripheralNotAvailableException

This method stops the asynchronous sampling of this channel output as started by a call to the startGeneration() method.
void setSamplingInterval(int interval) throws java.io.IOException, PeripheralNotAvailableException

This method returns the sampling interval, in microseconds. Whether changing the sampling interval has an immediate effect on an active (synchronous or asynchronous) generation is peripheral device-dependent as well as platform-dependent.
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 GenerationListener Interface

The GenerationListener interface defines methods for being notified of the completion of the conversion of a set of raw output values and that more output values to be converted may be provided. A GenerationListener can be registered using the DACChannel.startGeneration(int[], int, int, boolean, com.oracle.deviceaccess.dac.GenerationListener) method.

The GenerationListener interface consists of only one method:

void outputGenerated(GenerationEvent event)

This method is invoked when a buffer of DAC output values has been converted, and the buffer is available for copying more output values for convertion.

The DACChannelConfig Class

The DACChannelConfig class encapsulates the hardware addressing information, and static and dynamic configuration parameters of an DAC channel. Some hardware addressing parameters, as well as 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 DACChannelConfig can be passed to the PeripheralManager.open(PeripheralConfig) or PeripheralManager.open(Class, PeripheralConfig) method to open the designated DAC channel with the specified configuration. A PeripheralConfigInvalidException is thrown when attempting to open a peripheral device with an invalid or unsupported configuration

The DACChannelConfig interface consists of one constructor and four methods:

public DACChannelConfig(int converterNumber, int channelNumber, int resolution, int samplingInterval)

This constructor creates a new DACChannelConfig 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 default/initial configured sampling interval, in microseconds.

The GenerationEvent Class

The GenerationEvent class encapsulates DAC channel output sampling completion conditions. A GenerationEvent may indicate that: either all the values to output have been written and the designated buffer section is available for more values to output, or, in case of double buffering, half of the values to output have been written and the designated buffer section is available for more values to output.

When handling a GenerationEvent, the application may copy more output values to be converted in the buffer section designated by the getValues(), getOffset() and getNumber() methods. The application must set the actual number of output values copied by calling setActualNumber(int). If the actual number is set to a value smaller than the length of the designated buffer section, as given by the getNumber() method, the current asynchronous analog output generation will stop after the last provided output values have been converted, as if from a call to DACChannel.stopGeneration().

Note that this kind of event is never coalesced.

The GenerationEvent interface consists of two constructors and five methods:

public GenerationEvent(DACChannel channel, int[] values, int offset, int number)

This constructor creates a new GenerationEvent with the specified raw output value buffer and time-stamped with the current time..
public GenerationEvent(DACChannel channel, int[] values, int offset, int number, long timeStamp, int timeStampMicros)

This constructor creates a new GenerationEvent with the specified raw output value buffer and timestamp.
public int[] getValues()

This method returns the buffer where the values to output must be copied. This buffer is the same buffer that was passed as parameter to DACChannel.startGeneration(int[], int, int, boolean, com.oracle.deviceaccess.dac.GenerationListener).
public int getOffset()

This method returns the offset in the values buffer where to start copying the values to output. This offset is within the range defined by the parameters passed to DACChannel.startGeneration(int[], int, int, boolean, com.oracle.deviceaccess.dac.GenerationListener).
public int getNumber()

This method returns the maximum number of values to output that can be copied to the values buffer.
public void setActualNumber(int actualNumber)

This method sets the actual number of values to output that were copied to the values buffer. If the provided value is smaller than the length of the designated buffer section, as given by the getNumber() method, then the current asynchronous analog output generation will be stopped, as if from a call to DACChannel.stopGeneration().
public int getActualNumber()

This method returns the actual number of values to output that were copied to the values buffer.

Exceptions

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

Table 5-1 Exceptions of the com.oracle.deviceaccess.dac Package

Suite Type	Description
`InvalidSamplingRateException`	Thrown by an instance of `DACChannel` in case the requested sampling rate is higher than the maximum sampling rate the DAC device can support.