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::PhantomScaffold Class Reference

A class that manages Sensable PHANTOM devices. More...

#include <SurgSim/Devices/Phantom/PhantomScaffold.h>

Classes

class  Callback
 
struct  DeviceData
 
class  Handle
 
struct  StateData
 

Public Member Functions

 PhantomScaffold (std::shared_ptr< SurgSim::Framework::Logger > logger=nullptr)
 Constructor. More...
 
 ~PhantomScaffold ()
 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< PhantomScaffoldgetOrCreateSharedInstance ()
 Gets or creates the scaffold shared by all PhantomDevice instances. More...
 
static void setDefaultLogLevel (SurgSim::Framework::LogLevel logLevel)
 Sets the default log level. More...
 

Private Member Functions

bool registerDevice (PhantomDevice *device)
 Registers the specified device object. More...
 
bool unregisterDevice (const PhantomDevice *device)
 Unregisters the specified device object. More...
 
bool initializeDeviceState (DeviceData *info)
 Initializes a single device, creating the necessary HDAPI resources. More...
 
bool finalizeDeviceState (DeviceData *info)
 Finalizes a single device, destroying the necessary HDAPI resources. More...
 
bool updateDevice (DeviceData *info)
 Updates the device information for a single device. More...
 
void calculateForceAndTorque (DeviceData *info)
 Calculates forces and torques and sends them to the device library. More...
 
void setInputData (DeviceData *info)
 Sets the input DataGroup, which will be pushed to the InputComponent. More...
 
bool initializeSdk ()
 Initializes the OpenHaptics SDK. More...
 
bool finalizeSdk ()
 Finalizes (de-initializes) the OpenHaptics 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 OpenHaptics scheduler. More...
 
bool stopScheduler ()
 Stops the OpenHaptics scheduler. More...
 
bool checkForFatalError (const char *message)
 Check for OpenHaptics HDAPI errors, display them, and signal fatal errors. 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 PhantomDevice
 

Detailed Description

A class that manages Sensable PHANTOM devices.

This should support any PHANTOM device that can communicate using OpenHaptics 3.0 toolkit, such as PHANTOM Omni, PHANTOM Desktop, and the PHANTOM Premium series devices. The implementation is currently limited to 3DoF haptic output (forces only, no torques).

See also
SurgSim::Device::PhantomDevice

Constructor & Destructor Documentation

SurgSim::Device::PhantomScaffold::PhantomScaffold ( 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::PhantomScaffold::~PhantomScaffold ( )

Destructor.

Member Function Documentation

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

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

void SurgSim::Device::PhantomScaffold::calculateForceAndTorque ( PhantomScaffold::DeviceData info)
private

Calculates forces and torques and sends them to the device library.

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.
bool SurgSim::Device::PhantomScaffold::checkForFatalError ( const char *  message)
private

Check for OpenHaptics HDAPI errors, display them, and signal fatal errors.

Parameters
messageAn additional descriptive message.
Returns
true if there was a fatal error; false if everything is OK.
bool SurgSim::Device::PhantomScaffold::createHapticLoop ( )
private

Creates the haptic loop callback.

Returns
true on success.
bool SurgSim::Device::PhantomScaffold::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::PhantomScaffold::finalizeDeviceState ( DeviceData info)
private

Finalizes a single device, destroying the necessary HDAPI resources.

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

Finalizes (de-initializes) the OpenHaptics SDK.

Returns
true on success.
std::shared_ptr<SurgSim::Framework::Logger> SurgSim::Device::PhantomScaffold::getLogger ( ) const
inline

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

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

Gets or creates the scaffold shared by all PhantomDevice 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::PhantomScaffold::initializeDeviceState ( DeviceData info)
private

Initializes a single device, creating the necessary HDAPI resources.

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

Initializes the OpenHaptics SDK.

Returns
true on success.
bool SurgSim::Device::PhantomScaffold::registerDevice ( PhantomDevice 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::PhantomScaffold::runHapticFrame ( )
private

Executes the operations for a single haptic frame.

Should only be called from the context of an OpenHaptics callback.

Returns
true on success.
void SurgSim::Device::PhantomScaffold::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.
void SurgSim::Device::PhantomScaffold::setInputData ( DeviceData info)
private

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

Parameters
infoThe device data
bool SurgSim::Device::PhantomScaffold::startScheduler ( )
private

Starts the OpenHaptics scheduler.

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

Stops the OpenHaptics scheduler.

Returns
true on success.
bool SurgSim::Device::PhantomScaffold::unregisterDevice ( const PhantomDevice 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::PhantomScaffold::updateDevice ( PhantomScaffold::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 PhantomDevice
friend

Member Data Documentation

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

The default logging level.

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

Logger used by the scaffold and all devices.

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

Internal scaffold state.


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