com.acces.aiousb
Class AnalogInputSubsystem

java.lang.Object
  extended by com.acces.aiousb.AnalogInputSubsystem

public class AnalogInputSubsystem
extends java.lang.Object

Class AnalogInputSubsystem represents the analog input subsystem of a device. One accesses this analog input subsystem through its parent object, typically through a method such as adc() (see USB_AI16_Family.adc()).


Field Summary
static int CAL_MODE_GROUND
          Selects ground calibration mode (see setCalMode()).
static int CAL_MODE_NORMAL
          Selects normal measurement mode (see setCalMode()).
static int CAL_MODE_REFERENCE
          Selects reference (full scale) calibration mode (see setCalMode()).
static int CAL_TABLE_WORDS
          Number of 16-bit words in an A/D calibration table (65,536 16-bit words).
static int MAX_COUNTS
          Maximum number of counts A/D can read.
static int MIN_COUNTS
          Minimum number of counts A/D can read.
static int RANGE_0_10V
          Unipolar, 0-10 volt range (see setRange()).
static int RANGE_0_1V
          Unipolar, 0-1 volt range (see setRange()).
static int RANGE_0_2V
          Unipolar, 0-2 volt range (see setRange()).
static int RANGE_0_5V
          Unipolar, 0-5 volt range (see setRange()).
static int RANGE_10V
          Bipolar, -10 to +10 volt range (see setRange()).
static int RANGE_1V
          Bipolar, -1 to +1 volt range (see setRange()).
static int RANGE_2V
          Bipolar, -2 to +2 volt range (see setRange()).
static int RANGE_5V
          Bipolar, -5 to +5 volt range (see setRange()).
static int TRIG_MODE_CTR0_EXT
          If set, counter 0 is externally triggered (see setTriggerMode()).
static int TRIG_MODE_EXTERNAL
          If set, the A/D is triggered by an external pin on the board (see setTriggerMode()).
static int TRIG_MODE_FALLING_EDGE
          If set, the A/D is triggered by the falling edge of its trigger source, otherwise it's triggered by the rising edge (see setTriggerMode()).
static int TRIG_MODE_SCAN
          If set, each trigger will cause the A/D to scan all the channels, otherwise the A/D will read a single channel with each trigger (see setTriggerMode()).
static int TRIG_MODE_TIMER
          If set, the A/D is triggered by counter 2 (see setTriggerMode()).
 
Method Summary
 char[] calibrate(boolean autoCal, boolean returnCalTable, java.lang.String saveFileName)
          Calibrates the A/D, generating either a default table or using the internal voltage references to generate a calibration table.
 char[] calibrate(double[] points, boolean returnCalTable, java.lang.String saveFileName)
          Permits the A/D to be calibrated using an external voltage source.
 AnalogInputSubsystem clearFIFO(int method)
          Clears the streaming FIFO, using one of several different methods.
 double countsToVolts(int channel, char counts)
          Converts a single A/D count value to volts, based on the current gain setting for the specified channel.
 double[] countsToVolts(int startChannel, char[] counts)
          Converts an array of A/D count values to an array of voltage values, based on the current gain setting for each of the specified channels.
 int getCalMode()
          Gets the current calibration mode.
 int getChannelsPerGroup()
          Gets the number of analog input channels in each configuration group (1, 4 or 8 depending on the device model).
 double getClock()
          Gets the current clock frequency for timer-driven bulk reads (see setClock()).
 int getNumChannels()
          Gets the number of primary analog input channels.
 int getNumMUXChannels()
          Gets the number of analog input channels available through an optional multiplexer.
 int getOverSample()
          Gets the current number of over-samples.
 USBDevice getParent()
          Gets the parent device that this subsystem is part of.
 int getRange(int channel)
          Gets the current range for channel.
 int[] getRange(int startChannel, int numChannels)
          Gets the current range for multiple A/D channels.
static java.lang.String getRangeText(int range)
          Gets the textual string for the specified range.
 int getStreamingBlockSize()
          Gets the current streaming block size.
 int getTriggerMode()
          Gets the current trigger mode.
 boolean isAutoCalPresent(boolean force)
          Tells if automatic calibration is possible with this device.
 boolean isAutoConfig()
          Tells whether the modified configuration will be automatically sent to the device.
 boolean isDifferentialMode(int channel)
          Tells if channel is configured for single-ended or differential mode.
 boolean[] isDifferentialMode(int startChannel, int numChannels)
          Tells if multiple A/D channels are configured for single-ended or differential mode.
 boolean isDiscardFirstSample()
          Tells if the read(), readCounts() and readVolts() functions will discard the first A/D sample taken.
 java.io.PrintStream print(java.io.PrintStream stream)
          Prints the properties of this subsystem.
 AI16_DataSet read(int startChannel, int numChannels)
          Reads from multiple A/D channels and returns a data set containing both the data captured and the parameters in effect at the time the data was captured.
 char[] readBulkNext(int numSamples)
          Retrieves the next set of samples acquired during a bulk acquisition process initiated by readBulkStart().
 int readBulkSamplesAvailable()
          Gets the number of samples available to be retrieved during a bulk acquisition process initiated by readBulkStart().
 AnalogInputSubsystem readBulkStart(int startChannel, int numChannels, int numSamples)
          Starts a large A/D acquisition process in a background thread and returns immediately.
 AnalogInputSubsystem readConfig()
          Reads the A/D configuration from the device.
 char readCounts(int channel)
          Reads the A/D count value from a single channel.
 char[] readCounts(int startChannel, int numChannels)
          Reads the A/D count values from multiple channels.
 double readVolts(int channel)
          Reads the voltage from a single channel.
 double[] readVolts(int startChannel, int numChannels)
          Reads the voltage from multiple channels.
 AnalogInputSubsystem setAutoConfig(boolean autoConfig)
          Enables or disables automatically sending the modified configuration to the device.
 AnalogInputSubsystem setCalibrationTable(char[] calTable)
          Sets the calibration table in the A/D to the contents of calTable.
 AnalogInputSubsystem setCalibrationTable(java.lang.String fileName)
          Loads a calibration table from a file into the A/D.
 AnalogInputSubsystem setCalMode(int calMode)
          Sets the A/D calibration mode.
 AnalogInputSubsystem setClock(double clockHz)
          Sets the clock frequency for timer-driven bulk reads (see getClock() and readBulkStart()).
 AnalogInputSubsystem setDifferentialMode(int channel, boolean differentialMode)
          Sets a single A/D channel to differential or single-ended mode.
 AnalogInputSubsystem setDifferentialMode(int startChannel, boolean[] differentialMode)
          Sets multiple A/D channels to differential or single-ended mode.
 AnalogInputSubsystem setDiscardFirstSample(boolean discard)
          Specifies whether the read(), readCounts() and readVolts() functions will discard the first A/D sample taken.
 AnalogInputSubsystem setOverSample(int overSample)
          Sets the number of over-samples for all A/D channels.
 AnalogInputSubsystem setRange(int channel, int range)
          Sets the range for a single A/D channel.
 AnalogInputSubsystem setRange(int startChannel, int[] range)
          Sets the range for multiple A/D channels.
 AnalogInputSubsystem setRangeAndDiffMode(int range, boolean differentialMode)
          Sets all the A/D channels to the same range and differential mode.
 AnalogInputSubsystem setRangeAndDiffMode(int startChannel, int[] range, boolean[] differentialMode)
          Sets the range and differential mode for multiple A/D channels.
 AnalogInputSubsystem setRangeAndDiffMode(int channel, int range, boolean differentialMode)
          Sets the range and differential mode for a single A/D channel.
 AnalogInputSubsystem setStreamingBlockSize(int blockSize)
          Sets the streaming block size.
 AnalogInputSubsystem setTriggerMode(int triggerMode)
          Sets the trigger mode.
 char voltsToCounts(int channel, double volts)
          Converts a single voltage value to A/D counts, based on the current gain setting for the specified channel.
 char[] voltsToCounts(int startChannel, double[] volts)
          Converts an array of voltage values to an array of A/D count values, based on the current gain setting for each of the specified channels.
 AnalogInputSubsystem writeConfig()
          Writes the A/D configuration to the device.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CAL_MODE_NORMAL

public static final int CAL_MODE_NORMAL
Selects normal measurement mode (see setCalMode()).

See Also:
Constant Field Values

CAL_MODE_GROUND

public static final int CAL_MODE_GROUND
Selects ground calibration mode (see setCalMode()).

See Also:
Constant Field Values

CAL_MODE_REFERENCE

public static final int CAL_MODE_REFERENCE
Selects reference (full scale) calibration mode (see setCalMode()).

See Also:
Constant Field Values

TRIG_MODE_CTR0_EXT

public static final int TRIG_MODE_CTR0_EXT
If set, counter 0 is externally triggered (see setTriggerMode()).

See Also:
Constant Field Values

TRIG_MODE_FALLING_EDGE

public static final int TRIG_MODE_FALLING_EDGE
If set, the A/D is triggered by the falling edge of its trigger source, otherwise it's triggered by the rising edge (see setTriggerMode()).

See Also:
Constant Field Values

TRIG_MODE_SCAN

public static final int TRIG_MODE_SCAN
If set, each trigger will cause the A/D to scan all the channels, otherwise the A/D will read a single channel with each trigger (see setTriggerMode()).

See Also:
Constant Field Values

TRIG_MODE_EXTERNAL

public static final int TRIG_MODE_EXTERNAL
If set, the A/D is triggered by an external pin on the board (see setTriggerMode()).

See Also:
Constant Field Values

TRIG_MODE_TIMER

public static final int TRIG_MODE_TIMER
If set, the A/D is triggered by counter 2 (see setTriggerMode()).

See Also:
Constant Field Values

RANGE_0_10V

public static final int RANGE_0_10V
Unipolar, 0-10 volt range (see setRange()).

See Also:
Constant Field Values

RANGE_10V

public static final int RANGE_10V
Bipolar, -10 to +10 volt range (see setRange()).

See Also:
Constant Field Values

RANGE_0_5V

public static final int RANGE_0_5V
Unipolar, 0-5 volt range (see setRange()).

See Also:
Constant Field Values

RANGE_5V

public static final int RANGE_5V
Bipolar, -5 to +5 volt range (see setRange()).

See Also:
Constant Field Values

RANGE_0_2V

public static final int RANGE_0_2V
Unipolar, 0-2 volt range (see setRange()).

See Also:
Constant Field Values

RANGE_2V

public static final int RANGE_2V
Bipolar, -2 to +2 volt range (see setRange()).

See Also:
Constant Field Values

RANGE_0_1V

public static final int RANGE_0_1V
Unipolar, 0-1 volt range (see setRange()).

See Also:
Constant Field Values

RANGE_1V

public static final int RANGE_1V
Bipolar, -1 to +1 volt range (see setRange()).

See Also:
Constant Field Values

MIN_COUNTS

public static final int MIN_COUNTS
Minimum number of counts A/D can read.

See Also:
Constant Field Values

MAX_COUNTS

public static final int MAX_COUNTS
Maximum number of counts A/D can read.

See Also:
Constant Field Values

CAL_TABLE_WORDS

public static final int CAL_TABLE_WORDS
Number of 16-bit words in an A/D calibration table (65,536 16-bit words).

See Also:
Constant Field Values
Method Detail

print

public java.io.PrintStream print(java.io.PrintStream stream)
Prints the properties of this subsystem. Mainly useful for diagnostic purposes.

Parameters:
stream - the print stream where properties will be printed.
Returns:
The print stream.

getNumChannels

public int getNumChannels()
Gets the number of primary analog input channels.

Returns:
The number of channels, numbered 0 to n-1.

getNumMUXChannels

public int getNumMUXChannels()
Gets the number of analog input channels available through an optional multiplexer.

Returns:
The number of channels, numbered 0 to n-1.

getChannelsPerGroup

public int getChannelsPerGroup()
Gets the number of analog input channels in each configuration group (1, 4 or 8 depending on the device model).

Returns:
The number of channels per group.

isAutoCalPresent

public boolean isAutoCalPresent(boolean force)
Tells if automatic calibration is possible with this device.

Parameters:
force - True forces this class to interrogate the device anew; false returns the previous result if available, or interrogates the device if a previous result is not available.
Returns:
True indicates that automatic calibration is available.
Throws:
OperationFailedException
See Also:
calibrate()

getRangeText

public static java.lang.String getRangeText(int range)
Gets the textual string for the specified range.

Parameters:
range - the range for which to obtain the textual string.
Returns:
The textual string for the specified range.
Throws:
java.lang.IllegalArgumentException
See Also:
setRange()

isAutoConfig

public boolean isAutoConfig()
Tells whether the modified configuration will be automatically sent to the device.

Returns:
True indicates that the modified configuration will be automatically sent to the device, false indicates that you will have to explicitly call writeConfig() to send the configuration to the device.
See Also:
setAutoConfig()

setAutoConfig

public AnalogInputSubsystem setAutoConfig(boolean autoConfig)
Enables or disables automatically sending the modified configuration to the device. Normally, it's desirable to send the modified configuration to the device immediately. However, in order to reduce the amount of communication with the device while setting multiple properties, this automatic sending mechanism can be disabled and the configuration can be sent by explicitly calling writeConfig() once all the properties have been set, like so:
device.adc()
   .setAutoConfig( false )
   .setCalMode( AnalogInputSubsystem.CAL_MODE_NORMAL )
   .setTriggerMode( AnalogInputSubsystem.TRIG_MODE_SCAN | AnalogInputSubsystem.TRIG_MODE_TIMER )
   .setOverSample( 50 )
   .writeConfig()
   .setAutoConfig( true );
Remember to call setAutoConfig( true ) after configuring the properties, otherwise all subsequent configuration changes will have to be explicitly sent to the device by calling writeConfig().

Parameters:
autoConfig - True enables automatically sending modified configuration, false disables it.
Returns:
This subsystem, useful for chaining together multiple operations.

readConfig

public AnalogInputSubsystem readConfig()
Reads the A/D configuration from the device. This is done automatically when the class is instantiated, so it generally does not need to be done again. However, if the A/D configuration in the device has been changed without using this class (e.g. another program changed it), readConfig() can be used to copy the device's configuration into this class.

Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
OperationFailedException

writeConfig

public AnalogInputSubsystem writeConfig()
Writes the A/D configuration to the device. This is done automatically whenever the pertinent settings within this class are changed. However, if the A/D configuration in the device has been changed without using this class (e.g. another program changed it), or if automatic sending of the configuration has been disabled (see setAutoConfig()), then writeConfig() can be used to copy this class' configuration settings into the device.

Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
OperationFailedException

isDiscardFirstSample

public boolean isDiscardFirstSample()
Tells if the read(), readCounts() and readVolts() functions will discard the first A/D sample taken.

Returns:
False indicates that no samples will be discarded; true indicates that the first sample will be discarded.

setDiscardFirstSample

public AnalogInputSubsystem setDiscardFirstSample(boolean discard)
Specifies whether the read(), readCounts() and readVolts() functions will discard the first A/D sample taken. This setting does not pertain to the readBulkNext() function which returns all of the raw data captured. Discarding the first sample may be useful in cases in which voltage "residue" from reading a different channel affects the channel currently being read.

Parameters:
discard - false indicates that no samples will be discarded; true indicates that the first sample will be discarded.
Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
OperationFailedException

getCalMode

public int getCalMode()
Gets the current calibration mode.

Returns:
Current calibration mode (CAL_MODE_NORMAL, CAL_MODE_GROUND or CAL_MODE_REFERENCE).
See Also:
setCalMode()

setCalMode

public AnalogInputSubsystem setCalMode(int calMode)
Sets the A/D calibration mode. If ground or reference mode is selected, only one A/D sample may be taken at a time. That means, one channel and no oversampling. Attempting to read more than one channel or use an oversample setting of more than zero will result in a timeout error because the device will not send more than one sample. In order to protect users from accidentally falling into this trap, the read*() functions automatically and temporarily correct the scan parameters, restoring them when they complete.

Parameters:
calMode - the calibration mode. May be one of:
CAL_MODE_NORMAL
CAL_MODE_GROUND
CAL_MODE_REFERENCE
Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
java.lang.IllegalArgumentException

getTriggerMode

public int getTriggerMode()
Gets the current trigger mode.

Returns:
Current trigger mode (bitwise OR of TRIG_MODE_CTR0_EXT, TRIG_MODE_FALLING_EDGE, TRIG_MODE_SCAN, TRIG_MODE_EXTERNAL or TRIG_MODE_TIMER).
See Also:
setTriggerMode()

setTriggerMode

public AnalogInputSubsystem setTriggerMode(int triggerMode)
Sets the trigger mode.

Parameters:
triggerMode - a bitwise OR of these flags:
TRIG_MODE_CTR0_EXT
TRIG_MODE_FALLING_EDGE
TRIG_MODE_SCAN
TRIG_MODE_EXTERNAL
TRIG_MODE_TIMER
Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
java.lang.IllegalArgumentException

getRange

public int getRange(int channel)
Gets the current range for channel.

Parameters:
channel - the channel for which to obtain the current range.
Returns:
Current range for channel.
Throws:
java.lang.IllegalArgumentException
See Also:
setRange()

getRange

public int[] getRange(int startChannel,
                      int numChannels)
Gets the current range for multiple A/D channels.

Parameters:
startChannel - the first channel for which to obtain the current range.
numChannels - the number of channels for which to obtain the current range.
Returns:
Array containing the current ranges for the specified channels.
Throws:
java.lang.IllegalArgumentException
See Also:
setRange()

setRange

public AnalogInputSubsystem setRange(int channel,
                                     int range)
Sets the range for a single A/D channel.

Parameters:
channel - the channel for which to set the range.
range - the range (voltage range) for the channel. May be one of:
RANGE_0_1V
RANGE_1V
RANGE_0_2V
RANGE_2V
RANGE_0_5V
RANGE_5V
RANGE_0_10V
RANGE_10V
Returns:
This subsystem, useful for chaining together multiple operations.
See Also:
setDifferentialMode()

setRange

public AnalogInputSubsystem setRange(int startChannel,
                                     int[] range)
Sets the range for multiple A/D channels.

Parameters:
startChannel - the first channel for which to set the range.
range - an array of ranges, one per channel (see setRange()).
Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
java.lang.IllegalArgumentException

isDifferentialMode

public boolean isDifferentialMode(int channel)
Tells if channel is configured for single-ended or differential mode.

Parameters:
channel - the channel for which to obtain the current differential mode.
Returns:
Current range for channel.
Throws:
java.lang.IllegalArgumentException
See Also:
setDifferentialMode()

isDifferentialMode

public boolean[] isDifferentialMode(int startChannel,
                                    int numChannels)
Tells if multiple A/D channels are configured for single-ended or differential mode.

Parameters:
startChannel - the first channel for which to obtain the current differential mode.
numChannels - the number of channels for which to obtain the current differential mode.
Returns:
Array containing the current differential modes for the specified channels. False indicates channel is configured for single-ended mode and true indicates channel is configured for differential mode.
Throws:
java.lang.IllegalArgumentException
See Also:
setDifferentialMode()

setDifferentialMode

public AnalogInputSubsystem setDifferentialMode(int channel,
                                                boolean differentialMode)
Sets a single A/D channel to differential or single-ended mode.

When using differential mode, one should have a good understanding of how the hardware implements it. Considering the simple case of a device with only sixteen input channels, when differential mode is enabled for a channel, that channel is paired with another channel, eight higher than the one for which differential mode is enabled. For instance, if differential mode is enabled for channel 1, then it is paired with channel 9, meaning that channel 1 will return the voltage difference between channels 1 and 9, and channel 9 will no longer return a meaningful reading.

This scheme also means that enabling differential mode for channels 8-15 has no effect. In fact, if one attempts to enable differential mode for channels 8-15, nothing happens and if the differential mode setting is read back from the device for those channels, it will likely no longer be enabled! Further confusing matters is that some newer firmware does not clear the differential mode setting for channels 8-15, meaning that it will be returned from the device exactly as set even though it has no effect. So ... one should not rely on the differential mode setting for channels 8-15 to behave in a consistent or predictable manner.

For consistency and simplicity, one may read counts or volts from channels 8-15 even while differential mode is enabled, but the readings will not be meaningful. In differential mode, only the base channel (0-7) of the pair that's enabled for differential mode will return a meaningful reading. Channels 8-15 which are not enabled for differential mode will continue to return meaningful readings. For example, if differential mode is enabled for channel 1, then channel 1 will return a meaningful reading, channel 9 will not, and channels 8 and 10-15 will.

Considering the more complex case of a device such as the USB-AI16-64MA, which has an additional MUX affording 32 differential, or 64 single-ended inputs, things are a bit more complex. In this case, channels 0-3 share the same differential mode (and range) setting; channels 4-7 share the same setting; and so on. For the sake of simplicity and to support future designs which may have distinct settings for all channels, this software permits the differential mode (and range) to be specified for any MUXed channel, even though ultimately multiple channels may share the same setting. For example, on such a device as this, setting the differential mode (or range) of channel 1 also sets the differential mode (or range) of channels 0, 2 and 3.

There is yet another case to consider, that of devices such as the USB-AI16-128A. This device may have up to 128 channels, which share settings in groups of eight rather than four on the USB-AI16-64MA. Method getChannelsPerGroup() tells how many channels are grouped together on each device, and this topic is discussed more thoroughly in http://accesio.com/MANUALS/USB-AI FAMILY.PDF. The foregoing description also applies to the range setting, so one should refer to setRange() as well.

Parameters:
channel - the channel for which to set differential or single-ended mode.
differentialMode - false selects single-ended mode; true selects differential mode.
Returns:
This subsystem, useful for chaining together multiple operations.

setDifferentialMode

public AnalogInputSubsystem setDifferentialMode(int startChannel,
                                                boolean[] differentialMode)
Sets multiple A/D channels to differential or single-ended mode.

Parameters:
startChannel - the first channel for which to set differential or single-ended mode.
differentialMode - an array of mode selectors, one per channel. For each element in the array, false selects single-ended mode for that channel and true selects differential mode.
Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
java.lang.IllegalArgumentException

setRangeAndDiffMode

public AnalogInputSubsystem setRangeAndDiffMode(int channel,
                                                int range,
                                                boolean differentialMode)
Sets the range and differential mode for a single A/D channel.

Parameters:
channel - the channel for which to set the range.
range - the range (voltage range) for the channel (see setRange()).
differentialMode - false selects single-ended mode; true selects differential mode.
Returns:
This subsystem, useful for chaining together multiple operations.

setRangeAndDiffMode

public AnalogInputSubsystem setRangeAndDiffMode(int startChannel,
                                                int[] range,
                                                boolean[] differentialMode)
Sets the range and differential mode for multiple A/D channels.

Parameters:
startChannel - the first channel for which to set the range and differential mode.
range - an array of ranges, one per channel (see setRange()).
differentialMode - an array of mode selectors, one per channel. For each element in the array, false selects single-ended mode for that channel and true selects differential mode.
Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
java.lang.IllegalArgumentException

setRangeAndDiffMode

public AnalogInputSubsystem setRangeAndDiffMode(int range,
                                                boolean differentialMode)
Sets all the A/D channels to the same range and differential mode.

Parameters:
range - the range (voltage range) for the channels (see setRange()).
differentialMode - false selects single-ended mode; true selects differential mode.
Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
java.lang.IllegalArgumentException

getOverSample

public int getOverSample()
Gets the current number of over-samples.

Returns:
Current number of over-samples (0-255).
See Also:
setOverSample()

setOverSample

public AnalogInputSubsystem setOverSample(int overSample)
Sets the number of over-samples for all A/D channels.

Parameters:
overSample - number of over-samples (0-255).
Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
java.lang.IllegalArgumentException

setCalibrationTable

public AnalogInputSubsystem setCalibrationTable(java.lang.String fileName)
Loads a calibration table from a file into the A/D.

Parameters:
fileName - the name of a file containing the calibration table. A calibration table must consist of exactly 65,536 16-bit unsigned integers (see calibrate()).
Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
java.lang.IllegalArgumentException
OperationFailedException

setCalibrationTable

public AnalogInputSubsystem setCalibrationTable(char[] calTable)
Sets the calibration table in the A/D to the contents of calTable.

Parameters:
calTable - the calibration table to load. A calibration table must consist of exactly 65,536 16-bit unsigned integers (see calibrate()).
Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
java.lang.IllegalArgumentException
OperationFailedException

getStreamingBlockSize

public int getStreamingBlockSize()
Gets the current streaming block size.

Returns:
The current streaming block size. The value returned may not be the same as the value passed to setStreamingBlockSize() because that value is rounded up to a whole multiple of 512.
Throws:
OperationFailedException

setStreamingBlockSize

public AnalogInputSubsystem setStreamingBlockSize(int blockSize)
Sets the streaming block size.

Parameters:
blockSize - the streaming block size you wish to set. This will be rounded up to the next multiple of 512.
Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
java.lang.IllegalArgumentException
OperationFailedException

getClock

public double getClock()
Gets the current clock frequency for timer-driven bulk reads (see setClock()).

Returns:
The current frequency at which to take the samples (in Hertz).

setClock

public AnalogInputSubsystem setClock(double clockHz)
Sets the clock frequency for timer-driven bulk reads (see getClock() and readBulkStart()).

Parameters:
clockHz - the frequency at which to take the samples (in Hertz).
Returns:
This subsystem, useful for chaining together multiple operations.

calibrate

public char[] calibrate(boolean autoCal,
                        boolean returnCalTable,
                        java.lang.String saveFileName)
Calibrates the A/D, generating either a default table or using the internal voltage references to generate a calibration table.

Parameters:
autoCal - true uses the internal voltage references to automatically calibrate the A/D; false generates a default (uncalibrated) table.
returnCalTable - true causes calibrate() to return the generated calibration table; false returns an empty table.
saveFileName - the name of the file in which to save the generated calibration table. If null or empty, the generated calibration table is not saved to a file.
Returns:
If returnCalTable is true, an array of 65,536 16-bit unsigned integers representing the generated calibration table is returned; otherwise, an empty table (containing zero elements) is returned.
Throws:
OperationFailedException

calibrate

public char[] calibrate(double[] points,
                        boolean returnCalTable,
                        java.lang.String saveFileName)
Permits the A/D to be calibrated using an external voltage source. The proper way to use this function is to configure the A/D with a default calibration table (such as by calling calibrate( false ... )). Then inject a series of voltages into one of the A/D input channels, recording the count values reported by the A/D (by calling readCounts()). It's also a good idea to enable oversampling while recording these values in order to obtain the most stable readings. Alternatively, since points is an array of double values, you can obtain individual A/D count measurements and average them yourself, producing a double average, and put that value into the points array.

The points array consists of voltage-count pairs; points[0] is the first input voltage; points[1] is the corresponding count value measured by the A/D; points[2] and points[3] contain the second pair of voltage-count values; and so on. You can provide any number of pairs, although more than a few dozen is probably overkill, not to mention would take a lot of effort to acquire.

This calibration procedure uses the current gain A/D setting for channel 0, so it must be the same as that used to collect the measured A/D counts. It's recommended that all the channels be set to the same gain, the one that will be used during normal operation. The calibration is gain dependent, so switching the gain after calibrating may introduce slight offset or gain changes. So for best results, the A/D should be calibrated on the same gain setting that will be used during normal operation. You can create any number of calibration tables. If your application needs to switch between ranges, you may wish to create a separate calibration table for each range your application will use. Then when switching to a different range, the application can load the appropriate calibration table.

Although calibrating in this manner does take some effort, it produces the best results, eliminating all sources of error from the input pins onward. Furthermore, the calibration table can be saved to a file and reloaded into the A/D, ensuring consistency.

Parameters:
points - array of voltage-count pairs to calibrate the A/D with.
returnCalTable - true causes calibrate() to return the generated calibration table; false returns an empty table.
saveFileName - the name of the file in which to save the generated calibration table. If null or empty, the generated calibration table is not saved to a file.
Returns:
If returnCalTable is true, an array of 65,536 16-bit unsigned integers representing the generated calibration table is returned; otherwise, an empty table (containing zero elements) is returned.
Throws:
java.lang.IllegalArgumentException
OperationFailedException

read

public AI16_DataSet read(int startChannel,
                         int numChannels)
Reads from multiple A/D channels and returns a data set containing both the data captured and the parameters in effect at the time the data was captured. Whereas readCounts() and readVolts() also read data from multiple channels, they return only the raw data. read() returns a richer snapshot of the data.

Parameters:
startChannel - the first channel to read.
numChannels - the number of channels to read.
Returns:
A data set containing the samples and the sampling parameters.
Throws:
OperationFailedException

readCounts

public char readCounts(int channel)
Reads the A/D count value from a single channel.

Parameters:
channel - the channel to read.
Returns:
A/D counts (0-65,535). The meaning of these counts depends on the current A/D range of the channel (see setRange()). The count value may be converted to a voltage value using countsToVolts().

readCounts

public char[] readCounts(int startChannel,
                         int numChannels)
Reads the A/D count values from multiple channels.

Parameters:
startChannel - the first channel to read.
numChannels - the number of channels to read.
Returns:
An array of A/D counts (0-65,535), one per channel read. The meaning of these counts depends on the current A/D range of each channel (see setRange()). The array of count values may be converted to an array of voltage values using countsToVolts().
Throws:
OperationFailedException

readVolts

public double readVolts(int channel)
Reads the voltage from a single channel.

Parameters:
channel - the channel to read.
Returns:
A voltage value, limited to the current A/D range of the channel (see setRange()). The voltage value may be converted to a count value using voltsToCounts().

readVolts

public double[] readVolts(int startChannel,
                          int numChannels)
Reads the voltage from multiple channels.

Parameters:
startChannel - the first channel to read.
numChannels - the number of channels to read.
Returns:
An array of voltage values, one per channel read, each limited to the current A/D range of each channel (see setRange()). The array of voltage values may be converted to an array of count values using voltsToCounts().

readBulkStart

public AnalogInputSubsystem readBulkStart(int startChannel,
                                          int numChannels,
                                          int numSamples)
Starts a large A/D acquisition process in a background thread and returns immediately. The status of the acquisition process can be monitored using readBulkSamplesAvailable(), which returns the number of samples available to be retrieved by readBulkNext(). When the last of the data has been retrieved using readBulkNext(), the bulk acquisition process is automatically terminated and becomes ready to be used again.

While a bulk acquisition process is in progress, no functions of the device other than readBulkSamplesAvailable() or readBulkNext() should be used.

This example shows the proper way to configure the device for a large A/D acquisition process using the internal timer.
device.adc()
   .setStreamingBlockSize( 100000 )
   .setCalMode( AnalogInputSubsystem.CAL_MODE_NORMAL )
   .setTriggerMode( AnalogInputSubsystem.TRIG_MODE_SCAN | AnalogInputSubsystem.TRIG_MODE_TIMER )
   .setClock( 100000 )
   .readBulkStart( 1, 1, numSamples );
 do {
   char[] data = device.adc().readBulkNext( 20000 );
   ... do something with data ...
 } while( ...more data is available... );

Parameters:
startChannel - the first channel to read.
numChannels - the number of channels to read.
numSamples - the total number of samples to read.
Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
java.lang.IllegalArgumentException
OperationFailedException

readBulkSamplesAvailable

public int readBulkSamplesAvailable()
Gets the number of samples available to be retrieved during a bulk acquisition process initiated by readBulkStart().

Returns:
The number of samples available.
Throws:
OperationFailedException

readBulkNext

public char[] readBulkNext(int numSamples)
Retrieves the next set of samples acquired during a bulk acquisition process initiated by readBulkStart().

Parameters:
numSamples - the number of samples to retrieve.
Returns:
An array containing the number of samples requested, or all that are available. If fewer samples are available than are requested, only the samples available are returned. If zero samples are available, a zero-length array is returned.
Throws:
java.lang.IllegalArgumentException
OperationFailedException

clearFIFO

public AnalogInputSubsystem clearFIFO(int method)
Clears the streaming FIFO, using one of several different methods.

Parameters:
method - the method to use when clearing the FIFO. May be one of:
USBDevice.CLEAR_FIFO_METHOD_IMMEDIATE
USBDevice.CLEAR_FIFO_METHOD_AUTO
USBDevice.CLEAR_FIFO_METHOD_IMMEDIATE_AND_ABORT
USBDevice.CLEAR_FIFO_METHOD_WAIT
Returns:
This subsystem, useful for chaining together multiple operations.

countsToVolts

public double countsToVolts(int channel,
                            char counts)
Converts a single A/D count value to volts, based on the current gain setting for the specified channel. Be careful to ensure that the count value was actually obtained from the specified channel and that the gain hasn't changed since the count value was obtained.

Parameters:
channel - the channel number to use for converting counts to volts.
counts - the count value to convert to volts.
Returns:
A voltage value calculated using the current A/D range of the channel (see setRange()).
Throws:
java.lang.IllegalArgumentException

countsToVolts

public double[] countsToVolts(int startChannel,
                              char[] counts)
Converts an array of A/D count values to an array of voltage values, based on the current gain setting for each of the specified channels. This method is intended to convert an array of readings from sequential channels, such as might have been obtained from readCounts(). Be careful to ensure that the count values were actually obtained from the specified channels and that the gains havn't changed since the count values were obtained.

Parameters:
startChannel - the first channel number to use for converting counts to volts.
counts - the count values to convert to volts.
Returns:
An array of voltage values calculated using the current A/D range of each of the channels (see setRange()). The array returned has the same number of elements as counts.
Throws:
java.lang.IllegalArgumentException
OperationFailedException

voltsToCounts

public char voltsToCounts(int channel,
                          double volts)
Converts a single voltage value to A/D counts, based on the current gain setting for the specified channel. Be careful to ensure that the voltage value was actually obtained from the specified channel and that the gain hasn't changed since the voltage value was obtained.

Parameters:
channel - the channel number to use for converting volts to counts.
volts - the voltage value to convert to counts.
Returns:
A count value calculated using the current A/D range of the channel (see setRange()).
Throws:
java.lang.IllegalArgumentException

voltsToCounts

public char[] voltsToCounts(int startChannel,
                            double[] volts)
Converts an array of voltage values to an array of A/D count values, based on the current gain setting for each of the specified channels. This method is intended to convert an array of readings from sequential channels, such as might have been obtained from readVolts(). Be careful to ensure that the voltage values were actually obtained from the specified channels and that the gains havn't changed since the voltage values were obtained.

Parameters:
startChannel - the first channel number to use for converting volts to counts.
volts - the voltage values to convert to counts.
Returns:
An array of count values calculated using the current A/D range of each of the channels (see setRange()). The array returned has the same number of elements as volts.
Throws:
java.lang.IllegalArgumentException
OperationFailedException

getParent

public USBDevice getParent()
Gets the parent device that this subsystem is part of.

Returns:
The parent device that this subsystem is part of.