Settling

Table of Contents

• 🔹 What is Axis Settling?
• 🔹 Settling Criteria
  • 1. Fine Position Tolerance
  • 2. Coarse Position Tolerance
  • 3. Velocity Tolerance
  • 4. Settling Time
• 🔹 Summary Interrupts
• 🔹 For Position Moves
  • Parameters
• 🔹 Interrupts and Status Bits
  • IN_COARSE_POSITION
  • AT_TARGET
  • IN_FINE_POSITION
  • MOTION_DONE
  • AT_VELOCITY
• 🔹 RapidCode Functions
• 📜 Sample Code
  • Configure Axis Settling Parameters
  • Examine Iterrupts

Define and manage axis settling criteria for motion completion, including fine and coarse position tolerances, velocity tolerance, and settling time, applicable to both position and velocity moves.

🔹 What is Axis Settling?

Axis Settling is the process of the RMP firmware determining that all settling criteria for a move has been met, before resulting in MOTION_DONE (status bit, and optionally, an interrupt).

In order for a move to be considered settled (done), the Fine Position Tolerance and Actual Velocity Tolerance must be within range for the time specified by SettlingTimeSet().

🔹 Settling Criteria

The settling criteria help you configure the triggers for various motion interrupts.

The four criteria are:

1. Fine Position Tolerance

For some applications, it is not necessary for moves to land at exactly the commanded position. The fine position tolerance can be configured for each application to specify how close is “close enough”. This parameter is only considered during position moves.

2. Coarse Position Tolerance

Coarse position tolerance controls a second interrupt that signifies that the motor is “near” the commanded position. This value should be greater than or equal to the fine position tolerance. This parameter is only considered during position moves.

3. Velocity Tolerance

For a velocity move, the velocity tolerance dictates how close the actual velocity of the motor must be to the commanded velocity to be considered “at velocity”. It is recommended that you use a non-zero Settling Time when leveraging this for position moves. This parameter is considered during position and velocity moves.

4. Settling Time

The settling time dictates how long a particular metric must be within the ranges detailed above before the appropriate interrupt is triggered.

The sample app below shows how to adjust settling criteria through RapidCode. These parameters can also be adjusted through RapidSetup under the Axis “Settling Criteria” tab (shown below)

🔹 Summary Interrupts

There are five types of generated interrupts related to motion:

1. MOTION_DONE – This event indicates motion completion (fully settled) for a position move.

2. MOTION_AT_VELOCITY – This event indicates motion completion for a velocity move.

3. IN_COARSE_POSITION - This event indicates the motion is near the target position.

4. AT_TARGET - This event indicates the command position has reached the target position.

5. SETTLED - This event indicates all the settling criteria have been met for the duration of Settling Time.

For both position moves and velocity moves, the firmware 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 firmware uses the settling time window to determine when an axis has reached the final target location and is stable.

For velocity moves, the firmware 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.)

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

🔹 For Position Moves

A MOTION_DONE interrupt 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 been completed, position moves to use both position and velocity criteria.

A MOTION_DONE interrupt 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.

The default (factory) value for VelocityTolerance is 20,000,000 counts/sec. 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.

A MOTION_AT_VELOCITY interrupt is generated for a velocity move only after the velocity criteria have been met for the period specified by the settling time. To determine if motion has been completed, velocity moves using only the velocity criteria (they don’t use the position criteria).

Note

The motion completed interrupt generated this time is a MOTION_AT_VELOCITY interrupt rather than a MOTION_DONE interrupt.

For velocity moves, MOTION_DONE interrupt will only occur after commanding a Stop() or if the target command velocity is zero.

Be aware that setting VelocityTolerance to 0 does not disable the velocity criteria. For high-resolution encoders, setting VelocityTolerance to 0 makes it very difficult to meet the criteria of 0 counts of motion for settling time seconds.

For position moves, the generation of MOTION_DONE interrupts depends on three parameters:

1. SettlingTime
2. PositionFine/PositionToleranceFine
3. Velocity/VelocityTolerance

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

1. SettlingTime
2. Velocity/VelocityTolerance

Parameters

SettlingTime
This parameter specifies the amount of time (seconds) that a motion must be within the PositionToleranceFine band, in order for the motion to be considered complete (finished).

PositionFine/PositionToleranceFine
This parameter is a tolerance (encoder counts), where we know a motion is complete if the motion settles within this tolerance.

Velocity/VelocityTolerance
This parameter specifies a band around the target velocity for velocity moves.

PositionCoarse/PositionToleranceCoarse
This parameter, specifies a band around the final position.

🔹 Interrupts and Status Bits

IN_COARSE_POSITION

IN_COURSE_POSITION 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 coarse position tolerance. If the target position is changed by commanding a new motion on the fly, IN_COURSE_POSITION may be set and cleared more than once (causing multiple interrupts) during a single move.

AT_TARGET

AT_TARGET is TRUE whenever the command position is equal to the target (final) position. If the target position is changed by commanding a new motion on the fly, AT_TARGET may be set and cleared more than once (causing multiple interrupts) during a single move.

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

IN_FINE_POSITION

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

The settling criteria are:

1. The absolute value of the position error is less than or equal to the fine position tolerance.

2. The absolute value of the velocity is less than or equal to the velocity tolerance.

3. Both of the above criteria have been satisfied for the settling time. Whenever either criteria 1 or 2 is not satisfied, SETTLED is cleared and the settling timer is reset.

MOTION_DONE

MOTION_DONE will be true when all the settling criteria have been met, or the Axis goes to a STOPPED or ERROR state.

AT_VELOCITY

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

The velocity settling criteria are:

Criteria 1: The absolute value of the velocity error is less than or equal to the velocity tolerance.

Criteria 2: 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.

🔹 RapidCode Functions

Function	Description
SettleOnStopSet	Delays the MOTION_DONE event until after the stop time and when the Settling Tolerance is met.
SettleOnEStopSet	Similar to SettleOnStopSet, but applies when an EStop occurs.

📜 Sample Code

Configure Axis Settling Parameters

• C#

      const double POSITION_TOLERANCE_FINE = 200;   // Specify the fine position tolerance.
      const double POSITION_TOLERANCE_COARSE = 300; // Specify the coarse position tolerance.
      const double VELOCITY_TOLERANCE = 12000;      // Specify the velocity tolerance.
      const double SETTLING_TIME = 5;               // Specify the settling time.
   
      // SET
      axis.PositionToleranceFineSet(POSITION_TOLERANCE_FINE);     // Set fine position tolerance.
      axis.PositionToleranceCoarseSet(POSITION_TOLERANCE_COARSE); // Set coarse position tolerance.
      axis.VelocityToleranceSet(VELOCITY_TOLERANCE);              // Set velocity tolerance.
      axis.SettlingTimeSet(SETTLING_TIME);                        // Set settling time.
   
      // GET
      var posTolFine   = axis.PositionToleranceFineGet();
      var posTolCoarse = axis.PositionToleranceCoarseGet();
      var velTol       = axis.VelocityToleranceGet();
      var setTime      = axis.SettlingTimeGet();

• C++

      // Parameters
      const double POSITION_TOLERANCE_FINE = 200;   // Tolerance for when a move is considered complete.
      const double POSITION_TOLERANCE_COARSE = 300; // Tolerance for when a move is considered "near" complete.
      const double VELOCITY_TOLERANCE = 12000;      // Tolerance for when a velocity move is considered complete.
      const double SETTLING_TIME = 5;               // How long the axis must be within tolerance to be considered settled.
   
      // SET
      axis->PositionToleranceFineSet(POSITION_TOLERANCE_FINE);
      axis->PositionToleranceCoarseSet(POSITION_TOLERANCE_COARSE);
      axis->VelocityToleranceSet(VELOCITY_TOLERANCE);
      axis->SettlingTimeSet(SETTLING_TIME);
   
      // GET
      double posTolFine = axis->PositionToleranceFineGet();
      double posTolCoarse = axis->PositionToleranceCoarseGet();
      double velTol = axis->VelocityToleranceGet();
      double setTime = axis->SettlingTimeGet();

Examine Iterrupts

• C++

      const int TIMEOUT = (5000);  //ms
   
      RSIEventType interruptType;
   
      // Initialize Controller, enable interrupts
      MotionController *controller = MotionController::CreateFromSoftware();
      SampleAppsHelper::CheckErrors(controller);
   
      controller->InterruptEnableSet(true);
      try
      {
          SampleAppsHelper::StartTheNetwork(controller);            // [Helper Function] Initialize the network.
   
          while (controller->OS->KeyGet((int32_t)RSIWait::RSIWaitPOLL) < 0)
          {
              // add code here to generate interrupts (move axes, etc.)
   
              // wait for an interrupt
              interruptType = controller->InterruptWait(TIMEOUT);
   
              if (interruptType != RSIEventType::RSIEventTypeTIMEOUT)
              {
                  printf("IRQ %ld\n", interruptType);
                  printf("%s\n", controller->InterruptNameGet());
                  printf("InterruptSourceNumber = %ld\n", controller->InterruptSourceNumberGet());
                  printf("InterruptSampleTimer = %ld\n", controller->InterruptSampleTimeGet());
                  printf("\n");
              }
              else
              {
                  printf("Timeout waiting for interrupts...\n");
              }
          }
      }
      catch (RsiError const& err)
      {
          printf("\n%s\n", err.text);
      }
      controller->Delete();                                   // Delete the controller as the program exits to ensure memory is deallocated in the correct order.
      system("pause");                                        // Allow time to read Console.