Actin®  Version 5.2.0
Software for Robotics Simulation and Control
Ec::Plugin Class Referenceabstract

Provides an abstract class to be used as a template for creating dynamically loaded functions. More...

#include <ecPlugin.h>

Inheritance diagram for Ec::Plugin:
analogDigitalIoPlugin Ec::HardwarePlugin Ec::PluginGUI examplePlugin exampleHardwarePlugin Ec::MainWidgetPlugin Ec::ViewerPlugin exampleDockWidgetPlugin exampleGUIPlugin exampleIoDirectionPlugin melodramaPlugin simulationPlugin viewerInteractionPlugin

Public Types

enum  PluginTraitsEnum {
  TraitDefault = 0x00,
  TraitHardware = 0x01,
  TraitGUI = 0x02,
  TraitRemoteHardware = 0x04,
  TraitPermanent = 0x10,
  TraitWinPermanent = 0x20,
  TraitNoThread = 0x40,
  TraitGUIThread = 0x80,
  TraitCopySystem = 0x100,
  TraitMask = 0x1ff
}
 
typedef EcU32 PluginTraits
 

Public Member Functions

virtual const EcStringpluginName () const
 Retrieve the name of this plugin.
 
virtual PluginTraits traits () const
 Retrieve the type and version number for this plugin.
 
virtual void setConfigurationString (const EcString &str)
 
virtual EcString getConfigurationString () const
 
virtual EcBoolean readConfigurationString (EcXmlReader &stream)
 
virtual EcBoolean writeConfigurationString (EcXmlWriter &stream) const
 
virtual EcBoolean initState ()
 
virtual EcBoolean reset ()
 
virtual EcBoolean shutdown ()
 
virtual void update (const EcReal time)=0
 
EcU32 updatePeriodInMs () const
 
EcBoolean initialized () const
 
void setExtrapolationTime (const EcReal time)
 
EcReal extrapolationTime () const
 
AsyncThreadgetThread ()
 Get a pointer to the Ec::AsyncThread class for real time manipulation.
 
virtual void setIOBuffer (IOBuffer *pBuffer)
 Set a pointer to the IO buffer.
 
virtual IOBuffergetIOBuffer ()
 Get pointer to the IO buffer.
 
virtual const IOBuffergetIOBuffer () const
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean setParam (const EcU32 manIndex, const EcU32 subIndex, const EcU32 subSubIndex, const ParamType &value)
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean setParam (const EcU32 manIndex, const EcU32 subIndex, const EcString &key, const ParamType &value)
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean setParam (const EcU32 manIndex, const EcU32 subIndex, const ParamType &value)
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean setParam (const EcU32U32PairVector &manipLinkIndexVector, const ParamType &value)
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean setParam (const EcU32 manIndex, const ParamType &value)
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean setParam (const EcString &key, const ParamType &value)
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean setParam (const ParamType &value)
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean getParam (const EcU32 manIndex, const EcU32 subIndex, const EcU32 subSubIndex, ParamType &value) const
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean getParam (const EcU32 manIndex, const EcU32 subIndex, const EcString &key, ParamType &value) const
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean getParam (const EcU32 manIndex, const EcU32 subIndex, ParamType &value) const
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean getParam (const EcU32U32PairVector &manipLinkIndexVector, ParamType &value) const
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean getParam (const EcU32 manIndex, ParamType &value) const
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean getParam (const EcString &key, ParamType &value) const
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean getParam (ParamType &value) const
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC const ParamType param () const
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC const ParamType * paramPtr () const
 
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC boost::shared_ptr< const ParamType > paramScopedPtr () const
 

Static Public Member Functions

static EC_PLUGIN_DECL_SPEC PlugingetPlugin (const EcString &pluginName)
 
static EC_PLUGIN_DECL_SPEC PluginfindPlugin (const EcString &pluginName)
 

Static Public Attributes

static const EcU8 currentVersion = EC_VERSION_MAJOR
 

Protected Member Functions

EC_PLUGIN_DECL_SPEC Plugin ()
 Constructor. Disallow public construction. Use PluginManager::loadPlugin() instead.
 
virtual EC_PLUGIN_DECL_SPEC ~Plugin ()
 
virtual EcBoolean init ()
 
virtual void threadingStarted (EcIODataBroker *dataBroker)
 
virtual void threadsStopping (EcIODataBroker *dataBroker)
 
virtual EC_PLUGIN_DECL_SPEC EcString pluginID ()
 

Protected Attributes

EcString m_Name
 Name of the plugin.
 
PluginTraits m_PluginTraits
 Describes the capabilities of this plugin.
 
EcU32 m_UpdatePeriodInMs
 Dictates how often this plugin gets updates.
 
EcStringVector m_RequiredPlugins
 List of plugins that this plugin depends on.
 
EcBoolean m_Initialized
 Whether the plugin initialized properly.
 
IOBufferm_pBuffer
 Internal data caching mechanism.
 
EcU32 m_StatedSystemCopyIndex
 Index of the copy of the stated system used.
 
EcReal m_ExtrapolationTime
 The delta time used for joint position extrapolation.
 
AsyncThreadm_pAsyncThread
 Asynchronous base thread.
 

Friends

class PluginManager
 Creates and destroys plugins.
 
class ::EcIODataBroker
 Initializes and sets back-end.
 
class PluginThread
 Sets plugin's pointer to thread.
 

Detailed Description

Provides an abstract class to be used as a template for creating dynamically loaded functions.

Base Implementation class used to provide minimum capability for loading. It holds a pointer to the loading helper class to provide access to the plugin name as well as the ability to unload when finished.

Examples:
exampleIoDirectionPlugin.cpp, and examplePlugin.cpp.

Definition at line 82 of file ecPlugin.h.

Member Typedef Documentation

Declare a type to hold the plugin traits. 24-bits are reserved, with 8 being used for versioning.

Definition at line 109 of file ecPlugin.h.

Member Enumeration Documentation

Enumeration of some characteristics about this plugin. This describes exactly what the plugin is able to provide and accept.

Enumerator
TraitDefault 

Standard plugin capability - set by default.

TraitHardware 

Hardware-based plugin set for HardwarePlugin.

TraitGUI 

Uses QT UI - set for PluginGUI.

TraitRemoteHardware 

Hardware-based plugin for remote control.

TraitPermanent 

Unable to be removed from memory - makes irreversible changes.

TraitWinPermanent 

Memory restriction on windows.

TraitNoThread 

Do not spawn a thread for updates.

TraitGUIThread 

Spawn an update thread for GUI plugins.

TraitCopySystem 

Copy the stated system for this plugin.

TraitMask 

Mask of all traits.

Definition at line 92 of file ecPlugin.h.

Constructor & Destructor Documentation

virtual EC_PLUGIN_DECL_SPEC Ec::Plugin::~Plugin ( )
protectedvirtual

Destructor. Disallow public deletion. Use PluginManager::unloadPlugin() instead. Cleans up any allocated memory.

Member Function Documentation

EcReal Ec::Plugin::extrapolationTime ( ) const
inline

Get the delta time used for joint position extrapolation.

Returns
time EcReal in seconds

Definition at line 171 of file ecPlugin.h.

References m_ExtrapolationTime.

static EC_PLUGIN_DECL_SPEC Plugin* Ec::Plugin::findPlugin ( const EcString pluginName)
static

Attempt to retrieve a handle to a loaded plugin. This will not attempt to load the plugin if it is not already loaded.

Parameters
[in]pluginNameName of plugin to get a handle to
Returns
Plugin* Handle to plugin or EcNULL if not loaded

Referenced by getIOBuffer(), and Ec::plugin_find_and_cast().

virtual EcString Ec::Plugin::getConfigurationString ( ) const
inlinevirtual

Allows for saving of plugin parameters.

Returns
EcString Configuration-specific values to save off

Definition at line 124 of file ecPlugin.h.

template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::getParam ( const EcU32  manIndex,
const EcU32  subIndex,
const EcU32  subSubIndex,
ParamType &  value 
) const

Get parameters at the joint or end-effector level. Single values are accepted here.

Template Parameters
prmParameter to retrieve
Parameters
manIndexManipulator index
subIndexSecondary index, such as end-effector set index
subSubIndexThird index, such as end-effector index
valueVariable value will be stored in.
Returns
EcBoolean Success or failure of retrieving the value

Referenced by getIOBuffer().

template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::getParam ( const EcU32  manIndex,
const EcU32  subIndex,
const EcString key,
ParamType &  value 
) const

Get parameters at the joint or end-effector level. Single values are accepted here.

Template Parameters
prmParameter to retrieve
Parameters
manIndexManipulator index
subIndexSecondary index, such as end-effector set index
keyA string key, such as a named frame id
valueVariable value will be stored in.
Returns
EcBoolean Success or failure of retrieving the value
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::getParam ( const EcU32  manIndex,
const EcU32  subIndex,
ParamType &  value 
) const

Get parameters at the joint or end-effector level. Single values are accepted here.

Template Parameters
prmParameter to retrieve
Parameters
manIndexManipulator index
subIndexSecondary index, such as joint or end-effector index
valueVariable value will be stored in.
Returns
EcBoolean Success or failure of retrieving the value
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::getParam ( const EcU32U32PairVector manipLinkIndexVector,
ParamType &  value 
) const

Get parameters at the joint or end-effector level. Single values are accepted here.

Template Parameters
prmParameter to retrieve (for ex. JointAngle)
Parameters
manipLinkIndexVectorVector of pairs of manipulator index and link index for which value is requested
valueVariable value will be stored in (vector with same size as the given manipLinkIndexVector).
Returns
EcBoolean Success or failure of retrieving the value
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::getParam ( const EcU32  manIndex,
ParamType &  value 
) const

Get parameters for the entire manipulator. A vector of values is needed here. Allowed types are: JointAngle, JointVelocity

Template Parameters
prmParameter to retrieve
Parameters
manIndexManipulator index
valueVariable value will be stored in.
Returns
EcBoolean Success or failure of retrieving the value
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::getParam ( const EcString key,
ParamType &  value 
) const

Get parameters for the entire manipulator. A vector of values is needed here. Allowed types are: JointAngle, JointVelocity

Template Parameters
prmParameter to retrieve
Parameters
manipIdentifierManipulator identifier
valueVariable value will be stored in.
Returns
EcBoolean Success or failure of retrieving the value
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::getParam ( ParamType &  value) const

Get parameters for the entire system or plugin. Allowed types are: JointAngle, JointVelocity

Template Parameters
prmParameter to retrieve
Parameters
valueVariable value will be stored in.
Returns
EcBoolean Success or failure of retrieving the value
static EC_PLUGIN_DECL_SPEC Plugin* Ec::Plugin::getPlugin ( const EcString pluginName)
static

Attempt to retrieve a handle to a loaded plugin. This will attempt to load the plugin if it is not already loaded.

Parameters
[in]pluginNameName of plugin to get a handle to
Returns
Plugin* Handle to plugin or EcNULL if not loaded

Referenced by getIOBuffer(), and Ec::plugin_load_and_cast().

virtual EcBoolean Ec::Plugin::init ( )
inlineprotectedvirtual

Initialization routine. This method is called once when the plugin is first loaded to perform any one-time processing.

Returns
EcBoolean Success or failure of command

Reimplemented in exampleDockWidgetPlugin, analogDigitalIoPlugin, simulationPlugin, exampleGUIPlugin, Ec::MainWidgetPlugin, examplePlugin, exampleIoDirectionPlugin, Ec::ViewerPlugin, viewerInteractionPlugin, melodramaPlugin, and Ec::HardwarePlugin.

Definition at line 451 of file ecPlugin.h.

References EcTrue, and m_Initialized.

EcBoolean Ec::Plugin::initialized ( ) const
inline

Whether the plugin was able to initialize.

Returns
EcBoolean Initialization state of plugin

Definition at line 163 of file ecPlugin.h.

References m_Initialized.

virtual EcBoolean Ec::Plugin::initState ( )
inlinevirtual

State initialization. This method is called after file loading. It allows setting specific parameters based upon the file loaded.

Returns
EcBoolean Success or failure of command

Reimplemented in Ec::HardwarePlugin, exampleDockWidgetPlugin, examplePlugin, exampleIoDirectionPlugin, analogDigitalIoPlugin, melodramaPlugin, and exampleHardwarePlugin.

Definition at line 139 of file ecPlugin.h.

References EcTrue.

template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC const ParamType Ec::Plugin::param ( ) const

Get a const reference to the parameter for the entire system or plugin. No error checking value is given. Allowed types are: CollisionResults, DesiredForce, PropagationResults, State, SystemSimulation

Template Parameters
prmParameter to retrieve
ParamTypeVariable type to retrieve
Returns
ParamType const value of internal variable

Referenced by getIOBuffer().

template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC const ParamType* Ec::Plugin::paramPtr ( ) const

Get a const pointer to the parameter. No error checking value is given. Allowed types are: StatedSystem

Template Parameters
prmParameter to retrieve
ParamTypeVariable type to retrieve
Returns
ParamType* const pointer to internal variable

Referenced by getIOBuffer().

template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC boost::shared_ptr<const ParamType> Ec::Plugin::paramScopedPtr ( ) const

Get a const scoped pointer to the parameter. No error checking value is given.

Template Parameters
prmParameter to retrieve
ParamTypeVariable type to retrieve
Returns
scoped pointer to internal variable. While the pointer is in scope it hold a lock on simulation data

Referenced by getIOBuffer().

virtual EC_PLUGIN_DECL_SPEC EcString Ec::Plugin::pluginID ( )
protectedvirtual

Create a unique pluginID from plugin name. This ID will be used in licensing.

Returns
EcString pluginID

Referenced by threadsStopping().

virtual EcBoolean Ec::Plugin::readConfigurationString ( EcXmlReader stream)
inlinevirtual

Provides mechanism to set plugin parameters through an XML stream.

Parameters
[in]streamXML stream to read from
Returns
EcBoolean Success or failure of reading

Definition at line 129 of file ecPlugin.h.

References EcTrue.

virtual EcBoolean Ec::Plugin::reset ( )
inlinevirtual

This method is called when the simulation is initialized and/or reset due to file loading. Any state cleanup should be done here.

Returns
EcBoolean Success or Failure of command

Reimplemented in examplePlugin, and exampleIoDirectionPlugin.

Definition at line 144 of file ecPlugin.h.

References EcTrue.

virtual void Ec::Plugin::setConfigurationString ( const EcString str)
inlinevirtual

Provides mechanism to set plugin parameters. Called immediately before initState.

Parameters
[in]strInitialization string for parameter passing

Definition at line 120 of file ecPlugin.h.

void Ec::Plugin::setExtrapolationTime ( const EcReal  time)
inline

Set the delta time used for joint position extrapolation.

Parameters
timethe time in seconds

Definition at line 167 of file ecPlugin.h.

References m_ExtrapolationTime.

template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::setParam ( const EcU32  manIndex,
const EcU32  subIndex,
const EcU32  subSubIndex,
const ParamType &  value 
)

Methods that can be used to query or set data within the simulation

Set parameter at the joint or end-effector level. Single values are accepted here.

Template Parameters
prmParameter to change
Parameters
manIndexManipulator index
subIndexSecondary index, such as end-effector set index
subSubIndexThird index, such as end-effector index
valueValue to set
Returns
EcBoolean Success or failure of setting the value

Referenced by getIOBuffer().

template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::setParam ( const EcU32  manIndex,
const EcU32  subIndex,
const EcString key,
const ParamType &  value 
)

Set parameter at the joint or end-effector level. Single values are accepted here.

Template Parameters
prmParameter to change
Parameters
manIndexManipulator index
subIndexSecondary index, such as end-effector set index
keyA string key, such as the named frame id
valueValue to set
Returns
EcBoolean Success or failure of setting the value
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::setParam ( const EcU32  manIndex,
const EcU32  subIndex,
const ParamType &  value 
)

Set parameter at the joint or end-effector level. Single values are accepted here.

Template Parameters
prmParameter to change
Parameters
manIndexManipulator index
subIndexSecondary index, such as joint or end-effector index
valueValue to set
Returns
EcBoolean Success or failure of setting the value
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::setParam ( const EcU32U32PairVector manipLinkIndexVector,
const ParamType &  value 
)

Set parameter for setting only partial state (for ex. subset of all joint angles)

Template Parameters
prmParameter to change (for ex. JointAngle)
Parameters
manipLinkIndexVectorVector of pairs of manipulator index and link index for which values are to be set
valueValue to set (vector with same size as the given manipLinkIndexVector)
Returns
EcBoolean Success or failure of setting the value
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::setParam ( const EcU32  manIndex,
const ParamType &  value 
)

Set parameter for a single manipulator. A vector of values applied over each joint or a single value for the entire manipulator. Allowed types are: Base, JointAngle, JointVelocity

Template Parameters
prmParameter to change
Parameters
manIndexManipulator index
valueValue to set
Returns
EcBoolean Success or failure of setting the value
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::setParam ( const EcString key,
const ParamType &  value 
)

Set parameter for a single manipulator. A vector of values applied over each joint or a single value for the entire manipulator. Allowed types are: Base, JointAngle, JointVelocity

Template Parameters
prmParameter to change
Parameters
keyString key, ie: manipulator label, named frame key, etc.
valueValue to set
Returns
EcBoolean Success or failure of setting the value
template<EcU32 prm, typename ParamType >
EC_PLUGIN_DECL_SPEC EcBoolean Ec::Plugin::setParam ( const ParamType &  value)

Set parameter for the entire system or plugin. Allowed types are: ReInit

Template Parameters
prmParameter to change
Parameters
valueValue to set
Returns
EcBoolean Success or failure of setting the value
virtual EcBoolean Ec::Plugin::shutdown ( )
inlinevirtual

This method is called immediately before unloading the plugin. It is available to be overriden by plugins requiring an available simulation. As an example, hardware-based plugins might use this to home, or park, the hardware before powering down.

Reimplemented in Ec::HardwarePlugin, and analogDigitalIoPlugin.

Definition at line 150 of file ecPlugin.h.

References EcTrue, and update().

virtual void Ec::Plugin::threadingStarted ( EcIODataBroker dataBroker)
inlineprotectedvirtual

Called whenever the thread for this plugin starts.

This occurs after init, and occurs everytime the simulation restarts. It is called by the ecIODataBroker class (also inherited by simulation plugin) after each thread is started, so all plugin threads are available for setup, as well as the simulation thread. To override the "start" of the AsyncThread to get immediate thread control of the new thread, override the ctor and subclass AsyncThread. Note this is not called on the plugin's thread itself.

Code can call getThread() to get a pointer to the plugin's Ec:AsyncThread, or call dataBroker->simulationThread() to get the simulation thread or a setup a different plugin's thread via: Ec::Plugin * p = Ec::PluginManager::instance().findPlugin(vPlugins[ii]); if (p != EcNULL) p->getThread()->setPriority(50);

Parameters
dataBrokerPointer to EcIODataBroker (the simulation container).

Definition at line 469 of file ecPlugin.h.

virtual void Ec::Plugin::threadsStopping ( EcIODataBroker dataBroker)
inlineprotectedvirtual

This function is called just before threads are joined / stopped. It allows plugins to save off the actual state of the thread if desired.

Definition at line 473 of file ecPlugin.h.

References EC_PLUGIN_DECL_SPEC, and pluginID().

virtual void Ec::Plugin::update ( const EcReal  time)
pure virtual

This method will be called at the proper update rate specified.

Parameters
timeCurrent simulation timestep

Implemented in Ec::HardwarePlugin, analogDigitalIoPlugin, Ec::PluginGUI, and examplePlugin.

Referenced by shutdown().

EcU32 Ec::Plugin::updatePeriodInMs ( ) const
inline

Retrieve the current plugin update interval.

Returns
EcU32 Time in milliseconds between updates. A value of 0 means run at the same rate as the simulation

Definition at line 159 of file ecPlugin.h.

References m_UpdatePeriodInMs.

virtual EcBoolean Ec::Plugin::writeConfigurationString ( EcXmlWriter stream) const
inlinevirtual

Allows for saving of plugin parameters to an XML stream

Parameters
[in]streamXML stream to write to
Returns
EcBoolean Success or failure of writing

Definition at line 134 of file ecPlugin.h.

References EcTrue.

Member Data Documentation

const EcU8 Ec::Plugin::currentVersion = EC_VERSION_MAJOR
static

Current version of the plugin API. Any plugin compiled with this header will use 'currentVersion' as the built type. When the API changes, this number needs to be changed to invalidate older plugins.

Definition at line 88 of file ecPlugin.h.


The documentation for this class was generated from the following file:
Created by Energid Technologies www.energid.com
Copyright © 2016 Energid. All trademarks mentioned in this document are property of their respective owners.