Classes | Public Member Functions | Static Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | Static Private Attributes | Friends | List of all members
SurgSim::Device::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 (std::shared_ptr< SurgSim::Framework::Logger > logger=nullptr)
 Constructor. More...
 
 ~NovintScaffold ()
 Destructor. More...
 
std::shared_ptr< SurgSim::Framework::LoggergetLogger () const
 Gets the logger used by this object and the devices it manages. More...
 

Static Public Member Functions

static std::shared_ptr< NovintScaffoldgetOrCreateSharedInstance ()
 Gets or creates the scaffold shared by all NovintDevice and Novint7DofDevice instances. More...
 
static void setDefaultLogLevel (SurgSim::Framework::LogLevel logLevel)
 Sets the default log level. More...
 

Private Member Functions

bool registerDevice (NovintCommonDevice *device)
 Registers the specified device object. More...
 
bool unregisterDevice (const NovintCommonDevice *device)
 Unregisters the specified device object. More...
 
bool initializeDeviceState (DeviceData *info)
 Initializes a single device, creating the necessary HDAL resources. More...
 
bool finalizeDeviceState (DeviceData *info)
 Finalizes a single device, destroying the necessary HDAL resources. More...
 
bool updateDevice (DeviceData *info)
 Updates the device information for a single device. 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...
 
bool initializeSdk ()
 Initializes the HDAL SDK. More...
 
bool finalizeSdk ()
 Finalizes (de-initializes) the HDAL SDK. More...
 
bool runHapticFrame ()
 Executes the operations for a single haptic frame. More...
 
bool createHapticLoop ()
 Creates the haptic loop callback. More...
 
bool destroyHapticLoop ()
 Destroys the haptic loop callback. More...
 
bool startScheduler ()
 Starts the HDAL scheduler. More...
 
bool stopScheduler ()
 Stops the HDAL scheduler. 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...
 
bool checkForFatalError (const char *message)
 Check for HDAL errors, display them, and signal fatal errors. More...
 
bool checkForFatalError (bool previousError, const char *message)
 Check for HDAL errors, display them, and signal fatal errors. More...
 
void setPositionScale (const NovintCommonDevice *device, double scale)
 Sets the position scale for this device. More...
 
void setOrientationScale (const NovintCommonDevice *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::shared_ptr< SurgSim::Framework::Loggerm_logger
 Logger used by the scaffold and all devices. More...
 
std::unique_ptr< StateDatam_state
 Internal scaffold state. More...
 

Static Private Attributes

static SurgSim::Framework::LogLevel m_defaultLogLevel = SurgSim::Framework::LOG_LEVEL_INFO
 The default logging level. More...
 

Friends

class NovintCommonDevice
 
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::Device::NovintDevice, SurgSim::Device::Novint7DofDevice
SurgSim::Device::NovintCommonDevice

Constructor & Destructor Documentation

SurgSim::Device::NovintScaffold::NovintScaffold ( std::shared_ptr< SurgSim::Framework::Logger logger = nullptr)
explicit

Constructor.

Parameters
logger(optional) The logger to be used for the scaffold object and the devices it manages. If unspecified or empty, a console logger will be created and used.
SurgSim::Device::NovintScaffold::~NovintScaffold ( )

Destructor.

Member Function Documentation

SurgSim::DataStructures::DataGroup SurgSim::Device::NovintScaffold::buildDeviceInputData ( )
staticprivate

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

void SurgSim::Device::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
infoThe device data.
Note
The DeviceData's parameter mutex should be locked before this function is called.
void SurgSim::Device::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
infoThe device data.
bool SurgSim::Device::NovintScaffold::checkForFatalError ( const char *  message)
private

Check for HDAL errors, display them, and signal fatal errors.

Exactly equivalent to checkForFatalError(false, message).

Parameters
messageAn additional descriptive message.
Returns
true if there was a fatal error; false if everything is OK.
bool SurgSim::Device::NovintScaffold::checkForFatalError ( bool  previousError,
const char *  message 
)
inlineprivate

Check for HDAL errors, display them, and signal fatal errors.

Exactly equivalent to checkForFatalError(message) || previousError, but less nasty to read.

Parameters
previousErrorTrue if a previous error has occurred.
messageAn additional descriptive message.
Returns
true if there was a fatal error or if previousError is true; false if everything is OK.
bool SurgSim::Device::NovintScaffold::createHapticLoop ( )
private

Creates the haptic loop callback.

Returns
true on success.
bool SurgSim::Device::NovintScaffold::destroyHapticLoop ( )
private

Destroys the haptic loop callback.

Should be called while NOT holding the internal device list mutex, to prevent deadlock.

Returns
true on success.
bool SurgSim::Device::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
infoThe device data.
gravityCompensationStateDesired state of the gravity compensation flag.
Returns
true if it succeeds, false if it fails.
bool SurgSim::Device::NovintScaffold::finalizeDeviceState ( DeviceData info)
private

Finalizes a single device, destroying the necessary HDAL resources.

Parameters
[in,out]infoThe device data.
Returns
true on success.
bool SurgSim::Device::NovintScaffold::finalizeSdk ( )
private

Finalizes (de-initializes) the HDAL SDK.

Returns
true on success.
bool SurgSim::Device::NovintScaffold::getGravityCompensation ( const DeviceData info,
bool *  gravityCompensationState 
)
private

Gets the gravity compensation flag for the current device.

Parameters
infoThe device data.
[out]gravityCompensationStateState of the gravity compensation flag.
Returns
true if it succeeds, false if it fails.
std::shared_ptr< SurgSim::Framework::Logger > SurgSim::Device::NovintScaffold::getLogger ( ) const

Gets the logger used by this object and the devices it manages.

Returns
The logger.
std::shared_ptr< NovintScaffold > SurgSim::Device::NovintScaffold::getOrCreateSharedInstance ( )
static

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

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

Returns
the scaffold object.
bool SurgSim::Device::NovintScaffold::initializeDeviceState ( DeviceData info)
private

Initializes a single device, creating the necessary HDAL resources.

Parameters
[in,out]infoThe device data.
Returns
true on success.
bool SurgSim::Device::NovintScaffold::initializeSdk ( )
private

Initializes the HDAL SDK.

Returns
true on success.
bool SurgSim::Device::NovintScaffold::registerDevice ( NovintCommonDevice device)
private

Registers the specified device object.

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

Parameters
deviceThe device object to be used, which should have a unique name.
Returns
True if the initialization succeeds, false if it fails.
bool SurgSim::Device::NovintScaffold::runHapticFrame ( )
private

Executes the operations for a single haptic frame.

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

Returns
true on success.
void SurgSim::Device::NovintScaffold::setDefaultLogLevel ( SurgSim::Framework::LogLevel  logLevel)
static

Sets the default log level.

Has no effect unless called before a scaffold is created (i.e. before the first device).

Parameters
logLevelThe log level.
bool SurgSim::Device::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
infoThe device data.
gravityCompensationStateDesired state of the gravity compensation flag.
Returns
true if it succeeds, false if it fails.
void SurgSim::Device::NovintScaffold::setInputData ( DeviceData info)
private

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

Parameters
infoThe device data
void SurgSim::Device::NovintScaffold::setOrientationScale ( const NovintCommonDevice device,
double  scale 
)
private

Sets the orientation scale for this device.

Parameters
deviceA pointer to the device.
scaleThe multiplicative factor to apply to the rotation angles.
void SurgSim::Device::NovintScaffold::setPositionScale ( const NovintCommonDevice device,
double  scale 
)
private

Sets the position scale for this device.

Parameters
deviceA pointer to the device.
scaleThe multiplicative factor to apply to the position.
bool SurgSim::Device::NovintScaffold::startScheduler ( )
private

Starts the HDAL scheduler.

Returns
true on success.
bool SurgSim::Device::NovintScaffold::stopScheduler ( )
private

Stops the HDAL scheduler.

Returns
true on success.
bool SurgSim::Device::NovintScaffold::unregisterDevice ( const NovintCommonDevice device)
private

Unregisters the specified device object.

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

Parameters
deviceThe device object.
Returns
true on success, false on failure.
bool SurgSim::Device::NovintScaffold::updateDevice ( DeviceData info)
private

Updates the device information for a single device.

Parameters
infoThe device data.
Returns
true on success.

Friends And Related Function Documentation

friend class NovintCommonDevice
friend
friend class NovintDevice
friend

Member Data Documentation

SurgSim::Framework::LogLevel SurgSim::Device::NovintScaffold::m_defaultLogLevel = SurgSim::Framework::LOG_LEVEL_INFO
staticprivate

The default logging level.

std::shared_ptr<SurgSim::Framework::Logger> SurgSim::Device::NovintScaffold::m_logger
private

Logger used by the scaffold and all devices.

std::unique_ptr<StateData> SurgSim::Device::NovintScaffold::m_state
private

Internal scaffold state.


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