You're reading the documentation for an older, but still supported version (1.33.4).
For information on the latest version, please have a look at 1.33.5.

alter_motion (Manual Mode)

After enabling alter motion mode with enable_alter_motion, use alter_motion to apply incremental real-time corrections to the robot’s motion path while it’s actively moving. This allows a human operator to “nudge” or “trim” the TCP position interactively without re-executing a full command.

Typical usage

  • Perform orientation corrections (e.g., tool leveling, contact alignment).

  • Common in manual welding start-point correction or camera-guided teaching.

Note

  • Can only be called while alter motion mode is active.

  • Input vector represents [X, Y, Z, Rx, Ry, Rz] in fixed XYZ rotation order.

  • Offsets sent while no motion is running are ignored; start a task-space motion (for example amovel) first.

Caution

Call enable_alter_motion before alter_motion(); while alter motion is not enabled, alter_motion() sends nothing and still returns true, so a true return does not confirm that the offset was applied.

Example: Incremental TCP Correction During Manual Teaching

// Step 1: Enable alter mode (assume done earlier)
float fLimitDpos[2] = {5.0f, 3.0f};
float fLimitDposPer[2] = {0.0f, 0.0f};
drfl.enable_alter_motion(5, PATH_MODE_DPOS, COORDINATE_SYSTEM_BASE,
                         fLimitDpos, fLimitDposPer);

// Step 2: Start a slow task-space motion (100 mm along +X, relative)
float fRelTarget[NUM_TASK] = {100.0f, 0, 0, 0, 0, 0};
float fVel[2] = {30.0f, 20.0f};
float fAcc[2] = {60.0f, 40.0f};
drfl.amovel(fRelTarget, fVel, fAcc, 0.f, MOVE_MODE_RELATIVE);

// Step 3: Define a correction vector (move downwards)
float dPos[6] = {0, 0, -0.2f, 0, 0, 0};  // -0.2 mm per cycle

// Step 4: Apply small corrections in a loop while the motion runs
for (int i = 0; i < 25; ++i) {
    drfl.alter_motion(dPos);
    std::this_thread::sleep_for(std::chrono::milliseconds(50));  // 10 x iCycleTime ms
}
drfl.mwait();

printf("Manual fine adjustment complete.\n");

// Step 5: Disable alter mode after completion
drfl.disable_alter_motion();

Tips

  • Combine with camera or force feedback for semi-automatic fine-tuning.

  • Execute in a separate thread for smoother, continuous correction.

  • Use smaller increments (≤0.3 mm) when operating close to surfaces.