Public Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
SurgSim::Device::LabJackDevice Class Reference

A class implementing the communication with a LabJack data acquisition (DAQ) device. More...

#include <SurgSim/Devices/LabJack/LabJackDevice.h>

Inheritance diagram for SurgSim::Device::LabJackDevice:
SurgSim::Input::CommonDevice SurgSim::Input::DeviceInterface

Public Member Functions

 LabJackDevice (const std::string &uniqueName)
 Constructor. More...
 
virtual ~LabJackDevice ()
 Destructor. More...
 
virtual bool initialize () override
 Fully initialize the device. More...
 
bool isInitialized () const
 Check whether this device is initialized. More...
 
void setModel (LabJack::Model model)
 Set the model, e.g., U6. More...
 
LabJack::Model getModel () const
 
void setConnection (LabJack::Connection connection)
 Set the connection type of the LabJack, e.g., USB. More...
 
LabJack::Connection getConnection () const
 
void setAddress (std::string address)
 Set the address of the LabJack, e.g., "1" or "192.168.7.23". More...
 
const std::string & getAddress () const
 
void enableDigitalInput (int channel)
 Enable digital input line. More...
 
void setDigitalInputs (const std::unordered_set< int > &digitalInputChannels)
 Set which digital input lines are enabled. More...
 
const std::unordered_set< int > & getDigitalInputs () const
 
void enableDigitalOutput (int channel)
 Enable digital output line. More...
 
void setDigitalOutputs (const std::unordered_set< int > &digitalOutputChannels)
 Set which digital output lines are enabled. More...
 
const std::unordered_set< int > & getDigitalOutputs () const
 
void setTimerBase (LabJack::TimerBase base)
 Set the timer base rate. More...
 
LabJack::TimerBase getTimerBase () const
 
void setTimerClockDivisor (int divisor)
 If the Timer type ends in "_DIV", then the actual timer frequency is divided by the divisor. More...
 
int getTimerClockDivisor () const
 
void setTimerCounterPinOffset (int offset)
 The timers and counters are always on consecutive pins, but the start pin can be varied within limits. More...
 
int getTimerCounterPinOffset () const
 
void enableTimer (int index, LabJack::TimerMode mode)
 Enable timer. More...
 
void enableTimer (int index, LabJack::TimerMode mode, int initialValue)
 Enable timer with an initial value. More...
 
void setTimers (const std::unordered_map< int, LabJack::TimerSettings > &timers)
 Set which timers are enabled. More...
 
const std::unordered_map< int, LabJack::TimerSettings > & getTimers () const
 
void setMaximumUpdateRate (double rate)
 Set the maximum update rate for the LabJackThread. More...
 
double getMaximumUpdateRate () const
 
void enableAnalogInput (int positiveChannel, LabJack::Range range, int negativeChannel)
 Enable differential analog input. More...
 
void enableAnalogInput (int channel, LabJack::Range range)
 Enable single-ended analog input. More...
 
void setAnalogInputs (const std::unordered_map< int, LabJack::AnalogInputSettings > &analogInputs)
 Set which analog inputs are enabled. More...
 
const std::unordered_map< int, LabJack::AnalogInputSettings > & getAnalogInputs () const
 
void enableAnalogOutput (int channel)
 Enable analog output. More...
 
void setAnalogOutputs (const std::unordered_set< int > &analogOutputChannels)
 Set which analog outputs are enabled. More...
 
const std::unordered_set< int > & getAnalogOutputs () const
 
void setAnalogInputResolution (int resolution)
 Set the resolution for all the analog inputs. More...
 
int getAnalogInputResolution () const
 
void setAnalogInputSettling (int settling)
 Set the settling time for all the analog inputs. More...
 
int getAnalogInputSettling () const
 
- Public Member Functions inherited from SurgSim::Input::CommonDevice
 CommonDevice (const std::string &name)
 Constructor. More...
 
 CommonDevice (const std::string &name, const SurgSim::DataStructures::DataGroup &inputData)
 Constructor. More...
 
 CommonDevice (const std::string &name, SurgSim::DataStructures::DataGroup &&inputData)
 Constructor. More...
 
virtual ~CommonDevice ()
 Destructor. More...
 
virtual std::string getName () const override
 Return a (hopefully unique) device name. More...
 
void setNameForCallback (const std::string &name)
 Set the name used for calling the input consumers and output producer. More...
 
std::string getNameForCallback () const
 Get the name used for calling the input consumers and output producer. More...
 
virtual bool addInputConsumer (std::shared_ptr< InputConsumerInterface > inputConsumer) override
 Connect this device to an InputConsumerInterface, which will receive the data that comes from this device. More...
 
virtual bool removeInputConsumer (std::shared_ptr< InputConsumerInterface > inputConsumer) override
 Disconnect this device from an InputConsumerInterface, which will no longer receive data from this device. More...
 
virtual bool setOutputProducer (std::shared_ptr< OutputProducerInterface > outputProducer) override
 Connect this device to an OutputProducerInterface, which will send data to this device. More...
 
virtual bool removeOutputProducer (std::shared_ptr< OutputProducerInterface > outputProducer) override
 Disconnect this device from an OutputProducerInterface, which will no longer send data to this device. More...
 
virtual bool hasOutputProducer () override
 Getter for whether or not this device is connected with an OutputProducerInterface. More...
 
- Public Member Functions inherited from SurgSim::Input::DeviceInterface
virtual ~DeviceInterface ()
 Virtual destructor (empty). More...
 

Private Member Functions

virtual bool finalize () override
 Finalize (de-initialize) the device. More...
 

Private Attributes

std::shared_ptr< LabJackScaffoldm_scaffold
 The single scaffold object that handles communications with all instances of LabJackDevice. More...
 
LabJack::Model m_model
 The model, e.g., U6. More...
 
LabJack::Connection m_connection
 The type of communication connection, e.g., USB. More...
 
std::string m_address
 The address, or a zero-length string to indicate the first-found device of this type on this connection. More...
 
std::unordered_set< int > m_digitalInputChannels
 The line numbers for the digital inputs. More...
 
std::unordered_map< int, LabJack::AnalogInputSettingsm_analogInputs
 The analog inputs. The key is the positive channel. More...
 
std::unordered_set< int > m_digitalOutputChannels
 The line numbers for the digital outputs. More...
 
std::unordered_set< int > m_analogOutputChannels
 The line numbers for the analog outputs. More...
 
LabJack::TimerBase m_timerBase
 The timer base, which is the frequency of all the output timers unless it ends in "_DIV", in which case the frequency is the base divided by the divisor. More...
 
int m_timerClockDivisor
 The timer clock's divisor, see m_timerBase. More...
 
int m_timerCounterPinOffset
 The number of the lowest FIO pin that is a timer or counter. More...
 
std::unordered_map< int, LabJack::TimerSettingsm_timers
 A map from the timers' line numbers to their mode and optional initial value. More...
 
double m_threadRate
 The maximum update rate for the LabJackThread. More...
 
int m_analogInputResolution
 The resolution for all the analog inputs. More...
 
int m_analogInputSettling
 The settling time for all the analog inputs. More...
 

Friends

class LabJackScaffold
 

Additional Inherited Members

- Protected Member Functions inherited from SurgSim::Input::CommonDevice
virtual void pushInput ()
 Push application input to consumers. More...
 
virtual bool pullOutput ()
 Pull application output from a producer. More...
 
SurgSim::DataStructures::DataGroupgetInputData ()
 Getter for the input data DataGroup. More...
 
const SurgSim::DataStructures::DataGroupgetOutputData () const
 Getter for the output data DataGroup. More...
 

Detailed Description

A class implementing the communication with a LabJack data acquisition (DAQ) device.

Should work for the U3, U6, and U9 models on Windows and the U3 and U6 on Linux. See the manual(s) for your LabJack device(s) to understand the input and output data, the configuration parameters, timing limitations, etc. The various parameters and inputs are almost always passed through unchanged to the device driver. Timers, digital input/output, and analog input/output are supported. Currently not supported are counters, using the same channel as the positive channel for multiple analog inputs, and reconfiguring the device after initialization.

Warning
The LabJack device is configurable to such a degree that neither this class nor LabJackScaffold are able to do significant error-checking. If the output DataGroup and the calls (e.g., addTimer) to this class are not in agreement, the requests to the LabJack device driver will not be correct.
Application input provided by the device:
type name
scalar "analogInput0" Analog input with AIN0 as the positive channel
scalar "analogInput" Analog input with AIN1 as the positive channel
... ... ...
scalar "analogInput16" Analog input with AIN16 as the positive channel
boolean"digitalInput0" Digital input, line #0, true for high input, false for low
boolean"digitalInput1" Digital input, line #1, true for high input, false for low
... ... ...
boolean"digitalInput23" Digital input, line #23, true for high input, false for low
scalar "timerInput0" The input from timer #0 if that timer provides input values
scalar "timerInput1" The input from timer #1 if that timer provides input values
... ... ...
scalar "timerInput6" The input from timer #6 if that timer provides input values
Application output used by the device:
type name
scalar "analogOutput0" Analog output, DAC0
scalar "analogOutput1" Analog output, DAC1
boolean"digitalOutput0" Digital output, line #0, true for high output, false for low
boolean"digitalOutput1" Digital output, line #1, true for high output, false for low
... ... ...
boolean"digitalOutput23" Digital output, line #23, true for high output, false for low
scalar "timerOutput0" The output for timer #0 if that timer accepts output values
scalar "timerOutput1" The output for timer #1 if that timer accepts output values
... ... ...
scalar "timerOutput6" The output for timer #6 if that timer accepts output values
See also
SurgSim::Input::CommonDevice, SurgSim::Input::DeviceInterface, LabJackScaffold

Constructor & Destructor Documentation

SurgSim::Device::LabJackDevice::LabJackDevice ( const std::string &  uniqueName)
explicit

Constructor.

Parameters
uniqueNameA unique name for the device that will be used by the application.
SurgSim::Device::LabJackDevice::~LabJackDevice ( )
virtual

Destructor.

Member Function Documentation

void SurgSim::Device::LabJackDevice::enableAnalogInput ( int  positiveChannel,
LabJack::Range  range,
int  negativeChannel 
)

Enable differential analog input.

Parameters
positiveChannelThe positive channel.
rangeThe voltage range.
negativeChannelThe negative channel.
Exceptions
Assertsif already initialized.
Note
On Linux, does not correctly handle negative channels 31 or 32 for U3 model.
void SurgSim::Device::LabJackDevice::enableAnalogInput ( int  channel,
LabJack::Range  range 
)

Enable single-ended analog input.

Parameters
channelThe channel.
rangeThe voltage range.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::enableAnalogOutput ( int  channel)

Enable analog output.

Parameters
channelThe channel.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::enableDigitalInput ( int  channel)

Enable digital input line.

Parameters
channelThe channel number.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::enableDigitalOutput ( int  channel)

Enable digital output line.

Parameters
channelThe channel number.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::enableTimer ( int  index,
LabJack::TimerMode  mode 
)

Enable timer.

Since quadrature requires two lines, to measure a single quadrature encoder this function must be called twice on consecutive timerNumbers. All output timers use the same clock (see setTimerBase and setTimerClockDivisor).

Parameters
indexThe index of the timer (not the line number, see setTimerCounterPinOffset).
modeThe type of timer.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::enableTimer ( int  index,
LabJack::TimerMode  mode,
int  initialValue 
)

Enable timer with an initial value.

Since quadrature requires two lines, to measure a single quadrature encoder this function must be called twice on consecutive timerNumbers. For example, to enable z-phase support for a quadrature timer, with the Z (aka index) signal on digital channel FIO4 (channel 4), set initialValue for both timer channels to ((1 << 15) | 4). All output timers use the same clock (see setTimerBase and setTimerClockDivisor).

Parameters
indexThe index of the timer (not the line number, see setTimerCounterPinOffset).
modeThe type of timer.
initialValueThe initial value.
Exceptions
Assertsif already initialized.
bool SurgSim::Device::LabJackDevice::finalize ( )
overrideprivatevirtual

Finalize (de-initialize) the device.

Returns
True if device was successfully un-registered.
Exceptions
Assertsif not initialized.

Implements SurgSim::Input::DeviceInterface.

const std::string & SurgSim::Device::LabJackDevice::getAddress ( ) const
Returns
The address of the LabJack, e.g., "1" or "192.168.7.23".
int SurgSim::Device::LabJackDevice::getAnalogInputResolution ( ) const
Returns
The resolution code for all the analog inputs.
const std::unordered_map< int, LabJack::AnalogInputSettings > & SurgSim::Device::LabJackDevice::getAnalogInputs ( ) const
Returns
The enabled analog inputs.
int SurgSim::Device::LabJackDevice::getAnalogInputSettling ( ) const
Returns
The settling time code for all the analog inputs.
const std::unordered_set< int > & SurgSim::Device::LabJackDevice::getAnalogOutputs ( ) const
Returns
The enabled analog output channels.
LabJack::Connection SurgSim::Device::LabJackDevice::getConnection ( ) const
Returns
The connection type of the LabJack, e.g., USB.
const std::unordered_set< int > & SurgSim::Device::LabJackDevice::getDigitalInputs ( ) const
Returns
The enabled digital input lines.
const std::unordered_set< int > & SurgSim::Device::LabJackDevice::getDigitalOutputs ( ) const
Returns
The enabled digital output lines.
double SurgSim::Device::LabJackDevice::getMaximumUpdateRate ( ) const
Returns
The maximum update rate for the LabJackThread.
LabJack::Model SurgSim::Device::LabJackDevice::getModel ( ) const
Returns
The model, e.g., U6.
LabJack::TimerBase SurgSim::Device::LabJackDevice::getTimerBase ( ) const
Returns
The timer base rate.
int SurgSim::Device::LabJackDevice::getTimerClockDivisor ( ) const
Returns
The timer clock divisor.
int SurgSim::Device::LabJackDevice::getTimerCounterPinOffset ( ) const
Returns
The channel number of the first timer/counter.
const std::unordered_map< int, LabJack::TimerSettings > & SurgSim::Device::LabJackDevice::getTimers ( ) const
Returns
The enabled timers.
bool SurgSim::Device::LabJackDevice::initialize ( )
overridevirtual

Fully initialize the device.

When the manager object creates the device, the internal state of the device usually isn't fully initialized yet. This method performs any needed initialization.

Returns
True on success.
Exceptions
Assertsif already initialized, or if unable to get a scaffold.

Implements SurgSim::Input::DeviceInterface.

bool SurgSim::Device::LabJackDevice::isInitialized ( ) const

Check whether this device is initialized.

void SurgSim::Device::LabJackDevice::setAddress ( std::string  address)

Set the address of the LabJack, e.g., "1" or "192.168.7.23".

If the address is zero-length, attempt to open the first-found device of the specified type on the specified connection.

Parameters
addressThe address for the device, or a zero-length string.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::setAnalogInputResolution ( int  resolution)

Set the resolution for all the analog inputs.

The resolution parameter is a model-dependent code. Refer to the User's Guide for the specific model to determine behavior for different codes. For example, for the U6 see http://labjack.com/support/u6/users-guide/4.3.3 and http://labjack.com/support/u6/users-guide/appendix-b

Parameters
resolutionThe resolution code.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::setAnalogInputs ( const std::unordered_map< int, LabJack::AnalogInputSettings > &  analogInputs)

Set which analog inputs are enabled.

See also
enableAnalogInput
Parameters
analogInputsThe map from the line number of the positive channel to the range and (for differential readings only) the line number of the negative channel.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::setAnalogInputSettling ( int  settling)

Set the settling time for all the analog inputs.

The settling parameter is a model-dependent code. Refer to the User's Guide for the specific model to determine behavior for different codes. For example, for the U6 see http://labjack.com/support/u6/users-guide/2.6

Parameters
settlingThe settling time code.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::setAnalogOutputs ( const std::unordered_set< int > &  analogOutputChannels)

Set which analog outputs are enabled.

See also
enableAnalogOutput
Parameters
analogOutputChannelsThe line numbers for the analog outputs.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::setConnection ( LabJack::Connection  connection)

Set the connection type of the LabJack, e.g., USB.

Parameters
connectionThe communication medium.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::setDigitalInputs ( const std::unordered_set< int > &  digitalInputChannels)

Set which digital input lines are enabled.

Parameters
digitalInputChannelsThe line numbers for the digital inputs.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::setDigitalOutputs ( const std::unordered_set< int > &  digitalOutputChannels)

Set which digital output lines are enabled.

Parameters
digitalOutputChannelsThe line numbers for the digital outputs.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::setMaximumUpdateRate ( double  rate)

Set the maximum update rate for the LabJackThread.

Since the device driver blocks thread execution while acquiring new data, update rates have a definite upper-bound that is dependent on the requested inputs (at least). See the LabJack User's Guide for details.

void SurgSim::Device::LabJackDevice::setModel ( LabJack::Model  model)

Set the model, e.g., U6.

Parameters
modelThe model.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::setTimerBase ( LabJack::TimerBase  base)

Set the timer base rate.

Timer base rates that end in "_DIV" are divided by the divisor to get the actual timer frequency. See section 2.10 - Timers/Counters in the respective LabJack model's User's Guide.

Parameters
baseThe timer base rate.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::setTimerClockDivisor ( int  divisor)

If the Timer type ends in "_DIV", then the actual timer frequency is divided by the divisor.

Parameters
divisorThe amount by which to divide the frequency. Values from 1-255 are used directly, while 0 means divide by 256. Values above 255 are not supported and cause an error.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::setTimerCounterPinOffset ( int  offset)

The timers and counters are always on consecutive pins, but the start pin can be varied within limits.

Parameters
offsetThe channel number of the first timer/counter.
Exceptions
Assertsif already initialized.
void SurgSim::Device::LabJackDevice::setTimers ( const std::unordered_map< int, LabJack::TimerSettings > &  timers)

Set which timers are enabled.

See also
enableTimer
Parameters
timersThe map from timer index (not line number) to mode and optional initial value.
Exceptions
Assertsif already initialized.

Friends And Related Function Documentation

friend class LabJackScaffold
friend

Member Data Documentation

std::string SurgSim::Device::LabJackDevice::m_address
private

The address, or a zero-length string to indicate the first-found device of this type on this connection.

int SurgSim::Device::LabJackDevice::m_analogInputResolution
private

The resolution for all the analog inputs.

std::unordered_map<int, LabJack::AnalogInputSettings> SurgSim::Device::LabJackDevice::m_analogInputs
private

The analog inputs. The key is the positive channel.

int SurgSim::Device::LabJackDevice::m_analogInputSettling
private

The settling time for all the analog inputs.

std::unordered_set<int> SurgSim::Device::LabJackDevice::m_analogOutputChannels
private

The line numbers for the analog outputs.

LabJack::Connection SurgSim::Device::LabJackDevice::m_connection
private

The type of communication connection, e.g., USB.

std::unordered_set<int> SurgSim::Device::LabJackDevice::m_digitalInputChannels
private

The line numbers for the digital inputs.

std::unordered_set<int> SurgSim::Device::LabJackDevice::m_digitalOutputChannels
private

The line numbers for the digital outputs.

LabJack::Model SurgSim::Device::LabJackDevice::m_model
private

The model, e.g., U6.

std::shared_ptr<LabJackScaffold> SurgSim::Device::LabJackDevice::m_scaffold
private

The single scaffold object that handles communications with all instances of LabJackDevice.

double SurgSim::Device::LabJackDevice::m_threadRate
private

The maximum update rate for the LabJackThread.

LabJack::TimerBase SurgSim::Device::LabJackDevice::m_timerBase
private

The timer base, which is the frequency of all the output timers unless it ends in "_DIV", in which case the frequency is the base divided by the divisor.

See section 2.10 - Timers/Counters in the respective LabJack model's User's Guide.

int SurgSim::Device::LabJackDevice::m_timerClockDivisor
private

The timer clock's divisor, see m_timerBase.

int SurgSim::Device::LabJackDevice::m_timerCounterPinOffset
private

The number of the lowest FIO pin that is a timer or counter.

std::unordered_map<int, LabJack::TimerSettings> SurgSim::Device::LabJackDevice::m_timers
private

A map from the timers' line numbers to their mode and optional initial value.


The documentation for this class was generated from the following files: