Axis Tolerances and Related Events:
How Motion Related Events are Generated

There are five types of generated events related to motion: MOTION_DONE, MOTION_AT_VELOCITY, and NEAR_TARGET, AT_TARGET, and SETTLED. Motion completion for a position move is indicated by a MOTION_DONE event, while motion completion for a velocity move is indicated by an MOTION_AT_VELOCITY event.

For both position moves and velocity moves, the MPI uses a settling time window to determine when to generate a motion completed event (to indicate that motion has finished on an axis).

For position moves, the MPI uses the settling time window to determine when an axis has reached the final target location and is stable.

For velocity moves, the MPI uses the settling time window to determine when an axis has reached the final velocity. This works because during ringing, the velocity is highest when the position error is lowest. (Velocity and position error are inversely-related.)

Position and Velocity criteria for generating motion completion events

For a	A "motion completed" event is generated when	Criteria
Position move	ABS(position error) < MPIAxisConfig.settle.tolerance.distance	position
Position move		position
Position move	ABS(velocity error) < MPIAxisConfig.settle.tolerance.speed	velocity
Velocity move	ABS(velocity error) < MPIAxisConfig.settle.tolerance.speed	velocity

*where*:
	position error = (command position – actual position)
	velocity error = (command velocity – actual velocity)

For Position Moves
A MOTION_DONE event is generated by a position move only after both the position and velocity criteria have been met for the period specified by the settling time. To determine if motion has completed, position moves use both position and velocity criteria.

A MOTION_DONE event is also generated by a velocity move only if the target velocity is zero and the velocity criteria have been met for the period specified by the settling time.

We included the ability to additionally use the velocity criteria for position moves because some users prefer to decide that an axis is "settled" only after the position error and actual velocity are both low enough.

For Velocity Moves
An MOTION_AT_VELOCITY event is generated for a velocity move only after the velocity criteria has been met for the period specified by the settling time. To determine if motion has completed, velocity moves use only the velocity criteria (they don't use the position criteria).

Note that the motion completed event generated this time is an MOTION_AT_VELOCITY event rather than a MOTION_DONE event. For velocity moves, MOTION_DONE events will only occur after mpiMotionAction(..., MPIActionSTOP) or if the target command velocity is zero.

You can also use the velocity criteria to determine when ringing has stopped after an open loop commutation move. To do this, the position criteria is effectively disabled by setting the position tolerance to a very large value (e.g., 1.0E10). After that, the MOTION_DONE event following a move is determined entirely by the velocity tolerance and settling time, and, therefore, the event will be generated only after the ringing has stopped.

Be aware that setting MPIAxisConfig.settle.tolerance.speed to 0 does not disable the velocity criteria. For high resolution feedback, setting MPIAxisConfig.settle.tolerance.speed to 0 makes it very difficult to meet the criteria of 0 counts of motion for settlingTime seconds.

Setting Time Parameters

Four Settling Time Parameters

For position moves, the generation of DONE events depends on three parameters:

MPIAxisConfig.settle.time
MPIAxisConfig.settle.tolerance.distance
MPIAxisConfig.settle.tolerance.speed

DONE events are only generated when command = target or after STOP, ESTOP or ABORT events.

For velocity moves, the generation of AT_VELOCITY events depends on two parameters:

MPIAxisConfig.settle.time
MPIAxisConfig.settle.tolerance.speed

The settling.time value specifies the amount of time (seconds) that a motion must be within the settle.tolerance.distance band, in order for the motion to be considered complete (finished).

The settle.tolerance.distance parameter is a tolerance (encoder counts), where we know a motion is complete if the motion settles within this tolerance.

The settle.tolerance.speed parameter specifies a band around the target velocity for velocity moves.

A fourth parameter (MPIAxisConfig.nearTargetDistance) specifies a band around the final position.

MPIXmpStatusIN_FINE_POSITION | MPIXmpStatusIN_COARSE_POSITION
MPIXmpStatusAT_TARGET | MPIXmpStatusAT_VELOCITY
MPIXmpStatusDONE

MPIEventTypeSETTLED

During Normal Conditions (no Stop, E-stop, or Abort)
Between commanded motion and AT_TARGET, SETTLED is FALSE.

After AT_TARGET, the evaluation of the settling criteria begins. When the settling criteria has been satisfied, SETTLE is TRUE.

The settling criteria are:

The absolute value of the position error is less than or equal to the settle distance position tolerance.
The absolute value of the velocity is less than or equal to the settle speed tolerance.
Both of the above criteria has been satisfied for the settling time. Whenever either criteria 1 or 2 is not satisfied, SETTLED is cleared and the settling timer is reset.

During STOP
If settleOnStop is FALSE, SETTLED is FALSE.
If settleOnStop is TRUE and Feedrate != 0, SETTLED is FALSE.
If settleOnStop is TRUE and Feedrate = = 0, evaluation of the settling criteria begins.
After the settling criteria has been satisfied, SETTLED is TRUE.

During E-STOP
If settleOnEstop is FALSE, SETTLED is FALSE.
If settleOnEstop is TRUE and Feedrate != 0, SETTLED is FALSE.
If settleOnEstop is TRUE and Feedrate = = 0, evaluation of the settling criteria begins.
After the settling criteria has been satisfied, SETTLED is TRUE.

If both E-STOP and STOPoccur simultaneously
If both settleOnStop and settleOnEstop are FALSE, SETTLED is FALSE.
If either settleOnStop or settleOnEstop are TRUE and Feedrate != 0, SETTLED is FALSE.
If either settleOnStop or settleOnEstop are TRUE and Feedrate = = 0, evaluation of the settling criteria begins.
After the settling criteria has been satisfied SETTLED is TRUE.

Note: If STOP and E-STOP occur simultaneously, the controller applies priority to the E-STOP. Both status bits will be true, but the motion will decelerate at the E-STOP rate.

During ABORT
IN_FINE_POSITION is FALSE.

If both E-STOP and ABORT occur simultaneously
During an E-Stop_Abort condition, SETTLED is FALSE (even if settleOnEstop is TRUE).

After mpiMotionAction(..., MPIActionRESET)
If SETTLED status is TRUE before RESET, the status will be unaffected (no event generated).
If SETTLED status is FALSE, the effect of RESET depends on the cause: If SETTLED is FALSE because:

The position error exceeds the tolerance, SETTLED will remain FALSE (no event generated).
The position error is within the tolerance but STOP is TRUE and settleOnStop is FALSE, SETTLED will become TRUE at settlingTime after the RESET call (event will be generated).
The position error is within the tolerance but E_STOP is TRUE and settleOnEstop is FALSE, SETTLED will become TRUE at settlingTime after the RESET (event will be generated).
The position error has been within the tolerance for settlingTime but ABORT is TRUE, SETTLED will become TRUE immediately after the RESET (event will be generated).

MPIEventTypeNEAR_TARGET

During Normal Conditions (no Stop, E-stop, or Abort)
The NEAR_TARGET status bit can be set only during motion (defined from commaned motion) until MOTION_DONE is set for the following motion types:

S-Curve (final velocity = 0)
Trap
PT (after final point has been specified)
PVT (after final point has been specified)

For these motion types NEAR_TARGET is TRUE whenever the absolute distance to the target (measured from the actual position to the final position) is less than or equal to the near target distance tolerance. If the target position is changed by modifying motion, NEAR_TARGET may be set and cleared more than once (causing multiple events) during a single move.

NEAR_TARGET is always FALSE for velocity moves (or moves where the final velocity is non-zero).

During STOP, E-STOP, or ABORT
NEAR_TARGET is FALSE.

After mpiMotionAction(..., MPIActionRESET)
NEAR_TARGET is FALSE.

MPIEventTypeAT_TARGET

During Normal Conditions (no Stop, E-stop, or Abort)
The AT_TARGET status bit can be set only during motion (defined from commaned motion) until Motion_DONE is set for the following motion types:

S-Curve (final velocity = 0)
Trap
PT (after final point has been specified)
PVT (after final point has been specified)

For these motion types AT_TARGET is TRUE whenever the command position is equal to to the target (final) position. If the target position is changed by modifying motion, AT_TARGET may be set and cleared more than once (causing multiple events) during a single move.

AT_TARGET is always FALSE for velocity moves (or moves where the final velocity is non-zero).

During STOP, E-STOP, or ABORT
AT_TARGET is always FALSE.

After mpiMotionAction(..., MPIActionRESET)
AT_TARGET is always FALSE.

MPIEventTypeMOTION_AT_VELOCITY

During Normal Conditions (no Stop, E-stop, or Abort)
The MOTION_AT_VELOCITY status bit can only be set during the constant velocity portions for the following move types:

Velocity
S-Curve (final velocity = 0)

The velocity settling criteria are continuously evaluated during the constant velocity portion of the motion. Once the criteria has been satisfied, the MOTION_AT_VELOCITY bit is set to TRUE. MOTION_AT_VELOCITY is FALSE during any non-constant velocity portions of the motion.

The velocity settling criteria are:

The absolute value of the velocity error is less than or equal to the velocity tolerance.
Criteria 1 has been satisfied for the settling time. Whenever Criteria 1 is not satisfied, MOTION_AT_VELOCITY is set to FALSE and the settling timer is reset.

After Reset, Stop, E-stop, or Abort
After a Reset, Stop, E-Stop, or Abort, MOTION_AT_VELOCITY is always FALSE.

MPIEventTypeMOTION_DONE

This status bit is set to TRUE whenever SETTLED is TRUE. It can be cleared only by commanding a move.

After mpiMotionAction(..., MPIActionRESET)
DONE is always TRUE.