overwrite_user_cart_coord

This function updates an existing user coordinate system (iReqId) with a new pose (fTargetPos) and reference coordinate (eTargetRef). If bTargetUpdate is set to true, the update also synchronizes with the Teach Pendant (TP), allowing global updates across both the controller and TP environment.

If bTargetUpdate is false, the coordinate system is updated in the controller, and the update stays in effect after the client program ends.

This function is supported in M2.5 version or higher.

Available in Manual mode only. In other modes the function returns 0 and prints “this command can only be used in manual mode. please change to manual mode as robot mode”. The mode check uses the value returned by get_robot_mode.

Definition
DRFLEx.h within class CDRFLEx, public section

int overwrite_user_cart_coord(
    bool bTargetUpdate,
    int iReqId,
    float fTargetPos[NUM_TASK],
    COORDINATE_SYSTEM eTargetRef = COORDINATE_SYSTEM_BASE
) {
    return _overwrite_user_cart_coord(_rbtCtrl, bTargetUpdate, iReqId, fTargetPos, eTargetRef);
};

Parameter

Parameter Name	Data Type	Default Value	Description
bTargetUpdate	bool		Determines whether the coordinate update is local or global 0: Local update (temporary; program-only) 1: Global update (synchronized with Teach Pendant)
iReqId	int		Target coordinate ID to be overwritten. Must reference an existing user coordinate system.
fTargetPos	float[6]		Target position and orientation values (X, Y, Z, Rx, Ry, Rz) for the updated coordinate.
eTargetRef	COORDINATE_SYSTEM	COORDINATE_SYSTEM_BASE	Reference coordinate system for defining the new user coordinate frame

Return

Value	Description
int	Returns the coordinate ID (101–200) on success. Returns 0 if the robot is not in Manual mode or the request cannot be sent.

Example

// Step 1. Create a user coordinate
float pose1[6] = {50.0f, 40.0f, 50.0f, 0.0f, 0.0f, 0.0f};
int user_id = drfl.set_user_cart_coord(0, pose1, COORDINATE_SYSTEM_BASE);

// Step 2. Prepare a new pose for overwriting
float pose2[6] = {100.0f, 150.0f, 200.0f, 45.0f, 180.0f, 0.0f};

// Step 3. Overwrite the coordinate globally
int result = drfl.overwrite_user_cart_coord(true, user_id, pose2);

printf("Overwrite Result: %d\n", result);

This example first creates a user-defined coordinate system, then overwrites its position and orientation with new values, synchronizing the change globally across the Teach Pendant and controller.