SurgSim::Devices::NovintDevice Class Reference

A class implementing the communication with a Novint Falcon device. More...

`#include <SurgSim/Devices/Novint/NovintDevice.h>`

Inheritance diagram for SurgSim::Devices::NovintDevice:

## Public Member Functions

| NovintDevice (const std::string &name)
| Constructor. More...
| SURGSIM_CLASSNAME (SurgSim::Devices::NovintDevice)
virtual | ~NovintDevice ()
| Destructor. More...
void | setSerialNumber (const std::string &serialNumber)
| Sets the serial number used to register this device with the hardware library. More...
bool | getSerialNumber (std::string *serialNumber) const
| Gets the serial number used to register this device with the hardware library. More...
void | setInitializationName (const std::string &initializationName)
| Sets the name used to register this device with the hardware library. More...
bool | getInitializationName (std::string *initializationName) const
| Gets the name used to register this device with the hardware library. More...
bool | initialize () override
| Fully initialize the device. More...
bool | isInitialized () const override
void | setPositionScale (double scale)
| Sets the position scale for this device. More...
double | getPositionScale () const
| Gets the position scale for this device. More...
void | setOrientationScale (double scale)
| Sets the orientation scale for this device. More...
double | getOrientationScale () const
| Gets the orientation scale for this device. More...
void | set7DofDevice (bool val)
| Sets whether or not this is supposed to be a 7Dof device. More...
virtual bool | is7DofDevice () const
| Query if this object represents a 7 degree of freedom hardware device. More...
void | setMaxForce (double force)
| Set the maximum force that can be sent to the device. More...
double | getMaxForce () const
void | setAntigrav (Math::Vector3d antigrav)
| Set a constant force that gets added to all forces sent to the hardware. More...
Math::Vector3d | getAntigrav () 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. More...
std::string | getName () const override
| Return a (hopefully unique) device name. More...
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. More...
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. More...
Public Member Functions inherited from SurgSim::Input::DeviceInterface
virtual | ~DeviceInterface ()
| Virtual destructor (empty). More...
Public Member Functions inherited from SurgSim::Framework::Accessible
| Accessible ()
| Default Constructor. More...
| ~Accessible ()
| Destructor. More...
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...
template<>
boost::any | getValue (const std::string &name) const

## Protected Attributes

bool | m_7DofDevice
| True if the device is 7Dof, false if the device is 3Dof. More...
double | m_maxForce
| The maximum force magnitude (in Newtons) that should be sent to the hardware. More...
Math::Vector3d | m_antigrav
| The anti-gravity force in Newtons. More...

## Private Member Functions

bool | finalize () override
| Finalize (de-initialize) the device. More...
const DataStructures::OptionalValue< std::string > & | getOptionalInitializationName () const
void | setOptionalInitializationName (const DataStructures::OptionalValue< std::string > &name)
const DataStructures::OptionalValue< std::string > & | getOptionalSerialNumber () const
void | setOptionalSerialNumber (const DataStructures::OptionalValue< std::string > &serial)

## Private Attributes

std::shared_ptr< NovintScaffold > | m_scaffold
| The scaffold handles all the communication with the SDK. More...
SurgSim::DataStructures::OptionalValue< std::string > | m_initializationName
| The name passed to the SDK to specify which hardware device should be used. More...
SurgSim::DataStructures::OptionalValue< std::string > | m_serialNumber
| The serial number passed to the SDK to specify which hardware device should be used. More...
double | m_positionScale
| Scale factor for the position axes; stored locally before the device is initialized. More...
double | m_orientationScale
| Scale factor for the orientation axes; stored locally before the device is initialized. More...

## Friends

class | NovintScaffold

## 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. More...
virtual bool | pullOutput ()
| Pull application output from a producer. More...
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 Novint Falcon device.

This should provide basic support for any device that can communicate using the Novint HDAL SDK toolkit, such as the off-the-shelf Novint Falcon haptic gaming controller. Note that certain devices may require device-specific support in the code to enable particular hardware features. In particular, the Novint Falcon with the Open Surgery Grip will not be able to produce torques unless it is accessed using the NovintOsgDevice class.

Application input provided by the device:

  type | name |
  --- | --- | ---
  pose | "pose" | Device pose (units are meters)*.
  scalar | "toolDof" | %7th Dof (e.g., handle open/close angle)
  bool | "button1" | State of the first device button if present.**
  bool | "button2" | State of the second device button if present.**
  bool | "button3" | State of the third device button if present.**
  bool | "button4" | State of the third device button if present.**
  bool | "isHomed" | Device homing status.
  bool | "isPositionHomed" | Device homing status, position only.
  bool | "isOrientationHomed" | Device homing status, orientation only.

  * The workspace of an off-the-shelf Novint Falcon is +z points out from the face of the Falcon, +y points up, and +x points to your right if you are looking at the face of the Falcon (a right-hand frame). The workspace of both 7dof OSG Falcons in a pair is +x towards the right Falcon, +y up, and +z towards the user (a right-hand frame). Thus, if the 7dof OSG Falcons are setup in a typical configuration such that the left Falcon is to the user's left and the right Falcon is to the user's right, then the workspace will be the same as an off-the-shelf Falcon placed directly facing the user. The identity orientation for an OSG Falcon is with the handle of the tool parallel to the floor (pitch), and pointed towards the user (yaw)...therefore in the home pose, the "business end" of the tool points away from the user along the -z axis. **`button1` through `4` correspond to the buttons 0 through 3 provided by the HDAL SDK, but a custom Novint device might have fewer than 4 buttons.

Application output used by the device:

  type | name |
  --- | --- | ---
  vector | "force" | Device output force (units are newtons).
  vector | "torque" | Device output torque (in newton-meters, 7Dof only).
  bool | "gravityCompensation" | Enable or disable hardware gravity compensation.

## Constructor & Destructor Documentation

## NovintDevice()

SurgSim::Devices::NovintDevice::NovintDevice | ( | const std::string & | name | ) |

explicit

Constructor.

Parameters

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

## ~NovintDevice()

SurgSim::Devices::NovintDevice::~NovintDevice | ( |  | ) |

virtual

Destructor.

## Member Function Documentation

## finalize()

bool SurgSim::Devices::NovintDevice::finalize | ( |  | ) |

override private virtual

Finalize (de-initialize) the device.

Implements SurgSim::Input::DeviceInterface.

## getAntigrav()

Math::Vector3d SurgSim::Devices::NovintDevice::getAntigrav | ( |  | ) | const

Returns
  The constant force that gets added to all forces sent to the hardware (in Newtons).

## getInitializationName()

bool SurgSim::Devices::NovintDevice::getInitializationName | ( | std::string * | initializationName | ) | const

Gets the name used to register this device with the hardware library.

Parameters

  [out] | initializationName | The initialization name, if set.

Returns
  true if the initializationName has been set

## getMaxForce()

double SurgSim::Devices::NovintDevice::getMaxForce | ( |  | ) | const

Returns
  The maximum force (in Newtons) that can be sent to the device.

## getOptionalInitializationName()

const OptionalValue< std::string > & SurgSim::Devices::NovintDevice::getOptionalInitializationName | ( |  | ) | const

private

Used for serializing optional properties

## getOptionalSerialNumber()

const OptionalValue< std::string > & SurgSim::Devices::NovintDevice::getOptionalSerialNumber | ( |  | ) | const

private

Used for serializing optional properties

## getOrientationScale()

double SurgSim::Devices::NovintDevice::getOrientationScale | ( |  | ) | const

Gets the orientation scale for this device.

## getPositionScale()

double SurgSim::Devices::NovintDevice::getPositionScale | ( |  | ) | const

Gets the position scale for this device.

## getSerialNumber()

bool SurgSim::Devices::NovintDevice::getSerialNumber | ( | std::string * | serialNumber | ) | const

Gets the serial number used to register this device with the hardware library.

Parameters

  [out] | serialNumber | The serial number, if set.

Returns
  true if the serialNumber has been set.

## initialize()

bool SurgSim::Devices::NovintDevice::initialize | ( |  | ) |

override virtual

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.

## is7DofDevice()

bool SurgSim::Devices::NovintDevice::is7DofDevice | ( |  | ) | const

virtual

Query if this object represents a 7 degree of freedom hardware device.

Returns
  true if 7 degree of freedom device, false if not.

## isInitialized()

bool SurgSim::Devices::NovintDevice::isInitialized | ( |  | ) | const

override virtual

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

Implements SurgSim::Input::DeviceInterface.

## set7DofDevice()

void SurgSim::Devices::NovintDevice::set7DofDevice | ( | bool | val | ) |

Sets whether or not this is supposed to be a 7Dof device.

If the hardware is not actually 7Dof, the resulting device will never home. If the hardware is 7Dof, and this is not called, the resulting device will act like a typical 3Dof.

Parameters

  val | true for a 7Dof device.

## setAntigrav()

void SurgSim::Devices::NovintDevice::setAntigrav | ( | Math::Vector3d | antigrav | ) |

Set a constant force that gets added to all forces sent to the hardware.

Parameters

  antigrav | The anti-gravity force in Newtons.

## setInitializationName()

void SurgSim::Devices::NovintDevice::setInitializationName | ( | const std::string & | initializationName | ) |

Sets the name used to register this device with the hardware library.

To use an initialization name, the 'devices.yaml' file must be in the working directory, (see example at Data/devices.yaml) with an entry of the form "initializationName: serialNumber". An empty string indicates the first available device.

Parameters

  initializationName | The initialization name.

See also
  setSerialNumber

## setMaxForce()

void SurgSim::Devices::NovintDevice::setMaxForce | ( | double | force | ) |

Set the maximum force that can be sent to the device.

Higher force values will be scaled to this magnitude. Generally Falcons are robust enough that commanding excessive forces will not cause a problem, but in-development systems may overheat if over-driven.

Parameters

  force | The maximum force magnitude (in Newtons) that will be sent to the hardware.

## setOptionalInitializationName()

void SurgSim::Devices::NovintDevice::setOptionalInitializationName | ( | const DataStructures::OptionalValue< std::string > & | name | ) |

private

Used for serializing optional properties

## setOptionalSerialNumber()

void SurgSim::Devices::NovintDevice::setOptionalSerialNumber | ( | const DataStructures::OptionalValue< std::string > & | serial | ) |

private

Used for serializing optional properties

## setOrientationScale()

void SurgSim::Devices::NovintDevice::setOrientationScale | ( | double | scale | ) |

Sets the orientation scale for this device.

The orientation scale controls how much the pose changes for a given device rotation. The default value for a raw device tries to correspond to the actual physical motion of the device.

Parameters

  scale | The multiplicative factor to apply to the rotation angles.

## setPositionScale()

void SurgSim::Devices::NovintDevice::setPositionScale | ( | double | scale | ) |

Sets the position scale for this device.

The position scale controls how much the pose changes for a given device translation. The default value for a raw device tries to correspond to the actual physical motion of the device.

Parameters

  scale | The multiplicative factor to apply to the position.

## setSerialNumber()

void SurgSim::Devices::NovintDevice::setSerialNumber | ( | const std::string & | serialNumber | ) |

Sets the serial number used to register this device with the hardware library.

An empty string indicates the first available device.

Parameters

  serialNumber | The serial number.

See also
  setInitializationName

## SURGSIM_CLASSNAME()

SurgSim::Devices::NovintDevice::SURGSIM_CLASSNAME | ( | SurgSim::Devices::NovintDevice |  | ) |

## Friends And Related Function Documentation

## NovintScaffold

friend class NovintScaffold

friend

## Member Data Documentation

## m_7DofDevice

bool SurgSim::Devices::NovintDevice::m_7DofDevice

protected

True if the device is 7Dof, false if the device is 3Dof.

## m_antigrav

Math::Vector3d SurgSim::Devices::NovintDevice::m_antigrav

protected

The anti-gravity force in Newtons.

## m_initializationName

SurgSim::DataStructures::OptionalValue<std::string> SurgSim::Devices::NovintDevice::m_initializationName

private

The name passed to the SDK to specify which hardware device should be used.

## m_maxForce

double SurgSim::Devices::NovintDevice::m_maxForce

protected

The maximum force magnitude (in Newtons) that should be sent to the hardware.

## m_orientationScale

double SurgSim::Devices::NovintDevice::m_orientationScale

private

Scale factor for the orientation axes; stored locally before the device is initialized.

## m_positionScale

double SurgSim::Devices::NovintDevice::m_positionScale

private

Scale factor for the position axes; stored locally before the device is initialized.

## m_scaffold

std::shared_ptr<NovintScaffold> SurgSim::Devices::NovintDevice::m_scaffold

private

The scaffold handles all the communication with the SDK.

## m_serialNumber

SurgSim::DataStructures::OptionalValue<std::string> SurgSim::Devices::NovintDevice::m_serialNumber

private

The serial number passed to the SDK to specify which hardware device should be used.

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

- SurgSim/Devices/Novint/NovintDevice.h
- SurgSim/Devices/Novint/NovintDevice.cpp