This class constitutes the API of the Reflexxes Motion Libraries More...

#include <ReflexxesAPI.h>

Public Types
enum	RMLResultValue { RML_WORKING = 0, RML_FINAL_STATE_REACHED = 1, RML_ERROR = -1, RML_ERROR_INVALID_INPUT_VALUES = -100, RML_ERROR_EXECUTION_TIME_CALCULATION = -101, RML_ERROR_SYNCHRONIZATION = -102, RML_ERROR_NUMBER_OF_DOFS = -103, RML_ERROR_NO_PHASE_SYNCHRONIZATION = -104, RML_ERROR_NULL_POINTER = -105, RML_ERROR_EXECUTION_TIME_TOO_BIG = -106, RML_ERROR_USER_TIME_OUT_OF_RANGE = -107 }
	Result values of the On-Line Trajectory Generation algorithm. More...

Public Member Functions
	ReflexxesAPI (const unsigned int &DegreesOfFreedom, const double &CycleTimeInSeconds, const unsigned int &NumberOfAdditionalThreads=0)
	Constructor of the API class ReflexxesAPI (API of the Reflexxes Motion Library) More...

int	RMLPosition (const RMLPositionInputParameters &InputValues, RMLPositionOutputParameters *OutputValues, const RMLPositionFlags &Flags)
	This is the central method of each Reflexxes Type Motion Library. More...

int	RMLPositionAtAGivenSampleTime (const double &TimeValueInSeconds, RMLPositionOutputParameters *OutputValues)
	After calling ReflexxesAPI::RMLPosition(), this methods returns the state of motion of the computed trajectory at a given time instant. More...

int	RMLVelocity (const RMLVelocityInputParameters &InputValues, RMLVelocityOutputParameters *OutputValues, const RMLVelocityFlags &Flags)
	This is the method for velocity-based On-Line Trajectory Generation. More...

int	RMLVelocityAtAGivenSampleTime (const double &TimeValueInSeconds, RMLVelocityOutputParameters *OutputValues)
	After calling ReflexxesAPI::RMLVelocity(), this methods returns the state of motion of the computed trajectory at a given time instant. More...

	~ReflexxesAPI (void)
	Destructor of the class ReflexxesAPI. More...

Protected Attributes
double	CycleTime
	Cycle time in seconds as specified by the constructor ReflexxesAPI() More...

unsigned int	NumberOfDOFs
	Positive integer number of degrees of freedom as specified by the constructor ReflexxesAPI() More...

unsigned int	NumberOfOwnThreads
	Positive integer number of additional threads as specified by the constructor ReflexxesAPI() More...

void *	RMLPositionObject
	A pointer to an object for position-based On-Line Trajectory Generation. More...

void *	RMLVelocityObject
	A pointer to an object for velocity-based On-Line Trajectory Generation. More...

Detailed Description

This class constitutes the API of the Reflexxes Motion Libraries

The class ReflexxesAPI is the interface between the actual On-Line Trajectory Generation algorithms of the Reflexxes Motion Libraries and the applications using it. It wraps the classes of the algorithms, provides a simple and clean interface, and it hides all parts of the implementation that or not relevant the actual implementation behind its interface.

The only two relevant functions of a Reflexxes Motion Library are the the methods

ReflexxesAPI::RMLPosition(), which calls TypeIVRMLPosition::GetNextStateOfMotion() of the class TypeIVRMLPosition, to execute the position-based On-Line Trajectory Generation algorithm and
ReflexxesAPI::RMLVelocity(), which calls TypeIVRMLVelocity::GetNextStateOfMotion() of the class TypeIVRMLVelocity, to execute the velocity-based On-Line Trajectory Generation algorithm,

both of which calculate a new state of motion from any arbitrary initial state of motion.

Both methods, require the specification of a set of input values

RMLPositionInputParameters / RMLVelocityInputParameters (cf. page_InputValues)

and a data structure specifying a certain behavior of the algorithm

RMLPositionFlags / RMLVelocityFlags.

Based on these input values, the result, that is, the state of motion for the succeeding control cycle, is written to an

RMLPositionOutputParameters / RMLVelocityOutputParameters (cf. page_OutputValues)

object.
To get an overview about the source code, please refer to the page_SourceCode. A brief survey of the Reflexxes algorithm can be found at the page page_TypeIIAndIVOverview, and error-handling procedures are described at page_ErrorHandling.
Besides the classes for the input and output parameters, this class is is the only one that has to be embedded in a user application. The interface only consists of the constructor and the two methods RMLPosition() and RMLVelocity(), such that an integration into existing systems can be done in a clear and straight-forward way.

See also: RMLPositionInputParameters; RMLVelocityInputParameters; RMLPositionOutputParameters; RMLVelocityOutputParameters; RMLPositionFlags; RMLVelocityFlags; page_GettingStarted; page_SourceCode; page_TypeIIAndIVOverview; page_ErrorHandling

Definition at line 123 of file ReflexxesAPI.h.

Member Enumeration Documentation

enum ReflexxesAPI::RMLResultValue

Result values of the On-Line Trajectory Generation algorithm.

This enumeration contains all possible return values of the methods ReflexxesAPI::RMLPosition() and ReflexxesAPI::RMLVelocity(). Except ReflexxesAPI::RML_WORKING and ReflexxesAPI::RML_FINAL_STATE_REACHED, none the values must appear in a correct implementation. The input values of the algorithm are tested by the methods RMLPositionInputParameters::CheckForValidity() and RMLVelocityInputParameters::CheckForValidity().

If either one of these methods returns false, a correct calculation of output values can not necessarily be obtained anymore, but - in any case - a valid and continuous motion trajectory will be generated. In such a case, the library will try to calculate correct output values, and in many cases the library is capable to provide such values successfully, but a guarantee cannot be given (cf. page_ErrorHandling).

If RMLPositionInputParameters::CheckForValidity() or RMLVelocityInputParameters::CheckForValidity() return false, it may even be in indication for a wrong implementation of the application using the library, and it may happen that one the error-indicating values will be returned by ReflexxesAPI::RMLPosition() or ReflexxesAPI::RMLVelocity(), respectively. Furtheron, it may happen in this case that the execution time exceeds the value of RML_MAX_EXECUTION_TIME, such that RML_ERROR_EXECUTION_TIME_TOO_BIG will be returned.

Note: If RMLPositionInputParameters::CheckForValidity() or RMLVelocityInputParameters::CheckForValidity(), respectively, return true, either ReflexxesAPI::RML_WORKING or ReflexxesAPI::RML_FINAL_STATE_REACHED will be returned.

See also: ReflexxesAPI::RMLPosition(); ReflexxesAPI::RMLVelocity(); page_ErrorHandling

Enumerator
RML_WORKING	The On-Line Trajectory Generation algorithm is working; the final state of motion has not been reached yet.
RML_FINAL_STATE_REACHED	The desired final state of motion has been reached.
RML_ERROR	This is the initialization value of TypeIVRMLPosition::ReturnValue and TypeIVRMLVelocity::ReturnValue. In practice, this value. cannot be returned
RML_ERROR_INVALID_INPUT_VALUES	The applied input values are invalid (cf. RMLPositionInputParameters::CheckForValidity() RMLVelocityInputParameters::CheckForValidity()).
RML_ERROR_EXECUTION_TIME_CALCULATION	An error occurred during the first step of the algorithm (i.e., during the calculation of the synchronization time).
RML_ERROR_SYNCHRONIZATION	An error occurred during the second step of the algorithm (i.e., during the synchronization of the trajectory).
RML_ERROR_NUMBER_OF_DOFS	The number of degree of freedom of th input parameters, the output parameters, and the On-Line Trajectory Generation algorithm do not match.
RML_ERROR_NO_PHASE_SYNCHRONIZATION	If the input flag RMLFlags::ONLY_PHASE_SYNCHRONIZATION is set and it is not possible to calculate a physically (and mathematically) correct phase-synchronized (i.e., homothetic) trajectory, this error value will be returned. Please note: Even if this error message is returned, feasible, steady, and continuous output values will be computed in any case.
RML_ERROR_NULL_POINTER	If one of the pointers to objects of the classes RMLPositionInputParameters / RMLVelocityInputParameters RMLPositionOutputParameters / RMLVelocityOutputParameters RMLPositionFlags / RMLVelocityFlags is NULL, this error value will be returned.
RML_ERROR_EXECUTION_TIME_TOO_BIG	To ensure numerical stability, the value of the minimum trajectory execution time is limited to a value of RML_MAX_EXECUTION_TIME ( $10^{10}$ seconds).
RML_ERROR_USER_TIME_OUT_OF_RANGE	If either the method ReflexxesAPI::RMLPositionAtAGivenSampleTime() or the method ReflexxesAPI::RMLVelocityAtAGivenSampleTime() was used, the value of the parameter is negative or larger than the value of `RML_MAX_EXECUTION_TIME` ( $10^{10}\,s$ ).

Definition at line 262 of file ReflexxesAPI.h.

Constructor & Destructor Documentation

ReflexxesAPI::ReflexxesAPI	(	const unsigned int &	DegreesOfFreedom,
		const double &	CycleTimeInSeconds,
		const unsigned int &	NumberOfAdditionalThreads = `0`
	)

Constructor of the API class ReflexxesAPI (API of the Reflexxes Motion Library)

The constructor of the class ReflexxesAPI sets the respective attributes ReflexxesAPI::CycleTime, ReflexxesAPI::NumberOfDOFs, and ReflexxesAPI::NumberOfOwnThreads, and it creates two objects, one for position-based (TypeIVRMLPosition) and one for velocity-based (TypeIVRMLVelocity) On-Line Trajectory Generation.

Warning: The constructor is not real-time capable as heap memory has to be allocated.

Parameters

DegreesOfFreedom	Specifies the number of degrees of freedom ReflexxesAPI::NumberOfDOFs
CycleTimeInSeconds	Specifies the cycle time of the On-Line Trajectory Algorithms in seconds ReflexxesAPI::CycleTime
NumberOfAdditionalThreads

See also: ReflexxesAPI::NumberOfDOFs; ReflexxesAPI::NumberOfOwnThreads; ReflexxesAPI::CycleTime; ReflexxesAPI::RMLPosition; ReflexxesAPI::RMLVelocity; page_RealTimeBehavior

Definition at line 60 of file ReflexxesAPI.cpp.

ReflexxesAPI::~ReflexxesAPI ( void )

Destructor of the class ReflexxesAPI.

The destructor deletes the two objects for position-based and for velocity-based On-Line Trajectory Generation. If the constructor of the member object ReflexxesAPI::RMLPosition started additional threads, these threads will join the master thread again.

Definition at line 79 of file ReflexxesAPI.cpp.

Member Function Documentation

int ReflexxesAPI::RMLPosition	(	const RMLPositionInputParameters &	InputValues,
		RMLPositionOutputParameters *	OutputValues,
		const RMLPositionFlags &	Flags
	)

This is the central method of each Reflexxes Type Motion Library.

This method executes the position-based Reflexxes On-Line Trajectory Generation algorithm.

Based on the current state of motion ${\bf M}_i$ , the kinematic motion constraints ${\bf B}_i$ , the desired target state of motion ${\bf M}_i^{\,trgt}$ , and the selection vector ${\bf S}_i$ (all of which are contained in ReflexxesAPI::InputValues, a new state of motion ${\bf M}_{i+1}$ is calculated, which can be utilized as a set-point value at instant $T_{i+1}$ . The time difference between ${\bf M}_{i}$ and ${\bf M}_{i+1}$ is ReflexxesAPI::CycleTime (given in seconds).

For a detailed description, please refer to the method TypeIVRMLPosition::GetNextStateOfMotion().

Parameters

InputValues	Specifies the input values of the OTG algorithm, that is, on object of the class RMLPositionInputParameters. Please refer to the page_InputValues for a detailed description.
OutputValues	A pointer to an object of the class RMLPositionOutputParameters. The method will copy the new state of motion as well as further trajectory- relevant data (e.g., minimum and maximum positions and corresponding states of motion) to the object pointed to by `OutputValues`. Please refer to the page_OutputValues for a detailed description.
Flags	An object of the class RMLPositionFlags, which specifies a certain behavior of the called method. For a complete description, please refer to RMLPositionFlags.

Returns

An integer value as specified in ReflexxesAPI::RMLResultValue. If the implementation is correct, the method either returns ReflexxesAPI::RML_WORKING or ReflexxesAPI::RML_FINAL_STATE_REACHED. In general, one of the following values can be returned:

Note: A complete description of the On-Line Trajectory Generation framework may be also found at

T. Kroeger.
On-Line Trajectory Generation in Robotic Systems.
Springer Tracts in Advanced Robotics, Vol. 58, Springer, January 2010.
http://www.springer.com/978-3-642-05174-6

See also: ReflexxesAPI::RMLVelocity(); page_TypeIIAndIVOverview; sec_InputValuesPosition; sec_OutputValuesPosition; page_SynchronizationBehavior

Definition at line 92 of file ReflexxesAPI.cpp.

int ReflexxesAPI::RMLPositionAtAGivenSampleTime	(	const double &	TimeValueInSeconds,
		RMLPositionOutputParameters *	OutputValues
	)

After calling ReflexxesAPI::RMLPosition(), this methods returns the state of motion of the computed trajectory at a given time instant.

If the Reflexxes Motion Library is used for motion profile generation (profiler), this method returns the state of motion at at the instant TimeValueInSeconds that was calculated by the last call of ReflexxesAPI::RMLPosition(). TimeValueInSeconds is given in seconds and w.r.t. to the instant of the last call of ReflexxesAPI::RMLPosition().

Parameters

TimeValueInSeconds	Time instant in seconds, at which the state of motion will be calculated.
OutputValues	A pointer to an object of the class RMLPositionOutputParameters. The method will copy the new state of the instant `TimeValueInSeconds` of motion as well as further trajectory-relevant data (e.g., minimum and maximum positions and corresponding states of motion) to the object pointed to by `OutputValues`. Please refer to the page_OutputValues for a detailed description.

Returns

An integer value as specified in ReflexxesAPI::RMLResultValue. If the implementation is correct, the method either returns ReflexxesAPI::RML_WORKING or ReflexxesAPI::RML_FINAL_STATE_REACHED. In general, one of the following values can be returned:

In case, the call of ReflexxesAPI::RMLPosition() returned an error value, the same error value will be returned by this method.

See also: ReflexxesAPI::RMLPosition(); ReflexxesAPI::RMLVelocityAtAGivenSampleTime(); page_TypeIIAndIVOverview; sec_InputValuesPosition; sec_OutputValuesPosition

Definition at line 105 of file ReflexxesAPI.cpp.

int ReflexxesAPI::RMLVelocity	(	const RMLVelocityInputParameters &	InputValues,
		RMLVelocityOutputParameters *	OutputValues,
		const RMLVelocityFlags &	Flags
	)

This is the method for velocity-based On-Line Trajectory Generation.

This method executes the velocity-based Reflexxes On-Line Trajectory Generation algorithm.

The implementation and the required mathematical back-end is much simpler than for the position-based method (ReflexxesAPI::RMLPosition()). The position-based algorithm is implemented in the class TypeIVRMLPosition, and the velocity-based algorithm is implemented in TypeIVRMLVelocity. Basically, a call of this method behaves in the very same way than a call of RMLPosition(), but it is not possible to specify a desired target position vector $\vec{P}_i{\,trgt}$ and a maximum velocity vector $\vec{V}_i{\,max}$ . Internally, the method TypeIVRMLVelocity::GetNextStateOfMotion() is called. For further details, please refer to this method.

Based on the current state of motion ${\bf M}_i$ , the kinematic motion constraints ${\bf B}_i$ , the desired target velocity vector $\vec{V}_i^{\,trgt}$ , and the selection vector ${\bf S}_i$ (all of which are contained in InputValues, a new state of motion ${\bf M}_{i+1}$ is calculated, which can be utilized as a set-point value at the next control cycle. The time difference between ${\bf M}_{i}$ and ${\bf M}_{i+1}$ is ReflexxesAPI::CycleTime (given in seconds).

Parameters

InputValues	Specifies the input values of the velocity-based OTG algorithm, that is, on object of the class RMLVelocityInputParameters. Please refer to the page_InputValues for a detailed description.
OutputValues	A pointer to an object of the class RMLVelocityOutputParameters. The method will copy the new state of motion as well as further trajectory- relevant data (e.g., minimum and maximum Velocities and corresponding states of motion) to the object pointed to by `OutputValues`. Please refer to the page_OutputValues for a detailed description.
Flags	An object of the class RMLVelocityFlags, which specifies a certain behavior of the called method. For a complete description, please refer to RMLVelocityFlags.

Returns

An integer value as specified in ReflexxesAPI::RMLResultValue. In a correct implementation, the method either returns ReflexxesAPI::RML_WORKING or ReflexxesAPI::RML_FINAL_STATE_REACHED. In general, one of the following values can be returned:

Note: A complete description of the On-Line Trajectory Generation framework may be also found at

T. Kroeger.
On-Line Trajectory Generation in Robotic Systems.
Springer Tracts in Advanced Robotics, Vol. 58, Springer, January 2010.
http://www.springer.com/978-3-642-05174-6

See also: ReflexxesAPI::RMLPosition(); sec_InputValuesVelocity; sec_OutputValuesVelocity; page_SynchronizationBehavior

Definition at line 116 of file ReflexxesAPI.cpp.

int ReflexxesAPI::RMLVelocityAtAGivenSampleTime	(	const double &	TimeValueInSeconds,
		RMLVelocityOutputParameters *	OutputValues
	)

After calling ReflexxesAPI::RMLVelocity(), this methods returns the state of motion of the computed trajectory at a given time instant.

If the Reflexxes Motion Library is used for motion profile generation (profiler), this method returns the state of motion at at the instant TimeValueInSeconds that was calculated by the last call of ReflexxesAPI::RMLVelocity(). TimeValueInSeconds is given in seconds and w.r.t. to the instant of the last call of ReflexxesAPI::RMLVelocity().

Parameters

TimeValueInSeconds	Time instant in seconds, at which the state of motion will be calculated.
OutputValues	A pointer to an object of the class RMLVelocityOutputParameters. The method will copy the new state of the instant `TimeValueInSeconds` of motion as well as further trajectory-relevant data (e.g., minimum and maximum positions and corresponding states of motion) to the object pointed to by `OutputValues`. Please refer to the page_OutputValues for a detailed description.

Returns

An integer value as specified in ReflexxesAPI::RMLResultValue. If the implementation is correct, the method either returns ReflexxesAPI::RML_WORKING or ReflexxesAPI::RML_FINAL_STATE_REACHED. In general, one of the following values can be returned:

In case, the call of ReflexxesAPI::RMLVelocity() returned an error value, the same error value will be returned by this method.

See also: ReflexxesAPI::RMLVelocity(); ReflexxesAPI::RMLPositionAtAGivenSampleTime(); page_TypeIIAndIVOverview; sec_InputValuesVelocity; sec_OutputValuesVelocity

Definition at line 129 of file ReflexxesAPI.cpp.

Member Data Documentation

double ReflexxesAPI::CycleTime

protected

Cycle time in seconds as specified by the constructor ReflexxesAPI()

See also: ReflexxesAPI::ReflexxesAPI()

Definition at line 659 of file ReflexxesAPI.h.

unsigned int ReflexxesAPI::NumberOfDOFs

protected

Positive integer number of degrees of freedom as specified by the constructor ReflexxesAPI()

See also: ReflexxesAPI::ReflexxesAPI()

Definition at line 619 of file ReflexxesAPI.h.

unsigned int ReflexxesAPI::NumberOfOwnThreads

protected

Positive integer number of additional threads as specified by the constructor ReflexxesAPI()

The default value of this parameter is zero, that is, the algorithms of of the Reflexxes Motion Library are executed single-threaded. To achieve the best performance, it is recommended to use the Reflexxes Motion Library in this mode.

Depending on the number of degrees of freedom it can make sense to increase this number. In such a case, the constructor of the class ReflexxesAPI() creates a number of additional working threads. These threads are commonly suspended and are only woken up if the main thread has parallelized computations to do.

See also: ReflexxesAPI::ReflexxesAPI(); page_RealTimeBehavior

Definition at line 644 of file ReflexxesAPI.h.

void * ReflexxesAPI::RMLPositionObject

protected

A pointer to an object for position-based On-Line Trajectory Generation.

Depending on the type of Reflexxes Motion Library, an object containing the functionality for the position-based On-Line Trajectory Generation algorithm is created by the constructor ReflexxesAPI::ReflexxesAPI(). The method ReflexxesAPI::RMLPosition() accesses the functionality of this object.

See also: ReflexxesAPI::ReflexxesAPI(); ReflexxesAPI::RMLVelocityObject

Definition at line 680 of file ReflexxesAPI.h.

void * ReflexxesAPI::RMLVelocityObject

protected

A pointer to an object for velocity-based On-Line Trajectory Generation.

Depending on the type of Reflexxes Motion Library, an object containing the functionality for the velocity-based On-Line Trajectory Generation algorithm is created by the constructor ReflexxesAPI::ReflexxesAPI(). The method ReflexxesAPI::RMLVelocity() accesses the functionality of this object.

See also: ReflexxesAPI::ReflexxesAPI(); ReflexxesAPI::RMLPositionObject

Definition at line 701 of file ReflexxesAPI.h.

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

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation