SurgSim::Devices::NovintScaffold Class Reference

A class that manages Novint Falcon devices. More...

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

## Classes

class | Callback
struct | DeviceData
class | Handle
struct | StateData

## Public Member Functions

| NovintScaffold ()
| Constructor. More...
| ~NovintScaffold ()
| Destructor. More...

## Static Public Member Functions

static std::shared_ptr< NovintScaffold > | getOrCreateSharedInstance ()
| Gets or creates the scaffold shared by all NovintDevice and Novint7DofDevice instances. More...

## Private Member Functions

| NovintScaffold (const NovintScaffold &)
NovintScaffold & | operator= (const NovintScaffold &)
bool | registerDevice (NovintDevice *device)
| Registers the specified device object, and starts the servo loop if necessary. More...
bool | unregisterDevice (const NovintDevice *device)
| Unregisters the specified device object. More...
bool | initializeDeviceState (DeviceData *info)
| Initializes a single device, creating the necessary HDAL resources. More...
std::shared_ptr< NovintScaffold::Handle > | findHandleByInitializationName (const std::string &initializationName)
| Get the Handle associated with an initialization name, if any. More...
bool | updateDeviceInput (DeviceData *info)
| Updates the device information for a single device's input. More...
bool | updateDeviceOutput (DeviceData *info, bool pulledOutput)
| Updates the device information for a single device's output. More...
void | checkDeviceHoming (DeviceData *info)
| Checks whether a device has been homed. More...
void | calculateForceAndTorque (DeviceData *info)
| Calculates forces, and torques if the device is a 7Dof, and sends them to the HDAL. More...
void | setInputData (DeviceData *info)
| Sets the input DataGroup, which will be pushed to the InputComponent. More...
std::map< std::string, std::string > | getNameMap ()
| Gets the map from name to serial number. More...
bool | createAllHandles ()
| Creates a NovintScaffold::Handle for each device connected when the first registerDevice is called. More...
void | destroyAllHandles ()
| Destroys all the initialized handles. More...
bool | storeHandleIfValid (const std::shared_ptr< Handle > &handle, const std::string &serial)
| Store the handle if it is valid. More...
void | runHapticFrame ()
| Executes the operations for a single haptic frame. More...
bool | getGravityCompensation (const DeviceData *info, bool *gravityCompensationState)
| Gets the gravity compensation flag for the current device. More...
bool | enforceGravityCompensation (const DeviceData *info, bool gravityCompensationState)
| Attempts to force the gravity compensation flag for the current device to the specified value. More...
bool | setGravityCompensation (const DeviceData *info, bool gravityCompensationState)
| Sets the gravity compensation flag for the current device, unless it's already set as desired. More...
void | setPositionScale (const NovintDevice *device, double scale)
| Sets the position scale for this device. More...
void | setOrientationScale (const NovintDevice *device, double scale)
| Sets the orientation scale for this device. More...

## Static Private Member Functions

static SurgSim::DataStructures::DataGroup | buildDeviceInputData ()
| Builds the data layout for the application input (i.e. device output). More...

## Private Attributes

std::unique_ptr< StateData > | m_state
| Internal scaffold state. More...

## Friends

class | NovintDevice

## Detailed Description

A class that manages Novint Falcon devices.

This should support any device that can communicate using the Novint HDAL SDK toolkit, such as the off-the-shelf Novint Falcon gaming controller and the Novint Falcon with the Open Surgery Grip.

See also
  SurgSim::Devices::NovintDevice

## Constructor & Destructor Documentation

## NovintScaffold() [1/2]

SurgSim::Devices::NovintScaffold::NovintScaffold | ( |  | ) |

Constructor.

## ~NovintScaffold()

SurgSim::Devices::NovintScaffold::~NovintScaffold | ( |  | ) |

Destructor.

## NovintScaffold() [2/2]

SurgSim::Devices::NovintScaffold::NovintScaffold | ( | const NovintScaffold & |  | ) |

private

## Member Function Documentation

## buildDeviceInputData()

DataGroup SurgSim::Devices::NovintScaffold::buildDeviceInputData | ( |  | ) |

static private

Builds the data layout for the application input (i.e. device output).

## calculateForceAndTorque()

void SurgSim::Devices::NovintScaffold::calculateForceAndTorque | ( | DeviceData * | info | ) |

private

Calculates forces, and torques if the device is a 7Dof, and sends them to the HDAL.

The force to output is composed of a vector named "force" in the output data, plus contributions from two optional Jacobians. If the matrix "springJacobian" is provided in the output data, a spring force & torque are generated from its product with the difference between the current pose and the pose in the output data named "inputPose". A damping force & torque are generated similarly. The intention is for a Behavior to calculate a nominal force & torque as well as the desired linearized changes to the force & torque based on changes to the input's pose & velocities. Then the linearized deltas to the output force & torque can be calculated at the haptic update rates, thereby smoothing the output response to motion.

Parameters

  info | The device data.

Note
  The DeviceData's parameter mutex should be locked before this function is called.

## checkDeviceHoming()

void SurgSim::Devices::NovintScaffold::checkDeviceHoming | ( | DeviceData * | info | ) |

private

Checks whether a device has been homed.

If the position and/or orientation have not been homed, zeros the respective Values. Call this before setting the data to send to the Input Component. The DeviceData's parameter mutex should be locked before this function is called.

Parameters

  info | The device data.

## createAllHandles()

bool SurgSim::Devices::NovintScaffold::createAllHandles | ( |  | ) |

private

Creates a NovintScaffold::Handle for each device connected when the first registerDevice is called.

Returns
  True if there are device handles created; false otherwise.

## destroyAllHandles()

void SurgSim::Devices::NovintScaffold::destroyAllHandles | ( |  | ) |

private

Destroys all the initialized handles.

## enforceGravityCompensation()

bool SurgSim::Devices::NovintScaffold::enforceGravityCompensation | ( | const DeviceData * | info,
|  | bool | gravityCompensationState
| ) |  |

private

Attempts to force the gravity compensation flag for the current device to the specified value.

Sets the flag repeatedly, until it reports the desired value, in order to work around the problem where attempts to set the gravity compensation do not always change the actual gravity compensation flag in the device.

Logs a message if the state is known to have been changed.

Parameters

  info | The device data.
  gravityCompensationState | Desired state of the gravity compensation flag.

Returns
  true if it succeeds, false if it fails.

## findHandleByInitializationName()

std::shared_ptr< NovintScaffold::Handle > SurgSim::Devices::NovintScaffold::findHandleByInitializationName | ( | const std::string & | initializationName | ) |

private

Get the Handle associated with an initialization name, if any.

Parameters

  initializationName | The initialization name (from the configuration file).

Returns
  Shared pointer to Handle, or nullptr if not found.

## getGravityCompensation()

bool SurgSim::Devices::NovintScaffold::getGravityCompensation | ( | const DeviceData * | info,
|  | bool * | gravityCompensationState
| ) |  |

private

Gets the gravity compensation flag for the current device.

Parameters

  | info | The device data.
  [out] | gravityCompensationState | State of the gravity compensation flag.

Returns
  true if it succeeds, false if it fails.

## getNameMap()

std::map< std::string, std::string > SurgSim::Devices::NovintScaffold::getNameMap | ( |  | ) |

private

Gets the map from name to serial number.

Returns
  The map.

## getOrCreateSharedInstance()

std::shared_ptr< NovintScaffold > SurgSim::Devices::NovintScaffold::getOrCreateSharedInstance | ( |  | ) |

static

Gets or creates the scaffold shared by all NovintDevice and Novint7DofDevice instances.

The scaffold is managed using a SharedInstance object, so it will be destroyed when all devices are released.

Returns
  the scaffold object.

## initializeDeviceState()

bool SurgSim::Devices::NovintScaffold::initializeDeviceState | ( | DeviceData * | info | ) |

private

Initializes a single device, creating the necessary HDAL resources.

Parameters

  [in,out] | info | The device data.

Returns
  true on success.

## operator=()

NovintScaffold& SurgSim::Devices::NovintScaffold::operator= | ( | const NovintScaffold & |  | ) |

private

## registerDevice()

bool SurgSim::Devices::NovintScaffold::registerDevice | ( | NovintDevice * | device | ) |

private

Registers the specified device object, and starts the servo loop if necessary.

If successful, the device object will become connected to an unused controller.

Parameters

  device | The device object to be used, which should have a unique name.

Returns
  True if the initialization succeeds, false if it fails.

## runHapticFrame()

void SurgSim::Devices::NovintScaffold::runHapticFrame | ( |  | ) |

private

Executes the operations for a single haptic frame.

Should only be called from the context of a HDAL callback.

## setGravityCompensation()

bool SurgSim::Devices::NovintScaffold::setGravityCompensation | ( | const DeviceData * | info,
|  | bool | gravityCompensationState
| ) |  |

private

Sets the gravity compensation flag for the current device, unless it's already set as desired.

Parameters

  info | The device data.
  gravityCompensationState | Desired state of the gravity compensation flag.

Returns
  true if it succeeds, false if it fails.

## setInputData()

void SurgSim::Devices::NovintScaffold::setInputData | ( | DeviceData * | info | ) |

private

Sets the input DataGroup, which will be pushed to the InputComponent.

Parameters

  info | The device data

## setOrientationScale()

void SurgSim::Devices::NovintScaffold::setOrientationScale | ( | const NovintDevice * | device,
|  | double | scale
| ) |  |

private

Sets the orientation scale for this device.

Parameters

  device | A pointer to the device.
  scale | The multiplicative factor to apply to the rotation angles.

## setPositionScale()

void SurgSim::Devices::NovintScaffold::setPositionScale | ( | const NovintDevice * | device,
|  | double | scale
| ) |  |

private

Sets the position scale for this device.

Parameters

  device | A pointer to the device.
  scale | The multiplicative factor to apply to the position.

## storeHandleIfValid()

bool SurgSim::Devices::NovintScaffold::storeHandleIfValid | ( | const std::shared_ptr< Handle > & | handle,
|  | const std::string & | serial
| ) |  |

private

Store the handle if it is valid.

Returns
  true If handle is valid and stored; false, otherwise.

## unregisterDevice()

bool SurgSim::Devices::NovintScaffold::unregisterDevice | ( | const NovintDevice * | device | ) |

private

Unregisters the specified device object.

The corresponding controller will become unused, and can be re-registered later.

Parameters

  device | The device object.

Returns
  true on success, false on failure.

## updateDeviceInput()

bool SurgSim::Devices::NovintScaffold::updateDeviceInput | ( | DeviceData * | info | ) |

private

Updates the device information for a single device's input.

Parameters

  info | The device data.

Returns
  true on success.

## updateDeviceOutput()

bool SurgSim::Devices::NovintScaffold::updateDeviceOutput | ( | DeviceData * | info,
|  | bool | pulledOutput
| ) |  |

private

Updates the device information for a single device's output.

If pullOutput failed, zeros forces & torques.

Parameters

  info | The device data.
  pulledOutput | true if the most recent pullOutput succeeded.

Returns
  true on success.

## Friends And Related Function Documentation

## NovintDevice

friend class NovintDevice

friend

## Member Data Documentation

## m_state

std::unique_ptr<StateData> SurgSim::Devices::NovintScaffold::m_state

private

Internal scaffold state.

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

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