public interface ADCChannel extends Peripheral<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 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 PeripheralManager.open(id,...)
methods
using its ID or by a call to one of the
PeripheralManager.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
PeripheralManager.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 ClosedPeripheralException
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.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 |
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. |
close, getDescriptor, isOpen, tryLock, unlock
getInputBuffer, getOutputBuffer
int getMaxValue() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.int getMinSamplingInterval() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
setSamplingInterval
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.int getMinValue() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.int getSamplingInterval() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
setSamplingInterval
the peripheral
configuration-specific default value is returned.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.int acquire() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if another asynchronous acquisition is already active.void acquire(java.nio.IntBuffer dst) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.dst
- The buffer into which integer raw sampled input values are to be transferredjava.lang.NullPointerException
- If dst
is null
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral 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.double getVRefValue() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.void setSamplingInterval(int interval) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
interval
- the input sampling interval (in microseconds).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
)).UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalArgumentException
- if interval
is negative or zero.void startAcquisition(java.nio.IntBuffer dst, AcquisitionRoundListener listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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. 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.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.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral 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.void startAcquisition(java.nio.IntBuffer dst1, java.nio.IntBuffer dst2, AcquisitionRoundListener listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.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.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral 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.void startMonitoring(int low, int high, MonitoringListener listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.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
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral 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, UnavailablePeripheralException, ClosedPeripheralException
startAcquisition
methods.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.void stopMonitoring() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
startMonitoring
method.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another
application.ClosedPeripheralException
- if the peripheral has been closed.Copyright © 2012, 2014, Oracle and/or its affiliates. All rights reserved.
Legal Notices