public interface ADCChannel extends Device<ADCChannel>, BufferAccess<java.nio.IntBuffer>
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 numeric 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,...)
methods 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.
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.
ADCChannelConfig
configuration to
a value greater than 0
; whether or not the channel will indeed work
in buffering mode and will use an internal input buffer of the size requested
is up to the device driver. An application may check whether a channel is
working in buffering mode by calling the
ADCChannelConfig.getInputBufferSize
method. Buffer
s to the input methods; whether
efficient direct input transfers will be used depends on the underlying
hardware and driver capabilities and on whether the provided buffers are
suitable for such operations (see
BufferAccess.prepareBuffer
). Input methods
using double buffering may only support efficient direct operations if both
buffers are suitable for such operations.AcquisitionRoundListener
,
MonitoringListener
,
ADCPermission
BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN
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 |
getMaxSamplingInterval()
Gets the maximum scaled input sampling interval (in microseconds) that can be set using
setSamplingInterval . |
int |
getMaxValue()
Returns the maximum raw value this channel can convert to.
|
int |
getMinSamplingInterval()
Gets the minimum scaled input sampling interval (in microseconds) that can be set using
setSamplingInterval . |
int |
getMinValue()
Returns the minimum raw value this channel can convert to.
|
int |
getSamplingInterval()
Gets the scaled input sampling interval (in microseconds).
|
double |
getScaleFactor()
Gets the sampling interval scale factor of this ADC channel.
|
double |
getVRefValue()
Returns the Reference Voltage value of this ADC channel.
|
void |
setSamplingInterval(int interval)
Sets the scaled input sampling interval (in microseconds).
|
void |
setScaleFactor(double factor)
Sets the sampling interval scale factor of this ADC channel.
|
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. |
close, getByteOrder, getDescriptor, isOpen, tryLock, unlock
getInputBuffer, getOutputBuffer, prepareBuffer
int getMaxValue() throws java.io.IOException, UnavailableDeviceException, ClosedDeviceException
n
then the min
value returned by getMinValue
and the
max
value returned by getMaxValue
are such that: (max - min) == (2^n - 1)
.
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.int getMinSamplingInterval() throws java.io.IOException, UnavailableDeviceException, ClosedDeviceException
setSamplingInterval
. The minimum effective sampling interval
can be calculated from the currently set scale factor as can be retrieved using
getScaleFactor
.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.int getMaxSamplingInterval() throws java.io.IOException, UnavailableDeviceException, ClosedDeviceException
setSamplingInterval
. The maximum effective sampling interval
can be calculated from the currently set scale factor as can be retrieved using
getScaleFactor
.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.int getMinValue() throws java.io.IOException, UnavailableDeviceException, ClosedDeviceException
n
then the min
value returned by getMinValue
and the
max
value returned by getMaxValue
are such that: (max - min) == (2^n - 1)
.
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.int getSamplingInterval() throws java.io.IOException, UnavailableDeviceException, ClosedDeviceException
getScaleFactor
.
If the sampling interval was not
set previously using setSamplingInterval
, the device
configuration-specific default value is returned. Additionally, the value returned may differ
from the previously set or configured value as it may have been adjusted to account
for the timer resolution or discrete sampling interval values supported by the underlying platform or driver.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.void setScaleFactor(double factor) throws java.io.IOException, UnavailableDeviceException, ClosedDeviceException
setSamplingInterval
method in order to set
an appropriate scaled sampling interval.factor
- the scale factor (a number greater or equal to 1.0
).java.lang.IllegalArgumentException
- if factor
is NaN
, is less than 1.0
or,
if the setting of the scale factor would result
in the scaled sampling interval range to be outside the range [1 -
Integer.MAX_VALUE
]
.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.getScaleFactor()
,
setSamplingInterval(int)
double getScaleFactor() throws java.io.IOException, UnavailableDeviceException, ClosedDeviceException
scale
and the scaled sampling interval value as
returned by getSamplingInterval
is sInterval
then the
effective sampling interval is calculated as follows: Conversely, the scaled sampling interval value to set usingeInterval = (sInterval / scale)
setSamplingInterval(int)
to obtain the effective sampling
interval eInterval
is calculated as follows: The scale factor also applies to the minimum and maximum scaled sampling intervals as respectively returned bysInterval = (eInterval * scale)
getMinSamplingInterval
and getMaxSamplingInterval
.
If the sampling interval scale factor was not set previously using
setScaleFactor
, the device configuration-specific
default value is returned.
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.int acquire() throws java.io.IOException, UnavailableDeviceException, ClosedDeviceException
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.
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 an asynchronous acquisition is already active.void acquire(java.nio.IntBuffer dst) throws java.io.IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException
The input will be sampled according to the current effective input sampling interval
as determined by the current scaled sampling interval (see getSamplingInterval
)
and the current scale factor getScaleFactor
.
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 raw input values
have been read or otherwise transferred from the driver/hardware. If this
channel uses an internal input buffer and is therefore
working in buffering mode this method will block
until all the r raw input values have been copied from the internal
input buffer.
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.
dst
- The buffer into which integer raw sampled input values are to be transferredjava.lang.NullPointerException
- If dst
is null
.java.lang.IllegalStateException
- if an asynchronous acquisition is already active.UnavailableDeviceException
- if this device is not currently available - such as it is locked by another
application.UnsupportedByteOrderException
- if the byte ordering of the provided buffer is not supported (see Device Byte Order).ClosedDeviceException
- if the device has been closed.java.io.IOException
- if some other I/O error occurs.java.lang.UnsupportedOperationException
- if an asynchronous monitoring is already active and acquisition and monitoring
cannot be performed concurrently.double getVRefValue() throws java.io.IOException, UnavailableDeviceException, ClosedDeviceException
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)
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.void setSamplingInterval(int interval) throws java.io.IOException, UnavailableDeviceException, ClosedDeviceException
getScaleFactor
.
Whether changing the sampling interval
has an immediate effect or not on an active (synchronous or asynchronous) generation is
device- as well as platform-dependent.
If the underlying platform or driver does not support the requested interval value
then interval
will be aligned to the closest lower supported discrete interval value. The resulting, actual
scaled sampling interval can be retrieved by a call to getSamplingInterval
.
If the current scale factor as returned by
getScaleFactor
is scale
and the current scaled
sampling interval value - after alignment - is sInterval
then the effective sampling interval can be calculated as follows:
eInterval = (sInterval / scale)
interval
- the scaled input sampling interval (in microseconds).java.io.IOException
- if some other I/O error occurs.InvalidInputSamplingRateException
- if interval
is greater than the maximum sampling interval (see getMaxSamplingInterval
)
or lower than the minimum sampling interval (see 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.void startAcquisition(java.nio.IntBuffer dst, AcquisitionRoundListener listener) throws java.io.IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException
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.
If this channel
uses an internal input buffer and is therefore working in buffering mode the listener will only be
invoked after all the r raw input values have been copied from the
internal input buffer; otherwise the listener will only be invoked after all the
r raw input values have been transferred from the driver/hardware.
The buffer's position upon stopping this asynchronous operation by a call to
stopAcquisition
is not predictable unless called from within the
listener.
Upon notification of the provided AcquisitionRoundListener
the reference to the provided dst
buffer can be retrieved from the
RoundCompletionEvent
using the getBuffer
method.
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. The overrun condition resulting from the listener notification
returning with an already-full buffer will be reported on the subsequent notifications through
the RoundCompletionEvent.isOnError
method.
The input will be sampled according to the current effective input sampling interval
as determined by the current scaled sampling interval (see getSamplingInterval
)
and the current scale factor getScaleFactor
.
Only one acquisition (synchronous or asynchronous) can be going on at any time.
Buffers are not safe for use by multiple concurrent threads so care should be taken to not access the provided buffer until the operation (or a round thereof) has completed. Interfering with the asynchronous operation by accessing and modifying the provided buffer concurrently may yield unpredictable results.
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.java.lang.NullPointerException
- If dst
or listener
is null
.java.lang.IllegalArgumentException
- if the provided buffer dst
has a zero-capacity.java.lang.IllegalStateException
- if another synchronous or asynchronous acquisition is already active.UnavailableDeviceException
- if this device is not currently available - such as it is locked by another
application.UnsupportedByteOrderException
- if the byte ordering of the provided buffer is not supported (see Device Byte Order).ClosedDeviceException
- if the device has been closed.java.io.IOException
- if some other I/O error occurs.java.lang.UnsupportedOperationException
- if an asynchronous monitoring is already active and acquisition and monitoring
cannot be performed concurrently.void startAcquisition(java.nio.IntBuffer dst1, java.nio.IntBuffer dst2, AcquisitionRoundListener listener) throws java.io.IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException
This method behaves identically to
startAcquisition(IntBuffer, AcquisitionRoundListener)
excepts that it uses
double-buffering - the provided buffers must not have a zero-capacity and must not overlap
- that is the backing array sections or memory regions they refer to must not overlap.
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). Also,
the position of the current working buffer upon stopping this asynchronous operation by a call to
stopAcquisition
is not predictable even if called from within the
listener.
Upon notification of the provided AcquisitionRoundListener
the reference to the current working buffer (initially dst1
) can be retrieved from the
RoundCompletionEvent
using the getBuffer
method.
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. The overrun condition resulting from the listener notification
returning with an already-full buffer will be reported on the subsequent notifications through
the RoundCompletionEvent.isOnError
method.
Only one acquisition (synchronous or asynchronous) can be going on at any time.
Buffers are not safe for use by multiple concurrent threads so care should be taken to not access the provided buffers until the operation (or a round thereof) has completed. Interfering with the asynchronous operation by accessing and modifying the provided buffers concurrently may yield unpredictable results.
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.java.lang.NullPointerException
- If dst1
, dst2
or listener
is null
.java.lang.IllegalStateException
- if another synchronous or asynchronous acquisition is already active.java.lang.IllegalArgumentException
- if any of the buffers dst1
and dst2
has a zero-capacity or
if they are the same or overlap.UnavailableDeviceException
- if this device is not currently available - such as it is locked by another
application.UnsupportedByteOrderException
- if the byte ordering of the any of the provided buffers is not supported (see Device Byte Order).ClosedDeviceException
- if the device has been closed.java.io.IOException
- if some other I/O error occurs.java.lang.UnsupportedOperationException
- if an asynchronous monitoring is already active and acquisition and monitoring
cannot be performed concurrently.void startMonitoring(int low, int high, MonitoringListener listener) throws java.io.IOException, UnavailableDeviceException, ClosedDeviceException
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 input will be sampled according to the current effective input sampling interval
as determined by the current scaled sampling interval (see getSamplingInterval
)
and the current scale factor getScaleFactor
.
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.
listener
- the MonitoringListener
instance to be notified when a range condition
occurs.low
- the low raw threshold value.high
- the high raw threshold value.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.void stopAcquisition() throws java.io.IOException, UnavailableDeviceException, ClosedDeviceException
startAcquisition
methods.
This method return silently if no asynchronous analog input acquisition is currently active.
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.void stopMonitoring() throws java.io.IOException, UnavailableDeviceException, ClosedDeviceException
startMonitoring
method.
This method return silently if no range monitoring is currently active.
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.Copyright © 2012, 2015, Oracle and/or its affiliates. All rights reserved.
Legal Notices