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 ADCChannel.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) . |
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(int)
.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(int)
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 a 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, that is, dst1.remaining()
, at the moment this method is invoked.
Suppose that a 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.
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 buffer has been filled with raw sampled input
values and reading will asynchronously proceed with the alternate buffer (which becomes the 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).
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, 2013, Oracle and/or its affiliates. All rights reserved.
Legal Notices