public interface ADCChannel extends Peripheral
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()
.
Each ADC channel is identified by a numerical ID and by a name.
An ADCChannel
instance can be opened by a call to one of the PeripheralManager.open()
methods.
Once opened, an application can read the current sampled input value of an ADC channel by calling the
getValue()
method or can acquire the input values sampled over a period of time by calling the
getValues(int[], int, int)
method.
An application can also asynchronously acquire the input values sampled at a certain rate by calling the
startAcquisition
methods with a
AcquisitionListener
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.
Only one acquisition (synchronous or asynchronous) and one monitoring can be going on at any time. One acquisition
and one monitoring can be performed concurrently 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 release the ADC channel. Any further attempt to set or get the value of a ADC channel which has been closed will
result in a PeripheralNotAvailableException
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.AcquisitionListener
,
MonitoringListener
BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN, UNDEFINED_ID
Modifier and Type | Method and Description |
---|---|
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).
|
int |
getValue()
Reads the current raw sampled input value of this channel.
|
void |
getValues(int[] buffer,
int offset,
int count)
Reads
count raw sampled input values from this channel and copies them into the designated array. |
double |
getVRefValue()
Returns the Reference Voltage value of this ADC channel.
|
void |
setSamplingInterval(int interval)
Sets the input sampling interval (in microseconds).
|
void |
startAcquisition(int[] buffer,
int offset,
int count,
boolean doubleBuffering,
AcquisitionListener 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 the
startAcquisition method. |
void |
stopMonitoring()
Stops the range monitoring of this channel analog input as started by a call to the
startMonitoring() method. |
close, getID, getName, getProperties, isOpen
int getMaxValue() throws java.io.IOException, PeripheralNotAvailableException
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 an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).int getMinSamplingInterval() throws java.io.IOException, PeripheralNotAvailableException
setSamplingInterval(int)
.java.io.IOException
- if an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).int getMinValue() throws java.io.IOException, PeripheralNotAvailableException
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 an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).int getSamplingInterval() throws java.io.IOException, PeripheralNotAvailableException
setSamplingInterval(int)
the peripheral configuration-specific default value is returned.java.io.IOException
- if an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).int getValue() throws java.io.IOException, PeripheralNotAvailableException
java.io.IOException
- if an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).void getValues(int[] buffer, int offset, int count) throws java.io.IOException, PeripheralNotAvailableException
count
raw sampled input values from this channel and copies them into the designated array.
The input will be sampled according to the current input sampling interval as returned by
getSamplingInterval()
.
This method may be invoked at any time. If another thread has already initiated an I/O operation 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.buffer
- the buffer for the sampled input values to be read.offset
- the offset in buffer
where to start copying the sampled input values.count
- the number of sampled input values to read.java.io.IOException
- if an IO error occurred.java.lang.NullPointerException
- If buffer
is null
.java.lang.IndexOutOfBoundsException
- offset
or count
points or results in pointing outside buffer
.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).InvalidStateException
- if an asynchronous acquisition is already active.double getVRefValue() throws java.io.IOException, PeripheralNotAvailableException
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 an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).void setSamplingInterval(int interval) throws java.io.IOException, PeripheralNotAvailableException
interval
- the input sampling interval (in microseconds).java.io.IOException
- if an IO error occurred.InvalidInputSamplingRateException
- if the resulting sampling rate is higher than the maximum supported sampling rate.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).java.lang.IllegalArgumentException
- if interval
is negative or null.void startAcquisition(int[] buffer, int offset, int count, boolean doubleBuffering, AcquisitionListener listener) throws java.io.IOException, PeripheralNotAvailableException
AcquisitionListener
instance is cyclicly notified when count
raw sampled input values
have been read from this channel. The read values are copied into the designated section of the provided buffer.
Once count
raw sampled input values have 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()
.
If double buffering is enabled, notification will happen when ( count
/ 2) raw sampled input values have
been read and reading will proceed with the other half of the designated section of the provided 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). if count
is not even then one part of the
designated buffer section may be longer (by 1
) than the other one.
The analog 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.buffer
- the buffer for the sampled input values to be read.offset
- the offset in buffer
where to start copying the sampled input values.count
- the number of sampled input values to read.doubleBuffering
- whether double buffering should be used.listener
- the AcquisitionListener
instance to be notified when all the sampled input values have been
read.java.io.IOException
- if an IO error occurred.java.lang.NullPointerException
- if listener
is null
.java.lang.IndexOutOfBoundsException
- if offset
or count
points or results in pointing outside buffer
.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).InvalidStateException
- if another synchronous or asynchronous acquisition is already active.void startMonitoring(int low, int high, MonitoringListener listener) throws java.io.IOException, PeripheralNotAvailableException
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 an IO error occurred.java.lang.IllegalArgumentException
- if low
is greater than high
.java.lang.NullPointerException
- if listener
is null
.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).InvalidStateException
- if monitoring is already active.void stopAcquisition() throws java.io.IOException, PeripheralNotAvailableException
startAcquisition
method.java.io.IOException
- if an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).void stopMonitoring() throws java.io.IOException, PeripheralNotAvailableException
startMonitoring()
method.java.io.IOException
- if an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).Copyright (c) 1990, 2013, Oracle and/or its affiliates. All rights reserved.