jdk.dio.adc

Interface ADCChannel

All Superinterfaces:

java.lang.AutoCloseable, BufferAccess<java.nio.IntBuffer>, java.nio.channels.Channel, java.io.Closeable, Device<ADCChannel>

public interface ADCChannel
extends Device<ADCChannel>, BufferAccess<java.nio.IntBuffer>

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.

An ADC channel may be identified by the numerical ID and by the name (if any defined) that correspond to its registered configuration. An ADCChannel instance can be opened by a call to one of the DeviceManager.open(id,...) methods using its ID or by a call to one of the DeviceManager.open(name,...) methods using its name. When a ADCChannel instance is opened with an ad-hoc ADCChannelConfig configuration (which includes its hardware addressing information) using one of the DeviceManager.open(config,...) it is not assigned any ID nor name.

Once opened, an application can read the current sampled input value of an ADC channel by calling the acquire method or can acquire the input values sampled over a period of time by calling the acquire(IntBuffer) method.

An application can also asynchronously acquire the input values sampled at a certain rate by calling the startAcquisition methods with a AcquisitionRoundListener instance which will get cyclicly and asynchronously notified when the desired number of samples have been acquired. The analog 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.

At most one acquisition (synchronous or asynchronous) and/or (depending on the platform) at most one monitoring can be going on at any time. If an acquisition and a monitoring can be performed concurrently, they will be performed 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 close method to close the ADC channel. Any further attempt to set or get the value of a ADC channel which has been closed will result in a ClosedDeviceException been thrown.

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/timely manner.

See Also:

AcquisitionRoundListener, MonitoringListener, ADCPermission

Field Summary

Fields inherited from interface jdk.dio.Device

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN

Method Summary

Methods

Modifier and Type	Method and Description
int	acquire() Reads the current raw sampled input value of this channel.
void	acquire(java.nio.IntBuffer dst) Reads a sequence of raw sampled input values from this channel and copies them into the provided buffer.
int	getMaxValue() Returns the maximum raw value this channel can convert.
int	getMinSamplingInterval() Gets the minimum input sampling interval (in microseconds) that can be set using setSamplingInterval.
int	getMinValue() Returns the minimum raw value this channel can convert.
int	getSamplingInterval() Gets the input sampling interval (in microseconds).
double	getVRefValue() Returns the Reference Voltage value of this ADC channel.
void	setSamplingInterval(int interval) Sets the input sampling interval (in microseconds).
void	startAcquisition(java.nio.IntBuffer dst, AcquisitionRoundListener listener) Starts asynchronous analog input acquisition on this channel and reads a series of raw sampled input values.
void	startAcquisition(java.nio.IntBuffer dst1, java.nio.IntBuffer dst2, AcquisitionRoundListener listener) Starts asynchronous analog input acquisition on this channel and reads a series of raw sampled input values.
void	startMonitoring(int low, int high, MonitoringListener listener) Starts monitoring this channel analog 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).
void	stopAcquisition() Stops the asynchronous analog input acquisition on this channel as started by a call to one of the startAcquisition methods.
void	stopMonitoring() Stops the range monitoring of this channel analog input as started by a call to the startMonitoring method.

Methods inherited from interface jdk.dio.Device

close, getDescriptor, isOpen, tryLock, unlock

Methods inherited from interface jdk.dio.BufferAccess

getInputBuffer, getOutputBuffer

Method Detail

getMaxValue

int getMaxValue()
                throws java.io.IOException,
                       UnavailableDeviceException,
                       ClosedDeviceException

Returns the maximum raw value this channel can convert. If the ADC device resolution is n then the min value returned by getMinValue and the max value returned by getMaxValue are such that:

 (max - min) == (2^n - 1).
 

Returns:

the maximum raw value this channel can convert.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

getMinSamplingInterval

int getMinSamplingInterval()
                           throws java.io.IOException,
                                  UnavailableDeviceException,
                                  ClosedDeviceException

Gets the minimum input sampling interval (in microseconds) that can be set using setSamplingInterval.

Returns:

the minimum input sampling interval (in microseconds).

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

getMinValue

int getMinValue()
                throws java.io.IOException,
                       UnavailableDeviceException,
                       ClosedDeviceException

Returns the minimum raw value this channel can convert. If the ADC device resolution is n then the min value returned by getMinValue and the max value returned by getMaxValue are such that:

 (max - min) == (2^n - 1).
 

Returns:

the minimum raw value this channel can convert.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

getSamplingInterval

int getSamplingInterval()
                        throws java.io.IOException,
                               UnavailableDeviceException,
                               ClosedDeviceException

Gets the input sampling interval (in microseconds). If the sampling interval was not set previously using setSamplingInterval the device configuration-specific default value is returned.

Returns:

the input sampling interval (in microseconds).

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

acquire

int acquire()
            throws java.io.IOException,
                   UnavailableDeviceException,
                   ClosedDeviceException

Reads the current raw sampled input value of this channel.

This method may be invoked at any time. If another thread has already initiated a synchronous input acquisition 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.

Returns:

this channel's current raw sampled input value.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if another asynchronous acquisition is already active.

acquire

void acquire(java.nio.IntBuffer dst)
             throws java.io.IOException,
                    UnavailableDeviceException,
                    ClosedDeviceException

Reads a sequence of raw sampled input values from this channel and copies them into the provided buffer.

The input will be sampled according to the current input sampling interval as returned by getSamplingInterval.

r int integers will be read from this channel, where r is the number of integers remaining in the buffer, that is, dst.remaining(), at the moment this method is invoked.

Suppose that an integer sequence of length n is read, where 0 <= n <= r . This integer sequence will be transferred into the buffer so that the first integer in the sequence is at index p and the last integer is at index p + n - 1, where p is the buffer's position at the moment this method is invoked. Upon return the buffer's position will be equal to p + n; its limit will not have changed.

This operation will block until the requested r integers are read or an error occurs.

This method may be invoked at any time. If another thread has already initiated a synchronous input acquisition 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.

Parameters:

dst - The buffer into which integer raw sampled input values are to be transferred

Throws:

java.lang.NullPointerException - If dst is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

java.lang.IllegalStateException - if another asynchronous acquisition is already active.

java.lang.UnsupportedOperationException - if an asynchronous monitoring is already active and acquisition and monitoring cannot be performed concurrently.

getVRefValue

double getVRefValue()
                    throws java.io.IOException,
                           UnavailableDeviceException,
                           ClosedDeviceException

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)
 

Returns:

the Reference Voltage value of this channel.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

setSamplingInterval

void setSamplingInterval(int interval)
                         throws java.io.IOException,
                                UnavailableDeviceException,
                                ClosedDeviceException

Sets the input sampling interval (in microseconds). Whether changing the sampling interval has an immediate effect or not on an active (synchronous or asynchronous) acquisition is device- as well as platform-dependent.

Parameters:

interval - the input sampling interval (in microseconds).

Throws:

java.io.IOException - if some other I/O error occurs.

InvalidInputSamplingRateException - if the resulting sampling rate (i.e.: (1 / interval)) is higher than the maximum supported sampling rate (i.e.: (1 / getMinSamplingInterval )).

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalArgumentException - if interval is negative or zero.

startAcquisition

void startAcquisition(java.nio.IntBuffer dst,
                    AcquisitionRoundListener listener)
                      throws java.io.IOException,
                             UnavailableDeviceException,
                             ClosedDeviceException

Starts asynchronous analog input acquisition on this channel and reads a series of raw sampled input values. The provided AcquisitionRoundListener instance is cyclicly notified when the provided buffer has been filled with raw sampled input values. The read values are copied into the provided buffer. Once the requested number of raw sampled input values has 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.

r int integers will be read from this channel, where r is the number of integers remaining in the buffer (possibly 0), that is, dst.remaining(), at the moment this method is initially invoked and then subsequently when the listener is returning.

Suppose that an integer sequence of length n is read, where 0 <= n <= r . This integer sequence will be transferred into the buffer so that the first integer in the sequence is at index p and the last integer is at index p + n - 1, where p is the buffer's position at the moment this method is invoked and then subsequently when the listener is returning. Upon invocation of the listener to fetch more values to convert the buffer's position will be equal to p + n; its limit will not have changed.
The buffer's position upon stopping this asynchronous operation by a call to stopAcquisition is not predictable unless called from within the listener.

Note that a buffer with 0 integers remaining to be read (that is a buffer already full), at the moment this method is initially invoked or then subsequently when the listener is returning will not stop the asynchronous operation; the listener is guaranteed to be called back again at the latest as soon as all other events pending at the time of notification have been dispatched.

Interfering with the asynchronous operation by accessing and modifying the provided buffer concurrently may yield unpredictable results.

The input will be sampled according to the current input sampling interval as returned by getSamplingInterval.

Only one acquisition (synchronous or asynchronous) can be going on at any time.

Parameters:

dst - The buffer into which integer raw sampled input values are to be transferred.

listener - the AcquisitionRoundListener instance to be notified when all the sampled input values have been read.

Throws:

java.lang.NullPointerException - If dst or listener is null.

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if another synchronous or asynchronous acquisition is already active.

java.lang.UnsupportedOperationException - if an asynchronous monitoring is already active and acquisition and monitoring cannot be performed concurrently.

startAcquisition

void startAcquisition(java.nio.IntBuffer dst1,
                    java.nio.IntBuffer dst2,
                    AcquisitionRoundListener listener)
                      throws java.io.IOException,
                             UnavailableDeviceException,
                             ClosedDeviceException

Starts asynchronous analog input acquisition on this channel and reads a series of raw sampled input values.

This method behaves identically to startAcquisition(IntBuffer, AcquisitionRoundListener) excepts that it uses double-buffering. Notification will happen when the current working buffer (initially dst1) has been filled with raw sampled input values and reading will asynchronously proceed with the alternate buffer (which becomes the current working 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).

Note that a working buffer with 0 integers remaining to be read (that is a buffer already full), at the moment this method is initially invoked or then subsequently when the listener is returning will not stop the asynchronous operation; the listener is guaranteed to be called back again at the latest as soon as all other events pending at the time of notification have been dispatched.

Only one acquisition (synchronous or asynchronous) can be going on at any time.

Parameters:

dst1 - The first buffer into which integer raw sampled input values are to be transferred.

dst2 - The second buffer into which integer raw sampled input values are to be transferred.

listener - the AcquisitionRoundListener instance to be notified when all the sampled input values have been read.

Throws:

java.lang.NullPointerException - If dst1, dst2 or listener is null.

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if another synchronous or asynchronous acquisition is already active.

java.lang.UnsupportedOperationException - if an asynchronous monitoring is already active and acquisition and monitoring cannot be performed concurrently.

startMonitoring

void startMonitoring(int low,
                   int high,
                   MonitoringListener listener)
                     throws java.io.IOException,
                            UnavailableDeviceException,
                            ClosedDeviceException

Starts monitoring this channel analog 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 input sampling interval as returned by getSamplingInterval.

To only get notified when the input value gets over some threshold one may call this method with the low parameter set to the value of getMinValue. Conversely, to only get notified when the input value gets under some threshold one may 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 be going on at any time.

Parameters:

listener - the MonitoringListener instance to be notified when a range condition occurs.

low - the low raw threshold value.

high - the high raw threshold value.

Throws:

java.io.IOException - if some other I/O error occurs.

java.lang.IllegalArgumentException - if low is greater than high.

java.lang.NullPointerException - if listener is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if monitoring is already active.

java.lang.UnsupportedOperationException - if an asynchronous acquisition is already active and monitoring and acquisition cannot be performed concurrently.

stopAcquisition

void stopAcquisition()
                     throws java.io.IOException,
                            UnavailableDeviceException,
                            ClosedDeviceException

Stops the asynchronous analog input acquisition on this channel as started by a call to one of the startAcquisition methods.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

stopMonitoring

void stopMonitoring()
                    throws java.io.IOException,
                           UnavailableDeviceException,
                           ClosedDeviceException

Stops the range monitoring of this channel analog input as started by a call to the startMonitoring method.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.