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

#include <LabJackDevice.h>

Inheritance diagram for SurgSim::Devices::LabJackDevice:

Public Member Functions
	LabJackDevice (const std::string &uniqueName)
	Constructor. More...

	SURGSIM_CLASSNAME (SurgSim::Devices::LabJackDevice)

virtual	~LabJackDevice ()
	Destructor.

bool	initialize () override
	Fully initialize the device. More...

bool	isInitialized () const override

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	setResetOnDestruct (bool reset)
	Reset LabJack during destruct. More...

bool	getResetOnDestruct () const
	Get whether or not the hardware should reset when the LabJackDevice object destructs. More...

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 DataStructures::DataGroup &inputData)
	Constructor. More...

	CommonDevice (const std::string &name, DataStructures::DataGroup &&inputData)
	Constructor. More...

virtual	~CommonDevice ()
	Destructor.

std::string	getName () const override
	Return a (hopefully unique) device name.

std::string	getClassName () const override
	The class name for this class. 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...

bool	addInputConsumer (std::shared_ptr< InputConsumerInterface > inputConsumer) override
	Adds an input consumer that will be notified when the application input state is updated. More...

bool	removeInputConsumer (std::shared_ptr< InputConsumerInterface > inputConsumer) override
	Removes an input consumer previously added via addInputConsumer. More...

void	clearInputConsumers () override
	Removes all InputConsumers.

bool	setOutputProducer (std::shared_ptr< OutputProducerInterface > outputProducer) override
	Sets an output producer that will be asked for application output state when the device needs it. More...

bool	removeOutputProducer (std::shared_ptr< OutputProducerInterface > outputProducer) override
	Removes an output producer previously added via setOutputProducer. More...

bool	hasOutputProducer () override
	Query if this object has output producer. More...

void	clearOutputProducer () override
	Removes any OutputProducer.

Public Member Functions inherited from SurgSim::Input::DeviceInterface
virtual	~DeviceInterface ()
	Virtual destructor (empty).

Public Member Functions inherited from SurgSim::Framework::Accessible
	Accessible ()
	Default Constructor.

	~Accessible ()
	Destructor.

template<class T >
T	getValue (const std::string &name) const
	Retrieves the value with the name by executing the getter if it is found and tries to convert it to the given type. More...

boost::any	getValue (const std::string &name) const
	Retrieves the value with the name by executing the getter if it is found. More...

template<class T >
bool	getValue (const std::string &name, T *value) const
	Retrieves the value with the name by executing the getter if it is found, and converts it to the type of the output parameter. More...

void	setValue (const std::string &name, const boost::any &value)
	Sets a value of a property that has setter. More...

bool	isReadable (const std::string &name) const
	Check whether a property is readable. More...

bool	isWriteable (const std::string &name) const
	Check whether a property is writable. More...

void	setGetter (const std::string &name, GetterType func)
	Sets a getter for a given property. More...

void	setSetter (const std::string &name, SetterType func)
	Sets a setter for a given property. More...

void	setAccessors (const std::string &name, GetterType getter, SetterType setter)
	Sets the accessors getter and setter in one function. More...

void	removeAccessors (const std::string &name)
	Removes all the accessors (getter and setter) for a given property. More...

void	forwardProperty (const std::string &name, const Accessible &target, const std::string &targetProperty)
	Adds a property with the given name that uses the targets accessors, in effect forwarding the value to the target. More...

void	setSerializable (const std::string &name, EncoderType encoder, DecoderType decoder)
	Sets the functions used to convert data from and to a YAML::Node. More...

void	setDecoder (const std::string &name, DecoderType decoder)
	Sets the functions used to convert data from a YAML::Node. More...

YAML::Node	encode () const
	Encode this Accessible to a YAML::Node. More...

void	decode (const YAML::Node &node, const std::vector< std::string > &ignoredProperties=std::vector< std::string >())
	Decode this Accessible from a YAML::Node, will throw an exception if the data type cannot be converted. More...

std::vector< std::string >	getProperties ()

template<>
boost::any	getValue (const std::string &name) const

Friends
class	LabJackScaffold

Additional Inherited Members
Public Types inherited from SurgSim::Framework::Accessible
typedef std::function< boost::any(void)>	GetterType

typedef std::function< void(boost::any)>	SetterType

typedef std::function< YAML::Node(void)>	EncoderType

typedef std::function< void(const YAML::Node *)>	DecoderType

Public Types inherited from SurgSim::Framework::FactoryBase1< DeviceInterface, std::string >
typedef ObjectFactory1< DeviceInterface, std::string >	FactoryType

Static Public Member Functions inherited from SurgSim::Framework::FactoryBase1< DeviceInterface, std::string >
static FactoryType &	getFactory ()

Protected Member Functions inherited from SurgSim::Input::CommonDevice
virtual void	pushInput ()
	Push application input to consumers.

virtual bool	pullOutput ()
	Pull application output from a producer.

DataStructures::DataGroup &	getInputData ()
	Getter for the input data DataGroup. More...

const DataStructures::DataGroup &	getOutputData () 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	"analogInput1"	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

§ LabJackDevice()

SurgSim::Devices::LabJackDevice::LabJackDevice ( const std::string & uniqueName )

explicit

Constructor.

Parameters

uniqueName A unique name for the device that will be used by the application.

Member Function Documentation

§ enableAnalogInput() [1/2]

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

Enable differential analog input.

Parameters

positiveChannel	The positive channel.
range	The voltage range.
negativeChannel	The negative channel.

Exceptions

Asserts if already initialized.

Note: On Linux, does not correctly handle negative channels 31 or 32 for U3 model.

§ enableAnalogInput() [2/2]

void SurgSim::Devices::LabJackDevice::enableAnalogInput	(	int	channel,
		LabJack::Range	range
	)

Enable single-ended analog input.

Parameters

channel	The channel.
range	The voltage range.

Exceptions

Asserts if already initialized.

§ enableAnalogOutput()

void SurgSim::Devices::LabJackDevice::enableAnalogOutput ( int channel )

Enable analog output.

Parameters

channel The channel.

Exceptions

Asserts if already initialized.

§ enableDigitalInput()

void SurgSim::Devices::LabJackDevice::enableDigitalInput ( int channel )

Enable digital input line.

Parameters

channel The channel number.

Exceptions

Asserts if already initialized.

§ enableDigitalOutput()

void SurgSim::Devices::LabJackDevice::enableDigitalOutput ( int channel )

Enable digital output line.

Parameters

channel The channel number.

Exceptions

Asserts if already initialized.

§ enableTimer() [1/2]

void SurgSim::Devices::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

index	The index of the timer (not the line number, see setTimerCounterPinOffset).
mode	The type of timer.

Exceptions

Asserts if already initialized.

§ enableTimer() [2/2]

void SurgSim::Devices::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

index	The index of the timer (not the line number, see setTimerCounterPinOffset).
mode	The type of timer.
initialValue	The initial value.

Exceptions

Asserts if already initialized.

§ getAddress()

const std::string & SurgSim::Devices::LabJackDevice::getAddress ( ) const

Returns: The address of the LabJack, e.g., "1" or "192.168.7.23".

§ getAnalogInputResolution()

int SurgSim::Devices::LabJackDevice::getAnalogInputResolution ( ) const

Returns: The resolution code for all the analog inputs.

§ getAnalogInputs()

const std::unordered_map< int, LabJack::AnalogInputSettings > & SurgSim::Devices::LabJackDevice::getAnalogInputs ( ) const

Returns: The enabled analog inputs.

§ getAnalogInputSettling()

int SurgSim::Devices::LabJackDevice::getAnalogInputSettling ( ) const

Returns: The settling time code for all the analog inputs.

§ getAnalogOutputs()

const std::unordered_set< int > & SurgSim::Devices::LabJackDevice::getAnalogOutputs ( ) const

Returns: The enabled analog output channels.

§ getConnection()

LabJack::Connection SurgSim::Devices::LabJackDevice::getConnection ( ) const

Returns: The connection type of the LabJack, e.g., USB.

§ getDigitalInputs()

const std::unordered_set< int > & SurgSim::Devices::LabJackDevice::getDigitalInputs ( ) const

Returns: The enabled digital input lines.

§ getDigitalOutputs()

const std::unordered_set< int > & SurgSim::Devices::LabJackDevice::getDigitalOutputs ( ) const

Returns: The enabled digital output lines.

§ getMaximumUpdateRate()

double SurgSim::Devices::LabJackDevice::getMaximumUpdateRate ( ) const

Returns: The maximum update rate for the LabJackThread.

§ getModel()

LabJack::Model SurgSim::Devices::LabJackDevice::getModel ( ) const

Returns: The model, e.g., U6.

§ getResetOnDestruct()

bool SurgSim::Devices::LabJackDevice::getResetOnDestruct ( ) const

Get whether or not the hardware should reset when the LabJackDevice object destructs.

Returns: true if should reset on destruct.

§ getTimerBase()

LabJack::TimerBase SurgSim::Devices::LabJackDevice::getTimerBase ( ) const

Returns: The timer base rate.

§ getTimerClockDivisor()

int SurgSim::Devices::LabJackDevice::getTimerClockDivisor ( ) const

Returns: The timer clock divisor.

§ getTimerCounterPinOffset()

int SurgSim::Devices::LabJackDevice::getTimerCounterPinOffset ( ) const

Returns: The channel number of the first timer/counter.

§ getTimers()

const std::unordered_map< int, LabJack::TimerSettings > & SurgSim::Devices::LabJackDevice::getTimers ( ) const

Returns: The enabled timers.

§ initialize()

bool SurgSim::Devices::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.

Implements SurgSim::Input::DeviceInterface.

§ isInitialized()

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

overridevirtual

Returns: true if the device has been initialized and has not yet been finalized.

Implements SurgSim::Input::DeviceInterface.

§ setAddress()

void SurgSim::Devices::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

address The address for the device, or a zero-length string.

Exceptions

Asserts if already initialized.

§ setAnalogInputResolution()

void SurgSim::Devices::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

resolution The resolution code.

Exceptions

Asserts if already initialized.

§ setAnalogInputs()

void SurgSim::Devices::LabJackDevice::setAnalogInputs ( const std::unordered_map< int, LabJack::AnalogInputSettings > & analogInputs )

Set which analog inputs are enabled.

See also: enableAnalogInput

Parameters

analogInputs The 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

Asserts if already initialized.

§ setAnalogInputSettling()

void SurgSim::Devices::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

settling The settling time code.

Exceptions

Asserts if already initialized.

§ setAnalogOutputs()

void SurgSim::Devices::LabJackDevice::setAnalogOutputs ( const std::unordered_set< int > & analogOutputChannels )

Set which analog outputs are enabled.

See also: enableAnalogOutput

Parameters

analogOutputChannels The line numbers for the analog outputs.

Exceptions

Asserts if already initialized.

§ setConnection()

void SurgSim::Devices::LabJackDevice::setConnection ( LabJack::Connection connection )

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

Parameters

connection The communication medium.

Exceptions

Asserts if already initialized.

§ setDigitalInputs()

void SurgSim::Devices::LabJackDevice::setDigitalInputs ( const std::unordered_set< int > & digitalInputChannels )

Set which digital input lines are enabled.

Parameters

digitalInputChannels The line numbers for the digital inputs.

Exceptions

Asserts if already initialized.

§ setDigitalOutputs()

void SurgSim::Devices::LabJackDevice::setDigitalOutputs ( const std::unordered_set< int > & digitalOutputChannels )

Set which digital output lines are enabled.

Parameters

digitalOutputChannels The line numbers for the digital outputs.

Exceptions

Asserts if already initialized.

§ setMaximumUpdateRate()

void SurgSim::Devices::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.

§ setModel()

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

Set the model, e.g., U6.

Parameters

model The model.

Exceptions

Asserts if already initialized.

§ setResetOnDestruct()

void SurgSim::Devices::LabJackDevice::setResetOnDestruct ( bool reset )

Reset LabJack during destruct.

Parameters

reset true if the hardware should reset & re-enumerate when this object destructs.

Note: The LabJack hardware has the feature that it continues operation and remembers all settings even after the associated LabJackDevice object destructs and communication ends. This function causes the hardware to reset when the LabJackDevice object destructs, thereby returning to its default (boot-up) settings and forcing USB re-enumeration.; After a reset, it will take a few seconds before the hardware can communicate.

Warning: If the LabJackDevice object does not cleanly destruct (e.g., the executable halts due to an exception), then the hardware will not reset.

§ setTimerBase()

void SurgSim::Devices::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

base	The timer base rate.

Exceptions

Asserts if already initialized.

§ setTimerClockDivisor()

void SurgSim::Devices::LabJackDevice::setTimerClockDivisor ( int divisor )

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

Parameters

divisor The 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

Asserts if already initialized.

§ setTimerCounterPinOffset()

void SurgSim::Devices::LabJackDevice::setTimerCounterPinOffset ( int offset )

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

Parameters

offset The channel number of the first timer/counter.

Exceptions

Asserts if already initialized.

§ setTimers()

void SurgSim::Devices::LabJackDevice::setTimers ( const std::unordered_map< int, LabJack::TimerSettings > & timers )

Set which timers are enabled.

See also: enableTimer

Parameters

timers The map from timer index (not line number) to mode and optional initial value.

Exceptions

Asserts if already initialized.

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

SurgSim/Devices/LabJack/LabJackDevice.h
SurgSim/Devices/LabJack/LabJackDevice.cpp

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

§ LabJackDevice()

Member Function Documentation

§ enableAnalogInput() [1/2]

§ enableAnalogInput() [2/2]

§ enableAnalogOutput()

§ enableDigitalInput()

§ enableDigitalOutput()

§ enableTimer() [1/2]

§ enableTimer() [2/2]

§ getAddress()

§ getAnalogInputResolution()

§ getAnalogInputs()

§ getAnalogInputSettling()

§ getAnalogOutputs()

§ getConnection()

§ getDigitalInputs()

§ getDigitalOutputs()

§ getMaximumUpdateRate()

§ getModel()

§ getResetOnDestruct()

§ getTimerBase()

§ getTimerClockDivisor()

§ getTimerCounterPinOffset()

§ getTimers()

§ initialize()

§ isInitialized()

§ setAddress()

§ setAnalogInputResolution()

§ setAnalogInputs()

§ setAnalogInputSettling()

§ setAnalogOutputs()

§ setConnection()

§ setDigitalInputs()

§ setDigitalOutputs()

§ setMaximumUpdateRate()

§ setModel()

§ setResetOnDestruct()

§ setTimerBase()

§ setTimerClockDivisor()

§ setTimerCounterPinOffset()

§ setTimers()