Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

MotionCommand Class Reference

The abstract base class for motions, provides common interface. All motions should inherit from this. More...

#include <MotionCommand.h>

Inheritance diagram for MotionCommand:
Inheritance graph
[legend]

Detailed Description

The abstract base class for motions, provides common interface. All motions should inherit from this.

For instructions on how to create:

To create a new type of motion, you'll want to subclass this. You don't need to do anything fancy, but just be sure to override the 3 abstract functions, updateOutputs(), isAlive(), and isDirty().

There is a quick-start boilerplate included in the distribution: project/templates/motioncommand.h:

When an output is set to a value, that output is held at that value until it is set to a new value, even if the MotionCommand that set it is pruned or stops using the output. Outputs never "reset" to 0 or some other relatively arbitrary base value if all the MotionCommands are removed.

However, PID values will reset to the default values if pruned or not set since these values do have a base value which you will want to use 99% of the time.

Be aware that there is a delay between when you set a joint to a value and that actually is taken into account by the system - it's on the order of FrameTime*NumFrames (currently 8*4 = 32 ms, so worse case 2*8*4 = 64 ms) This is because the commands are double buffered. PIDs, on the other hand, seem to take effect more quickly. This un-synchronization can sometimes cause a bit of jerkiness (mainly on startup, where there's a large difference between desired and target values.)

Here is the cycle of calls made by MotionManager to your command:

  1. shouldPrune() (by default, this will return !isAlive() iff autoprune==true)
  2. updateOutputs() (assuming the MC wasn't pruned after the previous step)

So, if you want to hold a joint at a value, each time your updateOutputs function is called, you should tell the MotionManager to keep the joint there (using one of MotionManager::setOutput()'s). If you do not set a joint after a call to updateOutputs, the MotionManager will assume you are no longer using that joint and a lower priority MotionCommand may inherit it.

MotionCommands which generate events should use the inherited MotionCommand::postEvent() instead of trying to access a global erouter - the inherited version will properly handle sending the events regardless of the current process context, but trying to access a non-shared global like erouter could cause problems otherwise.

Warning:
Be careful what you call in MotionManager
Some functions are marked MotionCommand-safe - this is another issue due to our "fake" fork. In short, when a function is called on a MotionCommand, it uses the context of whatever process created it, not the process that actually made the function call. Thus, when Motion calls updateOutputs(), calls that the MotionCommand makes are indistinguishable from concurrent calls from Main. This can cause deadlock if a function is called which locks the MotionManager. To get around this, we need to pass the 'this' parameter on functions that require a lock, namely MotionManager::setOutputs(). This allows the MotionManager to figure out that it's the same MotionCommand it previously called updateOutputs() on, and thus avoid trying to lock itself again.
Don't store pointers in motion commands!
Since motion commands are in shared memory, and these shared memory regions can have different base pointers in each process, pointers will only be valid in the process from which they were assigned. In other processes, that address may point to something else, especially if it was pointing outside of the shared memory regions.
There are convoluted ways of getting around this. If needed, MotionManager could be modified to hand out shared memory regions upon request. Let's try to avoid this for now. Keep MotionCommands simple, without dynamic memory. Do more complicated stuff with behaviors, which only have to worry about running in Main.

Definition at line 92 of file MotionCommand.h.

List of all members.

Public Member Functions

*** ABSTRACT: *** (must be defined by subclasses)

virtual int updateOutputs ()=0
 is called once per update cycle, can do any processing you need to change your priorities or set output commands on the MotionManager
virtual int isDirty ()=0
 not used by MotionManager at the moment, but could be used to reduce recomputation, and you may find it useful
virtual int isAlive ()=0
 used to prune "dead" motions from the MotionManager

Protected Member Functions

void postEvent (const EventBase &event)
 calls EventTranslator::trapEvent() directly (avoids needing erouter, which is a non-shared global, causes problems with context, grr, silly OS)

Protected Attributes

EventTranslator * queue
 send events using this, instead of posting to the erouter
int autoprune
 default true, autoprune setting, if this is true and isAlive() returns false, MotionManager will attempt to remove the MC automatically
bool started
 true if the MotionCommand is currently running (although it may be overridden by a higher priority MotionCommand)

Private Member Functions

 MotionCommand (const MotionCommand &)
 don't call
MotionCommand & operator= (const MotionCommand &)
 don't call

*** INHERITED: ***



 MotionCommand ()
 Constructor: Defaults to kStdPriority and autoprune==true.
virtual ~MotionCommand ()
 Destructor.
virtual void start ()
 called after this is added to MotionManager; don't override this, use doStart instead
virtual void stop ()
 called after this is removed from MotionManager; don't override this, use doStop instead
virtual bool isActive () const
 returns true if the MotionCommand is currently running (although it may be overridden by a higher priority MotionCommand)
virtual bool getAutoPrune ()
virtual void setAutoPrune (bool ap)
virtual bool shouldPrune ()
 whether this motion should be removed from its motion group automatically ( MotionCommand::autoprune && !isAlive())
void setTranslator (EventTranslator *q)
 only called from MMCombo during process setup, allows MotionCommands to send events
virtual void doStart ()
 Override this if you want to run some startup code after being added to the MotionManager.
virtual void doStop ()
 Override this if you want to clean up after removal from MotionManager.
static double interpolate (double a, double b, double x)
 this utility function will probably be of use to a lot of MotionCommand's
static float interpolate (float a, float b, float x)
 this utility function will probably be of use to a lot of MotionCommand's
static void interpolate (const OutputCmd &a, const OutputCmd &b, float x, OutputCmd &r)
 this utility function will probably be of use to a lot of MotionCommand's, see interpolate(double a,double b,double r)

Constructor & Destructor Documentation

MotionCommand::MotionCommand (  ) 

Constructor: Defaults to kStdPriority and autoprune==true.

Definition at line 124 of file MotionCommand.h.

Referenced by DynamicMotionSequence::DynamicMotionSequence().

virtual MotionCommand::~MotionCommand (  )  [virtual]

Destructor.

Definition at line 130 of file MotionCommand.h.

MotionCommand::MotionCommand ( const MotionCommand &   )  [private]

don't call

Member Function Documentation

virtual void MotionCommand::doStart (  )  [protected, virtual]

Override this if you want to run some startup code after being added to the MotionManager.

Reimplemented in ArmMC, GaitedFootstepMC, HeadPointerMC, LedMC, PIDMC, and PostureMC.

Definition at line 161 of file MotionCommand.h.

Referenced by start().

virtual void MotionCommand::doStop (  )  [protected, virtual]

Override this if you want to clean up after removal from MotionManager.

The old MotionManagerMsg::mc_id will still be available, but this value is no longer valid within the MotionManager. Only use it if you need to clean up associated values stored elsewhere.

Reimplemented in GaitedFootstepMC.

Definition at line 165 of file MotionCommand.h.

Referenced by stop().

virtual bool MotionCommand::getAutoPrune (  )  [virtual]
Returns:
current setting of autopruning - used to remove motion from groups when !isAlive()

Definition at line 142 of file MotionCommand.h.

Referenced by PostureMC::isAlive(), HeadPointerMC::isAlive(), ArmMC::isAlive(), and MotionManager::RemoveAccess().

static void MotionCommand::interpolate ( const OutputCmd &  a,
const OutputCmd &  b,
float  x,
OutputCmd &  r 
) [static, protected]

this utility function will probably be of use to a lot of MotionCommand's, see interpolate(double a,double b,double r)

interpolates both value and weights of JointCmd's

Parameters:
a first joint cmd
b second joint cmd
x weight to favor b's value and weight
r joint cmd to store the result

Definition at line 193 of file MotionCommand.h.

static float MotionCommand::interpolate ( float  a,
float  b,
float  x 
) [static, protected]

this utility function will probably be of use to a lot of MotionCommand's

Does a weighted average of a and b, favoring b by x percent (so x==0 results in a, x==1 results in b)

Parameters:
a first value
b second value
x weight of second value as opposed to first
Returns:
$ a*(1.0-x)+b*x $
Todo:
  • replace with a more fancy spline based thing?

Definition at line 184 of file MotionCommand.h.

static double MotionCommand::interpolate ( double  a,
double  b,
double  x 
) [static, protected]

this utility function will probably be of use to a lot of MotionCommand's

Does a weighted average of a and b, favoring b by x percent (so x==0 results in a, x==1 results in b)

Parameters:
a first value
b second value
x weight of second value as opposed to first
Returns:
$ a*(1.0-x)+b*x $
Todo:
  • replace with a more fancy spline based thing?

Definition at line 174 of file MotionCommand.h.

Referenced by interpolate().

virtual bool MotionCommand::isActive (  )  const [virtual]

returns true if the MotionCommand is currently running (although it may be overridden by a higher priority MotionCommand)

Definition at line 139 of file MotionCommand.h.

virtual int MotionCommand::isAlive (  )  [pure virtual]

used to prune "dead" motions from the MotionManager

note that a motion could be "paused" or inactive and therefore not dirty, but still alive, biding its time to "strike" ;)

Returns:
zero if the motion is still processing, non-zero otherwise

Implemented in ArmMC, CMPackWalkMC, DynamicMotionSequence, GaitedFootstepMC, HeadPointerMC, LedMC, MotionSequenceMC< MAXMOVE >, PIDMC, PostureMC, RemoteControllerMC, SineMC, TailWagMC, UPennWalkMC, WheeledWalkMC, and XWalkMC.

Referenced by shouldPrune().

virtual int MotionCommand::isDirty (  )  [pure virtual]

not used by MotionManager at the moment, but could be used to reduce recomputation, and you may find it useful

Returns:
zero if none of the commands have changed since last getJointCmd(), else non-zero

Implemented in ArmMC, CMPackWalkMC, DynamicMotionSequence, GaitedFootstepMC, HeadPointerMC, LedMC, MotionSequenceMC< MAXMOVE >, PIDMC, PostureMC, SineMC, TailWagMC, UPennWalkMC, WheeledWalkMC, and XWalkMC.

MotionCommand& MotionCommand::operator= ( const MotionCommand &   )  [private]

don't call

void MotionCommand::postEvent ( const EventBase &  event  )  [protected]

calls EventTranslator::trapEvent() directly (avoids needing erouter, which is a non-shared global, causes problems with context, grr, silly OS)

Definition at line 11 of file MotionCommand.cc.

Referenced by EmergencyStopMC::freezeJoints(), EmergencyStopMC::releaseJoints(), XWalkMC::setTargetVelocity(), XWalkMC::updateOutputs(), TailWagMC::updateOutputs(), PostureMC::updateOutputs(), PIDMC::updateOutputs(), MotionSequenceMC< MAXMOVE >::updateOutputs(), LedMC::updateOutputs(), HeadPointerMC::updateOutputs(), ArmMC::updateOutputs(), XWalkMC::updateOutputsInitial(), and XWalkMC::zeroVelocities().

virtual void MotionCommand::setAutoPrune ( bool  ap  )  [virtual]
Parameters:
ap bool representing requested autopruning setting

Definition at line 145 of file MotionCommand.h.

Referenced by MotionManager::doAddMotion().

void MotionCommand::setTranslator ( EventTranslator *  q  ) 

only called from MMCombo during process setup, allows MotionCommands to send events

Definition at line 152 of file MotionCommand.h.

Referenced by MotionManager::checkinMotion(), and MotionManager::convertMotion().

virtual bool MotionCommand::shouldPrune (  )  [virtual]

whether this motion should be removed from its motion group automatically ( MotionCommand::autoprune && !isAlive())

Returns:
(MotionCommand::autoprune && !isAlive())

Definition at line 149 of file MotionCommand.h.

Referenced by MotionManager::getOutputs().

virtual void MotionCommand::start (  )  [virtual]

called after this is added to MotionManager; don't override this, use doStart instead

Reimplemented in CMPackWalkMC, WheeledWalkMC, and XWalkMC.

Definition at line 133 of file MotionCommand.h.

Referenced by SineMC::getAcceleration(), SineMC::getCount(), SineMC::getOffsetTime(), SineMC::getSpeed(), SineMC::setParams(), SineMC::sync(), SineMC::syncAll(), and SineMC::updateOutputs().

virtual void MotionCommand::stop (  )  [virtual]

called after this is removed from MotionManager; don't override this, use doStop instead

Reimplemented in CMPackWalkMC, WheeledWalkMC, and XWalkMC.

Definition at line 136 of file MotionCommand.h.

Referenced by MotionManager::removeMotion().

virtual int MotionCommand::updateOutputs (  )  [pure virtual]

is called once per update cycle, can do any processing you need to change your priorities or set output commands on the MotionManager

Returns:
zero if no changes were made, non-zero otherwise
See also:
RobotInfo::NumFrames
RobotInfo::FrameTime

Implemented in ArmMC, CMPackWalkMC, DynamicMotionSequence, EmergencyStopMC, GaitedFootstepMC, HeadPointerMC, LedMC, MotionSequenceMC< MAXMOVE >, PIDMC, PostureMC, RemoteControllerMC, SineMC, TailWagMC, UPennWalkMC, WaypointWalkMC, WheeledWalkMC, and XWalkMC.

Referenced by MotionManager::getOutputs().

Member Data Documentation

int MotionCommand::autoprune [protected]

default true, autoprune setting, if this is true and isAlive() returns false, MotionManager will attempt to remove the MC automatically

Definition at line 203 of file MotionCommand.h.

Referenced by getAutoPrune(), setAutoPrune(), and shouldPrune().

EventTranslator* MotionCommand::queue [protected]

send events using this, instead of posting to the erouter

Definition at line 201 of file MotionCommand.h.

Referenced by postEvent(), and setTranslator().

bool MotionCommand::started [protected]

true if the MotionCommand is currently running (although it may be overridden by a higher priority MotionCommand)

Definition at line 204 of file MotionCommand.h.

Referenced by isActive(), start(), and stop().

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

Tekkotsu v5.1CVS
 		Generated Mon May 9 04:59:13 2016 by Doxygen 1.6.3