Actin  Version 5.5.1
Software for Robotics Simulation and Control
Group Motion Manager

Introduction

The group motion manager provides PLCopen compliant (Part 4 - Coordinated Motion) C++ function blocks (FBs) for axes group motion control.

To maximize portability, methods provided by the EcGroupMotionManager are not thread safe. Please use thread synchronization mechanisms provided by target operating systems to protect the EcGroupMotionManager. Const methods should be protected by read lock. Non-const methods should be protected by write lock. Static methods need not be protected.

Motion Buffer

The group motion manager holds a motion buffer. Motions are added to the buffer in different behaviors depending on the buffer mode.

A const reference of the motion buffer can be acquired by EcGroupMotionManager::motionBuffer.

The default capacity of the motion buffer is 32. The capacity automatically doubles (but will not exceeds 2^31-1) if there is not enough space to hold new motions. Alternatively, the capacity can be set directly.

Buffer Mode

Currently the group motion manager supports ABORTING, BUFFERED, and BLENDING_NEXT modes (defined in EcGroupMotionManager::BufferMode).

  • In ABORTING mode, the motion buffer is cleared then the new motion is added. The new motion aborts current motion and starts immediately.
  • In BUFFERED mode, the new motion is queued in the motion buffer and runs only when the previous motion has finished. There is no blending. So the transition mode of the previous motion is not evaluated.
  • In BLENDING_NEXT mode, the new motion is queued in the motion buffer and is blended with the previous motion. The velocity is blended using the velocity parameter of the new motion.

Transition Mode

Currently the group motion manager supports CORNER_DISTANCE mode (defined in EcGroupMotionManager::TransitionMode).

State Diagram

The group motion manager has a state machine. The states are defined in EcGroupMotionManager::Status.

The state machine updates when running the manager based on the operation flag (see Group Operations) and individual motion status. The operation flags are defined in EcGroupMotionManager::Operation.

The state diagram is as below.

EcGroupMotionManager.png
State diagram.
  1. While in GROUP_STANDBY, if there are motions in the buffer and the operation flag is OP_EXECUTE, the state transits to GROUP_MOVING.
  2. While in GROUP_STANDBY, calling groupHalt aborts all motions in the buffer synchronously and the state remains in GROUP_STANDBY.
  3. While in GROUP_STANDBY, if groupInterrupt is called, the state transits to GROUP_INTERRUPTED synchronously.
  4. While in GROUP_STANDBY, if errors happen or if groupStop is called, the state transits to GROUP_ERROR_STOP directly.
  5. If all motions succeed, the state transits back to GROUP_STANDBY.
  6. While in GROUP_MOVING, if the operation flag is OP_INTERRUPT, OP_HALT, or OP_STOP, the state transits to GROUP_STOPPING while performing controlled stop.
  7. While in GROUP_STOPPING, if the operation flag is OP_INTERRUPT, calling groupContinue or adding a new motion in ABORTING mode can abort the stopping. If the operation flag is OP_HALT, adding a new motion in ABORTING mode can abort the stopping. The state transits back to GROUP_MOVING.
  8. When all axes stop moving, the state transits to
    • GROUP_STANDBY, if the operation flag is OP_HALT. The operation flag will be automatically reset to OP_EXECUTE.
    • GROUP_INTERRUPTED if the operation flag is OP_INTERRUPT.
    • GROUP_ERROR_STOP, if the operation flag is OP_STOP.
  9. While in GROUP_INTERRUPTED, motions can be continued if the operation flag is OP_EXECUTE by calling groupContinue.
  10. GROUP_INTERRUPTED can be halted by calling groupHalt.
  11. GROUP_INTERRUPTED can be stopped by calling groupStop.
  12. The only way to get out of the GROUP_ERROR_STOP state is by calling groupReset which clears the motion buffer and sets the operation flag to OP_EXECUTE.

Create, Config, and Run

See controlExecutiveModifierExample::runGroupMotionManager in controlExecutiveModifierExampleMain.cpp for an example of using EcGroupMotionManager.

Create an Instance

An instance of the group motion manager can be created using the default constructor of EcGroupMotionManager or the constructor with a manipulator index. If the default constructor is used, EcGroupMotionManager::setManipulatorIndex must be called later to set the manipulator index.

const EcU32 manipIndex = 0;
groupMotion.setManipulatorIndex(manipIndex);
const EcU32 manipIndex = 0;
EcGroupMotionManager groupMotion(manipIndex);

Although it is possible to change the manipulator index even after it is set, this is not recommended and do not do it when there are motions still in the buffer.

Set Buffer Capacity

EcGroupMotionManager::setBufferCapacity changes the buffer capacity. The capacity must be > 0, otherwise, this command will do nothing. Enlarging the buffer is always safe. However, it is not recommended to shrink the buffer when there are motions still in the buffer.

Run

(
const EcReal currentTime
);

This API performs motion planning and updates the state machine. An EcBaseControlSystemModifier instance is required and should be protected by a write lock.

If an EcControlSystemExecutiveModifier instance is used, this method should be called before EcControlSystemExecutiveModifier::calculateStateTimeSteps using the state time. See also Calculate State.

Administrative FBs

groupReadStatus

EcGroupMotionManager::groupReadStatus reads the state machine state.

Group Motions

All motion FBs return an monotonically increasing 32-bit integer ID of the motion. The motion ID can be later used to query its status using readMotionStatus. An ID < 0 means the motion is not accepted by the motion manager. This could be due to:

  • The group motion manager's STOP flag is raised.
  • The group motion manager's HALT flag is raised and the buffer mode is not ABORTING.
  • The motion buffer is full and the buffer mode is not ABORTING.

moveDirectAbsolute

EcGroupMotionManager::moveDirectAbsolute commands a movement of an axes group to the specified absolute joint positions.

moveLinearAbsolute

EcGroupMotionManager::moveLinearAbsolute commands a linear movement from the actual pose of the TCP to an absolute pose in the frame the end-effector is relative to.

moveCircularAbsolute

EcGroupMotionManager::moveCircularAbsolute commands an interpolated circular movement on an axes group from the actual position of the TCP. See figure. There are 2 overloaded versions.

  • Uses boarder point and end point.
  • Uses center, normal, central angle.

moveHelicalAbsolute

EcGroupMotionManager::moveHelicalAbsolute commands an interpolated helical movement on an axes group from the actual position of the TCP. See figure.

movePath

EcGroupMotionManager::movePath commands an axes group to move according to the specified path. A typical use case is run g-codes in an NC file loaded by EcEndEffectorMotionMovePath::loadGCodeFile.

Transformation FBs

setKinTransform

EcGroupMotionManager::setKinTransform sets the tool offset (in end-effector frame). This FB is always buffered.

setCoordinateTransform

EcGroupMotionManager::setCoordinateTransform sets a coordinate transformation between the MCS (Machine Coordinate System) and PCS (Part Coordinate System). Subsequent motions will use the new PCS. Setting the PCS to be NULL will use MCS.

Group Operations

groupInterrupt

EcGroupMotionManager::groupInterrupt interrupts the ongoing motion, commands a controlled stop, and eventually transfers the axes group to the state GROUP_INTERRUPTED. While stopping, the relevant axes stay on the path.

The command does not abort the interrupted motion. The interrupted motion can be continued by calling groupContinue when in the GROUP_INTERRUPTED state.

This command is only accepted (returns true) when the current operation <= OP_INTERRUPT. If accepted, the command sets the operation flag to OP_INTERRUPT.

groupContinue

EcGroupMotionManager::groupContinue continues the motion previously interrupted by setting the operation flag to OP_EXECUTE.

This command is only accepted (returns true) when the current operation <= OP_INTERRUPT.

groupHalt

EcGroupMotionManager::groupHalt aborts any ongoing motion, commands a controlled stop, and eventually transfers the axes group to the state GROUP_STANDBY.

This command is used to stop the axes group under normal operation conditions. It is only accepted (returns true) when the current operation <= OP_HALT. If accepted, the command sets the operation flag to OP_HALT.

groupStop

EcGroupMotionManager::groupStop aborts any ongoing motion, commands a controlled stop, and eventually transfers the axes group to the state GROUP_ERROR_STOP.

This command is used to trigger error stop externally. It is always accepted and sets the operation flag to OP_STOP. While the stop flag is set, no motions can be added on the same axes group even in ABORTING mode. The only way to transit out of GROUP_ERROR_STOP is by calling groupReset.

Note that the stop flag can also be set internally if an error happens.

groupReset

EcGroupMotionManager::groupReset clears the motion buffer, sets the current state to GROUP_STANDBY and the operation flag to OP_EXECUTE.

This command is only accepted (returns true) when the current state == GROUP_ERROR_STOP.

Actin APIs

motionBuffer

EcGroupMotionManager::motionBuffer gets a const reference of the motion buffer.

readMotionStatus

EcGroupMotionManager::readMotionStatus reads individual motion status given the motion ID.

The motion manager buffers the same number of motion IDs as the motion buffer capacity. If the motion ID is not found, this command returns false.

reset

EcGroupMotionManager::reset immediately clears the motion buffer, sets the operation flag to OP_EXECUTE and the state to GROUP_STANDBY. The motion ID will restart from 0.