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

This function applies an incremental adjustment to the active motion trajectory after enable_alter_motion has been successfully activated. It allows fine control of the robot’s end-effector position and orientation in real time by sending small delta pose values at each control cycle.

Each call to alter_motion() modifies the current trajectory based on the provided fTargetPos offsets. The input values correspond to X, Y, Z, Rx, Ry, Rz displacements and rotations, which are interpreted according to the reference frame configured in enable_alter_motion().

This function is available in M2.4 version or higher.

Definition
DRFLEx.h within class CDRFLEx, public section

bool alter_motion(float fTargetPos[NUM_TASK]) {
    return _alter_motion(_rbtCtrl, fTargetPos);
};

Parameter

Parameter Name

Data Type

Default Value

Description

fTargetPos

float[6]

Array representing incremental motion values for the current cycle.
Order: [X, Y, Z, Rx, Ry, Rz]
Units: mm for translation, deg for rotation.

Return

Value

Description

0

The robot is in a fault state, or the offset could not be sent.

1

The offset was sent, or alter motion is not enabled and nothing was sent.

Example

std::atomic<bool> g_bRunAlter(true);

// Thread sending small incremental poses until asked to stop
void ThreadFunc() {
    float delta[6] = {1.0f, 0.0f, 0.0f, 1.0f, 0.0f, 0.0f};  // ΔX=1mm, ΔRx=1° per cycle
    while (g_bRunAlter) {
        drfl.alter_motion(delta);
        std::this_thread::sleep_for(std::chrono::milliseconds(200));  // one 200 ms cycle
    }
}

// 1) Enable alter motion mode (20 x 10 ms = 200 ms cycle)
float limitDpos[2] = {50.0f, 90.0f};
float limitDposPer[2] = {5.0f, 50.0f};
drfl.enable_alter_motion(20, PATH_MODE_DPOS, COORDINATE_SYSTEM_BASE,
                         limitDpos, limitDposPer);

// 2) Start an asynchronous motion to alter (200 mm along X at 50 mm/s, about 4 s)
float target[6] = {200.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f};
float vel[2] = {50.0f, 30.0f};
float acc[2] = {100.0f, 60.0f};
drfl.amovel(target, vel, acc, 0.f, MOVE_MODE_RELATIVE);

// 3) Start the user thread; main makes no other drfl calls while it runs
std::thread th(ThreadFunc);

// 4) Let it run while the motion is active to apply incremental corrections
std::this_thread::sleep_for(std::chrono::seconds(3));

// 5) Stop the thread, then disable alter motion mode
g_bRunAlter = false;
th.join();
drfl.disable_alter_motion();

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.

  • Calls on one CDRFLEx object must be made one at a time: while alter_motion() is being sent periodically, make no other calls on the same object; see Rules for callback functions.

  • The update rate must match the cycle time set in enable_alter_motion.

  • Offsets are applied only while a motion is running. Offsets sent while no motion is running are ignored; start the motion (for example with amovel) before sending offsets.

  • Input values follow fixed XYZ notation, and must not exceed configured limits (fLimitDpos, fLimitDposPer).