enable_alter_motion

The enable_alter_motion() and alter_motion functions make it possible to alter the motion trajectory.

This function sets the configuration for the alter function and allows the input quantity of alter_motion() to be applied to the motion trajectory. Alter motion is generated in segments of iCycleTime x 10 ms. iCycleTime must be 1 to 254; see the Caution below. This function provides 2 modes (accumulation mode and increment mode). The input quantity of alter_motion() can be applied to the motion trajectory in two ways: as an accumulated value or as an increment value. In accumulation mode, the input quantity is the absolute altering amount (dX,dY,dZ,dRX,dRY,dRZ) from the current motion trajectory.

In increment mode, by contrast, the input quantity is the increment from the previous absolute altering amount. The reference coordinate can be changed through the input parameter ref. The limits on the accumulated amount and the increment amount can be set through the input parameters fLimitDpos (accumulated limit) and fLimitDposPer (increment input limit during 1 cycle). The actual alter amount is limited to these limits.

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

Definition
DRFLEx.h within class CDRFLEx, public section

bool enable_alter_motion(int iCycleTime,
                         PATH_MODE ePathMode,
                         COORDINATE_SYSTEM eTargetRef,
                         float fLimitDpos[2],
                         float fLimitDposPer[2]) {
    return _enable_alter_motion(_rbtCtrl, iCycleTime, ePathMode, eTargetRef, fLimitDpos, fLimitDposPer);
};

Parameter

Parameter Name	Data Type	Description
iCycleTime	int	Alter motion is generated in segments of iCycleTime x 10 ms. Valid range: 1 to 254. The controller refuses 0 and 255 with an alter-motion input error.
ePathMode	PATH_MODE	Path interpolation mode.
eTargetRef	COORDINATE_SYSTEM	Coordinate frame in which alter motion commands are applied. Typical values: `COORDINATE_SYSTEM_BASE`, `COORDINATE_SYSTEM_TOOL`.
fLimitDpos	float[2]	Maximum translation limits. [0]: Linear displacement limit (mm) [1]: Orientation change limit (deg) With both elements at `-10000` the accumulated amount is not limited.
fLimitDposPer	float[2]	Limit on the alter amount per cycle. [0]: Linear displacement limit per cycle (mm) [1]: Orientation change limit per cycle (deg) With both elements at `-10000` the amount per cycle is not limited.

Return

Value	Description
0	Error
1	Success

Caution

Values of iCycleTime above 255 are applied modulo 256; for example, 257 is applied as 1 (10 ms). Values whose remainder is 0 or 255 are refused with a warning. Pass only values from 1 to 254.

Example

// 1) Enable alter motion mode (20 x 10 ms = 200 ms cycle)
float limitDpos[2] = {5.0f, 3.0f};       // max linear/orient displacement
float limitDposPer[2] = {0.5f, 0.3f};    // per-cycle delta limits
drfl.enable_alter_motion(20, PATH_MODE_DPOS, COORDINATE_SYSTEM_TOOL,
                         limitDpos, limitDposPer);

// 2) Apply small delta adjustments while motion is running
for (int i = 0; i < 50; ++i) {
    float delta[6] = {0.1f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f};
    drfl.alter_motion(delta);
    std::this_thread::sleep_for(std::chrono::milliseconds(200));
}

// 3) Disable alter motion mode after fine-tuning
drfl.disable_alter_motion();

This example demonstrates how to activate alter motion, apply small position corrections at each control cycle, and safely disable it after the fine-tuning process. Note that alter_motion() can be used only after enable_alter_motion() is called successfully, and must be executed within the configured limits for displacement and orientation.