Skip Headers
Oracle® Java ME Embedded Device Access API Guide
Release 3.3
E35134-02
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

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.

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:

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:

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:

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.