AIOUSB::AnalogInputSubsystem Class Reference

#include <AnalogInputSubsystem.hpp>

Inheritance diagram for AIOUSB::AnalogInputSubsystem:

Inheritance graph
[legend]
Collaboration diagram for AIOUSB::AnalogInputSubsystem:

Collaboration graph
[legend]

List of all members.

Public Member Functions

virtual std::ostream & print (std::ostream &out)
int getNumChannels () const
int getNumMUXChannels () const
int getChannelsPerGroup ()
bool isAutoCalPresent (bool force)
bool isAutoConfig () const
AnalogInputSubsystemsetAutoConfig (bool autoConfig)
AnalogInputSubsystemreadConfig ()
AnalogInputSubsystemwriteConfig ()
bool isDiscardFirstSample () const
AnalogInputSubsystemsetDiscardFirstSample (bool discard)
int getCalMode () const
AnalogInputSubsystemsetCalMode (int calMode)
int getTriggerMode () const
AnalogInputSubsystemsetTriggerMode (int triggerMode)
int getRange (int channel) const
IntArray getRange (int startChannel, int numChannels) const
AnalogInputSubsystemsetRange (int channel, int range)
AnalogInputSubsystemsetRange (int startChannel, const IntArray &range)
bool isDifferentialMode (int channel) const
BoolArray isDifferentialMode (int startChannel, int numChannels) const
AnalogInputSubsystemsetDifferentialMode (int channel, bool differentialMode)
AnalogInputSubsystemsetDifferentialMode (int startChannel, const BoolArray &differentialMode)
AnalogInputSubsystemsetRangeAndDiffMode (int channel, int range, bool differentialMode)
AnalogInputSubsystemsetRangeAndDiffMode (int startChannel, const IntArray &range, const BoolArray &differentialMode)
AnalogInputSubsystemsetRangeAndDiffMode (int range, bool differentialMode)
int getOverSample () const
AnalogInputSubsystemsetOverSample (int overSample)
AnalogInputSubsystemsetCalibrationTable (const std::string &fileName)
AnalogInputSubsystemsetCalibrationTable (const UShortArray &calTable)
int getStreamingBlockSize ()
AnalogInputSubsystemsetStreamingBlockSize (int blockSize)
double getClock ()
AnalogInputSubsystemsetClock (double clockHz)
UShortArray calibrate (bool autoCal, bool returnCalTable, const std::string &saveFileName)
UShortArray calibrate (const DoubleArray &points, bool returnCalTable, const std::string &saveFileName)
AI16_DataSetread (int startChannel, int numChannels)
unsigned short readCounts (int channel)
UShortArray readCounts (int startChannel, int numChannels)
double readVolts (int channel)
DoubleArray readVolts (int startChannel, int numChannels)
AnalogInputSubsystemreadBulkStart (int startChannel, int numChannels, int numSamples)
int readBulkSamplesAvailable ()
UShortArray readBulkNext (int numSamples)
AnalogInputSubsystemclearFIFO (int method)
double countsToVolts (int channel, unsigned short counts) const
DoubleArray countsToVolts (int startChannel, const UShortArray &counts) const
unsigned short voltsToCounts (int channel, double volts) const
UShortArray voltsToCounts (int startChannel, const DoubleArray &volts) const

Static Public Member Functions

static std::string getRangeText (int range)

Static Public Attributes

static const int CAL_MODE_NORMAL = 0
static const int CAL_MODE_GROUND = 1
static const int CAL_MODE_REFERENCE = 3
static const int TRIG_MODE_CTR0_EXT = 0x10
static const int TRIG_MODE_FALLING_EDGE = 0x08
static const int TRIG_MODE_SCAN = 0x04
static const int TRIG_MODE_EXTERNAL = 0x02
static const int TRIG_MODE_TIMER = 0x01
static const int RANGE_0_10V = 0
static const int RANGE_10V = 1
static const int RANGE_0_5V = 2
static const int RANGE_5V = 3
static const int RANGE_0_2V = 4
static const int RANGE_2V = 5
static const int RANGE_0_1V = 6
static const int RANGE_1V = 7
static const int MIN_COUNTS = 0
static const int MAX_COUNTS = 0xffff
static const int CAL_TABLE_WORDS = 64 * 1024

Protected Member Functions

AnalogInputSubsystemsetScanRange (int startChannel, int numChannels)
 AnalogInputSubsystem (USBDevice &parent)
virtual ~AnalogInputSubsystem ()

Protected Attributes

int numChannels
int numMUXChannels
int channelsPerGroup
int configBlockSize
int autoCalFeature
AI16_InputRangeinputRange
bool * differentialMode
int calMode
int triggerMode
int startChannel
int endChannel
int overSample
unsigned short * readBulkBuffer
int readBulkSamplesRequested
int readBulkSamplesRetrieved
bool autoConfig

Static Protected Attributes

static const char RANGE_TEXT [][10]
static const int NUM_CONFIG_REGISTERS = 20
static const int NUM_MUX_CONFIG_REGISTERS = 21
static const int NUM_GAIN_CODE_REGISTERS = 16
static const int REG_GAIN_CODE = 0
static const int REG_CAL_MODE = 16
static const int REG_TRIG_MODE = 17
static const int REG_START_END = 18
static const int REG_OVERSAMPLE = 19
static const int REG_MUX_START_END = 20
static const int DIFFERENTIAL_MODE = 8
static const int MAX_OVERSAMPLE = 0xff
static const int TRIG_MODE_VALID_MASK
static const int AUTO_CAL_UNKNOWN = 0
static const int AUTO_CAL_NOT_PRESENT = 1
static const int AUTO_CAL_PRESENT = 2
static const int MAX_CHANNELS = 128

Friends

class USB_AI16_Family


Detailed Description

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()).

Constructor & Destructor Documentation

AIOUSB::AnalogInputSubsystem::AnalogInputSubsystem ( USBDevice parent  )  [protected]

AIOUSB::AnalogInputSubsystem::~AnalogInputSubsystem (  )  [protected, virtual]


Member Function Documentation

UShortArray AIOUSB::AnalogInputSubsystem::calibrate ( const DoubleArray points,
bool  returnCalTable,
const std::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( bool autoCal, bool returnCalTable, const std::string &saveFileName )). 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( int channel )). 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 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.
Exceptions:
IllegalArgumentException 
OperationFailedException 

UShortArray AIOUSB::AnalogInputSubsystem::calibrate ( bool  autoCal,
bool  returnCalTable,
const std::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 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.
Exceptions:
OperationFailedException 

AnalogInputSubsystem& AIOUSB::AnalogInputSubsystem::clearFIFO ( int  method  )  [inline]

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.

DoubleArray AIOUSB::AnalogInputSubsystem::countsToVolts ( int  startChannel,
const UShortArray counts 
) const

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( int startChannel, int numChannels ). 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( int channel, int range )). The array returned has the same number of elements as counts.
Exceptions:
IllegalArgumentException 
OperationFailedException 

double AIOUSB::AnalogInputSubsystem::countsToVolts ( int  channel,
unsigned short  counts 
) const

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( int channel, int range )).
Exceptions:
IllegalArgumentException 

int AIOUSB::AnalogInputSubsystem::getCalMode (  )  const [inline]

int AIOUSB::AnalogInputSubsystem::getChannelsPerGroup (  )  [inline]

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.

double AIOUSB::AnalogInputSubsystem::getClock (  )  [inline]

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

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

int AIOUSB::AnalogInputSubsystem::getNumChannels (  )  const [inline]

Gets the number of primary analog input channels.

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

int AIOUSB::AnalogInputSubsystem::getNumMUXChannels (  )  const [inline]

Gets the number of analog input channels available through an optional multiplexer.

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

int AIOUSB::AnalogInputSubsystem::getOverSample (  )  const [inline]

Gets the current number of over-samples.

Returns:
Current number of over-samples (0-255).
See also:
setOverSample( int oversample )

IntArray AIOUSB::AnalogInputSubsystem::getRange ( int  startChannel,
int  numChannels 
) const

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.
See also:
setRange( int startChannel, const IntArray &range )
Exceptions:
IllegalArgumentException 

int AIOUSB::AnalogInputSubsystem::getRange ( int  channel  )  const

Gets the current range for channel.

Parameters:
channel the channel for which to obtain the current range.
Returns:
Current range for channel.
See also:
setRange( int channel, int range )
Exceptions:
IllegalArgumentException 

std::string AIOUSB::AnalogInputSubsystem::getRangeText ( int  range  )  [static]

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.
See also:
setRange( int channel, int range )
Exceptions:
IllegalArgumentException 

int AIOUSB::AnalogInputSubsystem::getStreamingBlockSize (  )  [inline]

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( int blockSize ) because that value is rounded up to a whole multiple of 512.
Exceptions:
OperationFailedException 

int AIOUSB::AnalogInputSubsystem::getTriggerMode (  )  const [inline]

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( int triggerMode )

bool AIOUSB::AnalogInputSubsystem::isAutoCalPresent ( bool  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.
See also:
calibrate( bool autoCal, bool returnCalTable, const std::string &saveFileName )
Exceptions:
OperationFailedException 

bool AIOUSB::AnalogInputSubsystem::isAutoConfig (  )  const [inline]

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( bool autoConfig )

BoolArray AIOUSB::AnalogInputSubsystem::isDifferentialMode ( int  startChannel,
int  numChannels 
) const

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.
See also:
setDifferentialMode( int startChannel, const BoolArray &differentialMode )
Exceptions:
IllegalArgumentException 

bool AIOUSB::AnalogInputSubsystem::isDifferentialMode ( int  channel  )  const

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.

False indicates single-ended mode; true indicates differential mode.

See also:
setDifferentialMode( int channel, boolean differentialMode )
Exceptions:
IllegalArgumentException 

bool AIOUSB::AnalogInputSubsystem::isDiscardFirstSample (  )  const

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.

ostream & AIOUSB::AnalogInputSubsystem::print ( std::ostream &  out  )  [virtual]

Prints the properties of this subsystem. Mainly useful for diagnostic purposes.

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

Implements AIOUSB::DeviceSubsystem.

AI16_DataSet * AIOUSB::AnalogInputSubsystem::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( int startChannel, int numChannels ) and readVolts( int startChannel, int numChannels ) 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.
Exceptions:
OperationFailedException 

UShortArray AIOUSB::AnalogInputSubsystem::readBulkNext ( int  numSamples  ) 

Retrieves the next set of samples acquired during a bulk acquisition process initiated by readBulkStart( int startChannel, int numChannels, int numSamples ).

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.
Exceptions:
IllegalArgumentException 
OperationFailedException 

int AIOUSB::AnalogInputSubsystem::readBulkSamplesAvailable (  ) 

Gets the number of samples available to be retrieved during a bulk acquisition process initiated by readBulkStart( int startChannel, int numChannels, int numSamples ).

Returns:
The number of samples available.
Exceptions:
OperationFailedException 

AnalogInputSubsystem & AIOUSB::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( int numSamples ). 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 {
   UShortArray 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.
Exceptions:
IllegalArgumentException 
OperationFailedException 

AnalogInputSubsystem & AIOUSB::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.
Exceptions:
OperationFailedException 

UShortArray AIOUSB::AnalogInputSubsystem::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( int channel, int range )). The array of count values may be converted to an array of voltage values using countsToVolts( int startChannel, const UShortArray &counts ) const.
Exceptions:
OperationFailedException 

unsigned short AIOUSB::AnalogInputSubsystem::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( int channel, int range )). The count value may be converted to a voltage value using countsToVolts( int channel, unsigned short counts ) const.

DoubleArray AIOUSB::AnalogInputSubsystem::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( int channel, int range )). The array of voltage values may be converted to an array of count values using voltsToCounts( int startChannel, const DoubleArray &volts ) const.

double AIOUSB::AnalogInputSubsystem::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( int channel, int range )). The voltage value may be converted to a count value using voltsToCounts( int channel, double volts ) const.

AnalogInputSubsystem& AIOUSB::AnalogInputSubsystem::setAutoConfig ( bool  autoConfig  )  [inline]

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.

AnalogInputSubsystem & AIOUSB::AnalogInputSubsystem::setCalibrationTable ( const UShortArray 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( bool autoCal, bool returnCalTable, const std::string &saveFileName )).
Returns:
This subsystem, useful for chaining together multiple operations.
Exceptions:
IllegalArgumentException 
OperationFailedException 

AnalogInputSubsystem & AIOUSB::AnalogInputSubsystem::setCalibrationTable ( const std::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( bool autoCal, bool returnCalTable, const std::string &saveFileName )).
Returns:
This subsystem, useful for chaining together multiple operations.
Exceptions:
IllegalArgumentException 
OperationFailedException 

AnalogInputSubsystem & AIOUSB::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:
AnalogInputSubsystem::CAL_MODE_NORMAL
AnalogInputSubsystem::CAL_MODE_GROUND
AnalogInputSubsystem::CAL_MODE_REFERENCE
Returns:
This subsystem, useful for chaining together multiple operations.
Exceptions:
IllegalArgumentException 

AnalogInputSubsystem& AIOUSB::AnalogInputSubsystem::setClock ( double  clockHz  )  [inline]

Sets the clock frequency for timer-driven bulk reads (see getClock() and readBulkStart( int startChannel, int numChannels, int numSamples )).

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

AnalogInputSubsystem & AIOUSB::AnalogInputSubsystem::setDifferentialMode ( int  startChannel,
const BoolArray 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.
Exceptions:
IllegalArgumentException 

AnalogInputSubsystem & AIOUSB::AnalogInputSubsystem::setDifferentialMode ( int  channel,
bool  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( int channel, int range ) 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.

AnalogInputSubsystem & AIOUSB::AnalogInputSubsystem::setDiscardFirstSample ( bool  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.
Exceptions:
OperationFailedException 

AnalogInputSubsystem & AIOUSB::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.
Exceptions:
IllegalArgumentException 

AnalogInputSubsystem & AIOUSB::AnalogInputSubsystem::setRange ( int  startChannel,
const IntArray 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( int channel, int range )).
Returns:
This subsystem, useful for chaining together multiple operations.
Exceptions:
IllegalArgumentException 

AnalogInputSubsystem & AIOUSB::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:
AnalogInputSubsystem::RANGE_0_1V
AnalogInputSubsystem::RANGE_1V
AnalogInputSubsystem::RANGE_0_2V
AnalogInputSubsystem::RANGE_2V
AnalogInputSubsystem::RANGE_0_5V
AnalogInputSubsystem::RANGE_5V
AnalogInputSubsystem::RANGE_0_10V
AnalogInputSubsystem::RANGE_10V
Returns:
This subsystem, useful for chaining together multiple operations.
See also:
setDifferentialMode( int channel, bool differentialMode )

AnalogInputSubsystem & AIOUSB::AnalogInputSubsystem::setRangeAndDiffMode ( int  range,
bool  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( int channel, int range )).
differentialMode false selects single-ended mode; true selects differential mode.
Returns:
This subsystem, useful for chaining together multiple operations.
Exceptions:
IllegalArgumentException 

AnalogInputSubsystem & AIOUSB::AnalogInputSubsystem::setRangeAndDiffMode ( int  startChannel,
const IntArray range,
const BoolArray 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( int channel, int range )).
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.
Exceptions:
IllegalArgumentException 

AnalogInputSubsystem & AIOUSB::AnalogInputSubsystem::setRangeAndDiffMode ( int  channel,
int  range,
bool  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( int channel, int range )).
differentialMode false selects single-ended mode; true selects differential mode.
Returns:
This subsystem, useful for chaining together multiple operations.

AnalogInputSubsystem & AIOUSB::AnalogInputSubsystem::setScanRange ( int  startChannel,
int  numChannels 
) [protected]

AnalogInputSubsystem& AIOUSB::AnalogInputSubsystem::setStreamingBlockSize ( int  blockSize  )  [inline]

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.
Exceptions:
IllegalArgumentException 
OperationFailedException 

AnalogInputSubsystem & AIOUSB::AnalogInputSubsystem::setTriggerMode ( int  triggerMode  ) 

Sets the trigger mode.

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

UShortArray AIOUSB::AnalogInputSubsystem::voltsToCounts ( int  startChannel,
const DoubleArray volts 
) const

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( int startChannel, int numChannels ). 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( int channel, int range )). The array returned has the same number of elements as volts.
Exceptions:
IllegalArgumentException 
OperationFailedException 

unsigned short AIOUSB::AnalogInputSubsystem::voltsToCounts ( int  channel,
double  volts 
) const

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( int channel, int range )).
Exceptions:
IllegalArgumentException 

AnalogInputSubsystem & AIOUSB::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( bool autoConfig )), then writeConfig() can be used to copy this class' configuration settings into the device.

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


Friends And Related Function Documentation

friend class USB_AI16_Family [friend]


Member Data Documentation

const int AIOUSB::AnalogInputSubsystem::AUTO_CAL_NOT_PRESENT = 1 [static, protected]

const int AIOUSB::AnalogInputSubsystem::AUTO_CAL_PRESENT = 2 [static, protected]

const int AIOUSB::AnalogInputSubsystem::AUTO_CAL_UNKNOWN = 0 [static, protected]

Selects ground calibration mode (see setCalMode( int calMode )).

Selects normal measurement mode (see setCalMode( int calMode )).

Selects reference (full scale) calibration mode (see setCalMode( int calMode )).

const int AIOUSB::AnalogInputSubsystem::CAL_TABLE_WORDS = 64 * 1024 [static]

Number of 16-bit words in an A/D calibration table (65,536 16-bit words).

const int AIOUSB::AnalogInputSubsystem::DIFFERENTIAL_MODE = 8 [static, protected]

const int AIOUSB::AnalogInputSubsystem::MAX_CHANNELS = 128 [static, protected]

const int AIOUSB::AnalogInputSubsystem::MAX_COUNTS = 0xffff [static]

Maximum number of counts A/D can read.

const int AIOUSB::AnalogInputSubsystem::MAX_OVERSAMPLE = 0xff [static, protected]

Minimum number of counts A/D can read.

const int AIOUSB::AnalogInputSubsystem::NUM_CONFIG_REGISTERS = 20 [static, protected]

const int AIOUSB::AnalogInputSubsystem::NUM_GAIN_CODE_REGISTERS = 16 [static, protected]

const int AIOUSB::AnalogInputSubsystem::NUM_MUX_CONFIG_REGISTERS = 21 [static, protected]

Unipolar, 0-10 volt range (see setRange( int channel, int range )).

Unipolar, 0-1 volt range (see setRange( int channel, int range )).

Unipolar, 0-2 volt range (see setRange( int channel, int range )).

Unipolar, 0-5 volt range (see setRange( int channel, int range )).

Bipolar, -10 to +10 volt range (see setRange( int channel, int range )).

Bipolar, -1 to +1 volt range (see setRange( int channel, int range )).

Bipolar, -2 to +2 volt range (see setRange( int channel, int range )).

Bipolar, -5 to +5 volt range (see setRange( int channel, int range )).

const char AIOUSB::AnalogInputSubsystem::RANGE_TEXT [static, protected]

Initial value:

 {
    
      "0-10V"
    , "+/-10V"
    , "0-5V"
    , "+/-5V"
    , "0-2V"
    , "+/-2V"
    , "0-1V"
    , "+/-1V"
}

unsigned short* AIOUSB::AnalogInputSubsystem::readBulkBuffer [protected]

const int AIOUSB::AnalogInputSubsystem::REG_CAL_MODE = 16 [static, protected]

const int AIOUSB::AnalogInputSubsystem::REG_GAIN_CODE = 0 [static, protected]

const int AIOUSB::AnalogInputSubsystem::REG_MUX_START_END = 20 [static, protected]

const int AIOUSB::AnalogInputSubsystem::REG_OVERSAMPLE = 19 [static, protected]

const int AIOUSB::AnalogInputSubsystem::REG_START_END = 18 [static, protected]

const int AIOUSB::AnalogInputSubsystem::REG_TRIG_MODE = 17 [static, protected]

If set, counter 0 is externally triggered (see setTriggerMode( int triggerMode )).

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

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( int triggerMode )).

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( int triggerMode )).

If set, the A/D is triggered by counter 2 (see setTriggerMode( int triggerMode )).


doxygen