Motion Hold

Table of Contents

• • 🔹 What is Motion Hold?
  • 🔹 Why use Motion Hold?
  • 📜 Sample Code
    • IO Triggered Motion
    • Position Triggered Motion
    • Software Triggered Motion

Execute motion on an Axis or MultiAxis triggered by real-time conditions such as I/O values, axis positions, or software triggers.

🔹 What is Motion Hold?

Motion Hold is a feature available to any motion on an Axis or MultiAxis. The feature allows the user to command (and therefore load) a motion that should not execute immediately. The motion will be triggered by some real-time condition monitored by the RMP firmware.

There are three main types of Motion Hold:

• I/O triggered motion - A motion holds its execution until an I/O value reaches the desired state.
• Position triggered motion - A motion holds its execution until an Axis position is exceeded.
• Software triggered motion - A motion holds its execution until a bit is set in the RMP’s firmware memory.

🔹 Why use Motion Hold?

Motion Hold is especially useful when a motion needs to have a very tight synchronization with some other process – when the synchronization must be accurate to less than one millisecond. A Windows app cannot offer this level of synchronization so it must be configured into the RMP for processing in the real-time firmware for sub-millisecond response to start motion.

Some examples of when Motion Hold might be used for various types:

Note

EXAMPLE 1 - IO Triggered Motion \ An Axis may need to perform its motion precisely when a digital input bit changes state.

EXAMPLE 2 - Position Triggered Motion \ An Axis may need to wait for some other Axis to move into a safe position before it can start its motion.

EXAMPLE 3 - Software Triggered Motion \ An Axis object (Or two axes) that has independent motion but must be started synchronously (can also be accomplished using MultiAxis). The Windows application will set a bit in RMP firmware memory which will trigger both Axis objects to start within the same RMP sample period.

📜 Sample Code

IO Triggered Motion

An Axis may need to perform its motion precisely when a digital input bit changes state. This sample code is done in AKD Drive with Digital IO Inputs switches. A digital input switch triggers to release the HOLD set on the specified Motion. This functionality is available for all Drives but some changes to the sample app may be required.

• C#

  /*  This sample demonstrates how to hold motion until a digital input signal is received.
      Uses a digital input to trigger motion release, useful for external sensor-based control.
  */
   
  using RSI.RapidCode; // RSI.RapidCode.dotNET;
   
  Console.WriteLine("📜 Motion Hold: via Digital Input");
   
  // set sample config params
  const int DIGITAL_INPUTS_PDO_INDEX = 3;  // pdo inputs index for digital inputs
   
  // get rmp objects
  MotionController controller = MotionController.Get();
   
  try
  {
      Helpers.CheckErrors(controller);
   
      // check is network is started
      if (controller.NetworkStateGet() != RSINetworkState.RSINetworkStateOPERATIONAL)
      {
          Console.WriteLine("Network not started. Please start it before running this app.");
          return;
      }
      
      // get axis
      Axis axis = controller.AxisGet(Constants.AXIS_0_INDEX);
      Helpers.CheckErrors(axis);
   
      // configure phantom axis
      Helpers.PhantomAxisReset(axis);
      axis.AmpEnableSet(true);
   
      // get host address using the pdo input index of digital inputs
      ulong inputAddress = controller.NetworkInputAddressGet(DIGITAL_INPUTS_PDO_INDEX);
   
      // configure motion hold for digital input
      axis.MotionHoldTypeSet(RSIMotionHoldType.RSIMotionHoldTypeCUSTOM);  // use custom type to hold based on bit pattern
      axis.MotionHoldUserAddressSet(inputAddress);                        // specify the digital inputs host address
      axis.MotionHoldUserMaskSet(0x20000);                                // specify the bit to watch (logic AND)
      axis.MotionHoldUserPatternSet(0x20000);                             // bit value that will release the motion hold
   
      // enable motion hold
      axis.MotionAttributeMaskOnSet(RSIMotionAttrMask.RSIMotionAttrMaskHOLD);
   
      // command motion - will be held until digital input condition is met
      axis.MoveRelative(10);
      Console.WriteLine("\tFirst motion commanded (held until digital input triggers)");
      axis.MotionDoneWait();
   
      // subsequent moves will also be held with same condition
      axis.MoveRelative(10);
      Console.WriteLine("\tSecond motion commanded (held until digital input triggers)");
      axis.MotionDoneWait();
   
      // disable motion hold
      axis.MotionAttributeMaskOffSet(RSIMotionAttrMask.RSIMotionAttrMaskHOLD);
   
      // this motion will execute immediately without hold
      axis.MoveRelative(10);
      Console.WriteLine("\tThird motion commanded (no hold, executes immediately)");
      axis.MotionDoneWait();
   
      Console.WriteLine($"\tFinal position: {axis.CommandPositionGet()}");
   
      // cleanup
      Helpers.AbortMotionObject(axis);
  }
  // handle errors as needed
  finally
  {
      controller.Delete();  // dispose
  }

Position Triggered Motion

An Axis may need to wait for some other Axis to move into a safe position before it can start its motion. This sample code is done in AKD Drive with one Actual Axis and one Phantom Axis. It can be applied to two Phantom Axis or two Actual Axis with the slight changes of code which is guided in comment.

• C#

  /*  This sample demonstrates how to hold motion based on another axis reaching a specified position.
      Uses one axis to control when another axis's motion is released, useful for synchronized operations.
  */
   
  using RSI.RapidCode; // RSI.RapidCode.dotNET;
   
  Console.WriteLine("📜 Motion Hold: via Position");
   
  // set sample config params
  const double TRIGGER_POSITION = 1;
  const int MOVING_AXIS_TARGET = 10;
  const int HOLDING_AXIS_TARGET = 2;
   
  // get rmp objects
  MotionController controller = MotionController.Get();
   
  try
  {
      Helpers.CheckErrors(controller);
   
      // get axes
      Axis holdingAxis = controller.AxisGet(Constants.AXIS_0_INDEX);
      Helpers.CheckErrors(holdingAxis);
   
      Axis movingAxis = controller.AxisGet(Constants.AXIS_1_INDEX);
      Helpers.CheckErrors(movingAxis);
   
      // configure phantom axes
      Helpers.PhantomAxisReset(holdingAxis);
      Helpers.PhantomAxisReset(movingAxis);
   
      holdingAxis.AmpEnableSet(true);
      movingAxis.AmpEnableSet(true);
   
      // configure motion hold - holdingAxis will be held until movingAxis reaches trigger position
      holdingAxis.MotionHoldTypeSet(RSIMotionHoldType.RSIMotionHoldTypeAXIS_COMMAND_POSITION);  // use AXIS_ACTUAL_POSITION for real axes
      holdingAxis.MotionHoldAxisNumberSet(movingAxis.NumberGet());                              // specify which axis position to monitor
      holdingAxis.MotionHoldAxisPositionSet(TRIGGER_POSITION);                                  // position that will release the hold
      holdingAxis.MotionHoldAxisLogicSet(RSIUserLimitLogic.RSIUserLimitLogicGE);                // release when position >= trigger position
   
      // enable motion hold and command motion
      holdingAxis.MotionAttributeMaskOnSet(RSIMotionAttrMask.RSIMotionAttrMaskHOLD);
      holdingAxis.MoveRelative(HOLDING_AXIS_TARGET);  // this motion will be held
   
      Console.WriteLine($"\tHolding axis commanded to move to {HOLDING_AXIS_TARGET}, but motion is held");
   
      // move the trigger axis to release the hold
      movingAxis.MoveRelative(MOVING_AXIS_TARGET);
      Console.WriteLine($"\tMoving axis to {MOVING_AXIS_TARGET} to release hold...");
   
      movingAxis.MotionDoneWait();
      holdingAxis.MotionDoneWait();
   
      Console.WriteLine($"\tHolding axis final position: {holdingAxis.CommandPositionGet()} (expected: {HOLDING_AXIS_TARGET})");
      Console.WriteLine($"\tMoving axis final position: {movingAxis.CommandPositionGet()} (expected: {MOVING_AXIS_TARGET})");
   
      // cleanup
      Helpers.AbortMotionObject(holdingAxis);
      Helpers.AbortMotionObject(movingAxis);
  }
  // handle errors as needed
  finally
  {
      controller.Delete();  // dispose
  }

Software Triggered Motion

An Axis object (Or two axes) that has independent motion but must be started synchronously (can also be accomplished using MultiAxis). The Windows application will set a bit in RMP firmware memory which will trigger both Axis objects to start within the same RMP sample period. This sample code is done in AKD Drive with one Actual axis. There are a lots of available/free firmware address. Some are suggested in comment. Available/free firmware addresses can be found using vm3 as long as there is no label on address, it can be used.

• C#

  /*  This sample demonstrates how to hold motion using a software address (memory location).
      Motion is held until a specific bit pattern is written to the address, useful for custom logic.
  */
   
  using RSI.RapidCode; // RSI.RapidCode.dotNET;
  using System.Threading;
   
  Console.WriteLine("📜 Motion Hold: via Address");
   
  // set sample config params
  const int MOVE_DISTANCE = 2;
   
  // get rmp objects
  MotionController controller = MotionController.Get();
   
  try
  {
      Helpers.CheckErrors(controller);
   
      // get axis
      Axis axis = controller.AxisGet(Constants.AXIS_0_INDEX);
      Helpers.CheckErrors(axis);
   
      // configure phantom axis
      Helpers.PhantomAxisReset(axis);
      axis.AmpEnableSet(true);
   
      // get available software address from user buffer
      ulong softwareAddress = controller.AddressGet(RSIControllerAddressType.RSIControllerAddressTypeUSER_BUFFER, 1);
   
      // configure motion hold on software address
      axis.MotionHoldTypeSet(RSIMotionHoldType.RSIMotionHoldTypeCUSTOM);  // use custom type to hold based on bit pattern
      axis.MotionHoldUserAddressSet(softwareAddress);                     // specify the host address
      axis.MotionHoldUserMaskSet(0x1);                                    // specify the bit to watch (logic AND)
      axis.MotionHoldUserPatternSet(0x1);                                 // bit value that will release the motion hold
   
      // ensure condition is false initially
      if (controller.MemoryGet(softwareAddress) != 0x0)
          controller.MemorySet(softwareAddress, 0x0);
   
      // enable motion hold
      axis.MotionAttributeMaskOnSet(RSIMotionAttrMask.RSIMotionAttrMaskHOLD);
   
      // command motion - will be held
      axis.MoveRelative(MOVE_DISTANCE);
      Console.WriteLine($"\tFirst motion commanded to move {MOVE_DISTANCE} (held)");
      Thread.Sleep(100);
   
      double positionWhileHeld = axis.CommandPositionGet();
      Console.WriteLine($"\tPosition while held: {positionWhileHeld} (should be 0)");
   
      // release motion hold by setting the address
      controller.MemorySet(softwareAddress, 0x1);
      Console.WriteLine("\tReleasing hold via address...");
      axis.MotionDoneWait();
      controller.MemorySet(softwareAddress, 0x0);  // reset to false
   
      Console.WriteLine($"\tPosition after release: {axis.CommandPositionGet()} (expected: {MOVE_DISTANCE})");
   
      // command motion again - will be held again
      axis.MoveRelative(MOVE_DISTANCE);
      Console.WriteLine($"\tSecond motion commanded to move {MOVE_DISTANCE} (held)");
      Thread.Sleep(100);
   
      // release motion hold again
      controller.MemorySet(softwareAddress, 0x1);
      Console.WriteLine("\tReleasing hold via address...");
      axis.MotionDoneWait();
      controller.MemorySet(softwareAddress, 0x0);  // reset to false
   
      // disable motion hold
      axis.MotionAttributeMaskOffSet(RSIMotionAttrMask.RSIMotionAttrMaskHOLD);
   
      // this motion will execute immediately
      axis.MoveRelative(MOVE_DISTANCE);
      Console.WriteLine($"\tThird motion commanded to move {MOVE_DISTANCE} (no hold)");
      axis.MotionDoneWait();
   
      // clean up
      Helpers.AbortMotionObject(axis);
   
      Console.WriteLine($"\tFinal position: {axis.CommandPositionGet()} (expected: {MOVE_DISTANCE * 3})");
  }
  // handle errors as needed
  finally
  {
      controller.Delete();  // dispose
  }

• C++

    /* CONSTANTS */
    // *NOTICE* The following constants must be configured before attempting to run with hardware.
   
    // Axis configuration parameters
    const int AXIS_COUNT = 1;
    const int AXIS_NUMBER = 0;
   
    const double USER_UNITS = 1048576;
   
    // Index for the address in the user buffer to use for the motion hold
    const int USER_BUFFER_INDEX = 0;
   
    // Motion parameters
    const double MOTION_DISTANCE = 0.25;
   
    const std::chrono::duration HOLD_TIME = std::chrono::milliseconds(2000);
   
    // To run with hardware, set the USE_HARDWARE flag to true AFTER you have configured the parameters above and taken proper safety precautions.
    USE_HARDWARE = false;
   
    // The rmpPath only needs to be set if the project directory is different than the rapid setup directory.
    // *NOTICE* When setting the rmpPath, be sure to uncomment the rmpPath arguement in MotionController::CreateFromSoftware() in the Run() function.
    const char rmpPath[] = "C:\\RSI\\X.X.X\\";            // Insert the path location of the RMP.rta (usually the RapidSetup folder)"
   
    /* SAMPLE APP BODY */
   
    // Initialize MotionController class.
    MotionController* controller = MotionController::CreateFromSoftware(/*rmpPath*/);     // NOTICE: Uncomment "rmpPath" if project directory is different than rapid setup directory.
    SampleAppsHelper::CheckErrors(controller);                                               // [Helper Function] Check that the axis has been initialize correctly. 
   
    // Setup the controller for the appropriate hardware configuration.
    if (USE_HARDWARE)
    {
      SampleAppsHelper::SetupControllerForHardware(controller);
    }
    else
    {
      SampleAppsHelper::SetupControllerForPhantoms(controller, AXIS_COUNT, { AXIS_NUMBER });
    }
   
    try
    {
      Axis* axis = controller->AxisGet(AXIS_NUMBER);      // Initialize Axis Class. (Use RapidSetup Tool to see what is your axis number)
      SampleAppsHelper::CheckErrors(axis);                 // [Helper Function] Check that the axis has been initialize correctly.
   
      // GET AXIS READY
      axis->UserUnitsSet(USER_UNITS);                     // Specify the counts per Unit.
      axis->PositionSet(0);                               // Make sure motor starts at position 0 every time.
      axis->ErrorLimitTriggerValueSet(1);                 // Set the position error trigger value
      axis->Abort();                                      // If there is any motion happening, abort it.
      axis->ClearFaults();                                // Clear faults.>
      axis->AmpEnableSet(true);                           // Enable the motor.
   
      // GET AN AVAILABLE MEMORY ADDRESS
      uint64_t userBufferAddress = controller->AddressGet(RSIControllerAddressType::RSIControllerAddressTypeUSER_BUFFER, USER_BUFFER_INDEX);
   
      // SET MOTION HOLD ON AVAILABLE SOFTWARE ADDRESS
      axis->MotionHoldTypeSet(RSIMotionHoldType::RSIMotionHoldTypeCUSTOM);        // Use TypeCUSTOM to hold execution based on a particular bit turning ON or OFF.
      axis->MotionHoldUserAddressSet(userBufferAddress);                          // Specify the available hostAddress . This address' value will be used to evaluate the motion hold condition.
      axis->MotionHoldUserMaskSet(0x1);                                           // Specify the bit you want to mask/watch from the MotionHoldUserAddressSet' address value (this evaluates using a logic AND)
      axis->MotionHoldUserPatternSet(0x1);                                        // Specify the bit value that will release the motion hold. (When this value is met, motion hold will be released)
   
      // Check the condition to be false at first
      if (controller->MemoryGet(userBufferAddress) != 0x0)        // Check Available host address value is mask to be false (in this case 0x0)
      {
        controller->MemorySet(userBufferAddress, 0x0);          // if not, mask it to false value/condition (in this case 0x0)
      }
   
      // COMMAND MOTION (NO HOLD YET)
      printf("\nCommanding Motion...\n");
      axis->MoveRelative(MOTION_DISTANCE);                            // Command simple relative motion. (This motion will have no HOLD)
   
      // SET MOTION HOLD
      printf("\nSetting Motion Hold...\n");
      axis->MotionAttributeMaskOnSet(RSIMotionAttrMask::RSIMotionAttrMaskHOLD);       // Set the HOLD motion attribute mask ON. (This initializes the HOLD on a particular motion)
   
      // COMMAND MOTION AGAIN (MOTION WILL BE HELD)
      printf("Commanding Motion...\n");
      axis->MoveRelative(MOTION_DISTANCE);                                                         // Command simple relative motion. (This motion will be HOLD by the condition above)
      std::this_thread::sleep_for(HOLD_TIME);                           // Sleep for 3 second before releasing motion hold.
   
      // RELEASE MOTION HOLD (MOTION WILL START)
      printf("Releasing Motion Hold...\n");
      controller->MemorySet(userBufferAddress, 0x1);      // Release Motion Hold by specifying the host address value to SET Condition (in this case 0x10000)
      axis->MotionDoneWait();                             // Wait for motion to be done
      controller->MemorySet(userBufferAddress, 0x0);      // Specify host address value back to false value/condition (in this case 0x0)
   
      // CLEAR MOTION HOLD
      printf("\nClearing Motion Hold...\n");
      axis->MotionAttributeMaskOffSet(RSIMotionAttrMask::RSIMotionAttrMaskHOLD);      // Set the HOLD motion attribute mask OFF. (This will clear any motion HOLDS that were set on this Axis)
   
      // COMMAND MOTION AGAIN (NO HOLD)
      printf("Commanding Motion...\n");
      axis->MoveRelative(-2 * MOTION_DISTANCE);           // This motion will have no HOLD since the previous line has set the motion attribute mask OFF.
      axis->MotionDoneWait();                             // Wait for Motion to be completed.
   
      // Abort and Clear Faults
      axis->Abort();
      axis->ClearFaults();
    }
    catch (RsiError const& err)
    {
      printf("%s\n", err.text);       // If there are any exceptions/issues this will be printed out.
      return -1;
    }
    controller->Delete();               // Delete the controller as the program exits to ensure memory is deallocated in the correct order.
    return 0;