C, C++:

Drag Teaching Configuration dragTeach

During the drag teaching, the RealMan robotic arm records the drag trajectory and replays the trajectory according to the user's commands. This interface is intended for the drag teaching start control, the drag trajectory replay control, and the force-position hybrid control.

Start the drag teaching rm_start_drag_teach()

• Method prototype:

int rm_start_drag_teach(rm_robot_handle * handle,int trajectory_record)

Jump to rm_robot_handle for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.
trajectory_record	Input	Trajectory record during the drag teaching, 0: no record, 1: trajectory record.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.

• Usage demo

//Control the drag teaching mode of the robotic arm, and record the trajectory during the drag teaching
int trajectory_record = 1;
ret = rm_start_drag_teach(robot_handle,trajectory_record);

Stop the drag teaching rm_stop_drag_teach()

• Method prototype:

int rm_stop_drag_teach(rm_robot_handle * handle)

Jump to rm_robot_handle for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.

• Usage demo

//Exit the drag teaching mode
ret = rm_stop_drag_teach(robot_handle);

Start the multiple drag teaching rm_start_multi_drag_teach()

• Method prototype:

int rm_start_multi_drag_teach(rm_robot_handle * handle,int mode,int singular_wall)

Jump to rm_robot_handle for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.
mode	Input	Drag teaching mode 0: current loop mode, 1: position-only drag in the 6-DoF force mode, 2: orientation-only drag in the 6-DoF force mode, 3: position-orientation drag in the 6-DoF force mode.
singular_wall	Input	Available only for the drag teaching in the 6-DoF force mode to enable or disable the drag singular wall. 0: disable drag singular wall, 1: enable drag singular wall.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.

Note: Possible reasons for failure

• The current robotic arm is not the 6-DoF force version (drag teaching in the 6-DoF force mode).
• The robotic arm is currently in IO emergency stop state.
• The robotic arm is currently in simulation mode.
• The input parameters are incorrect.
• During the drag teaching in the 6-DoF force mode, the robotic arm is currently in the singular zone.

• Usage demo

//Use the position-only drag in the 6-DoF force mode, and enable the drag singular wall.
int mode = 1;
int singular_wall = 1;
ret = rm_start_multi_drag_teach(robot_handle,mode,singular_wall);

Start the multiple drag teaching (new parameters) rm_start_multi_drag_teach_new()

• Method prototype:

int rm_start_multi_drag_teach_new(rm_robot_handle * handle,rm_multi_drag_teach_t teach_state)

Jump to rm_robot_handle for details of the structureJump to rm_multi_drag_teach_t for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.
teach_state	Input	Multiple drag teaching parameter

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.

Note: Possible reasons for failure

• The current robotic arm is not the 6-DoF force version (drag teaching in the 6-DoF force mode).
• The robotic arm is currently in IO emergency stop state.
• The robotic arm is currently in simulation mode.
• The input parameters are incorrect.
• During the drag teaching in the 6-DoF force mode, the robotic arm is currently in the singular zone.

• Usage demo

rm_multi_drag_teach_t teach = 
{
    {0,0,0,0,0,0},      //All axes are non-draggable
    0,      //Use the work frame
    0       //Disable the drag singular wall
};

teach.free_axes[0] = 1;     //The X-axis of the reference frame is draggable
ret = rm_start_multi_drag_teach_new(robot_handle, teach);

Move to the trajectory origin rm_drag_trajectory_origin()

Before the trajectory replay, it is required to move the robotic arm to the trajectory origin. If the setting is correct, the robotic arm will move to the trajectory origin at a speed of 20.

• Method prototype:

int rm_drag_trajectory_origin(rm_robot_handle * handle,int block)

Jump to rm_robot_handle for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.
block	Input	Blocking settings: multi-thread mode: 0: non-blocking mode, immediately return after sending commands; 1: blocking mode, return after the robotic arm reaches the target position or the planning fails. Single-thread mode: 0: non-blocking mode; other values: blocking mode, and timeout period setting according to the movement time, in s.

Note: For single-thread blocking mode, set the timeout period to return the trajectory after running within the timeout period.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.
-4	int	The current in-position equipment verification fails, indicating that the current in-position equipment is not a joint.
-5	int	The single-thread mode does not receive a return value after the timeout, indicating that the timeout period may be improper.

• Usage demo

//By default, the robotic arm moves to the trajectory origin in the multi-thread, blocking mode
ret = rm_drag_trajectory_origin(robot_handle,1);

Start the trajectory replay rm_run_drag_trajectory()

• Method prototype:

int rm_run_drag_trajectory(rm_robot_handle * handle,int block)

Jump to rm_robot_handle for details of the structure

It is available only after the drag teaching is complete, and the robotic arm is located at the trajectory origin. The rm_drag_trajectory_origin interface can be called to move the robotic arm to the trajectory origin.

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.
block	Input	Blocking settings: multi-thread mode: 0: non-blocking mode, immediately return after sending commands; 1: blocking mode, return after the robotic arm reaches the target position or the planning fails. Single-thread mode: 0: non-blocking mode; other values: blocking mode, and timeout period setting according to the movement time, in s.

Note: For single-thread blocking mode, set the timeout period to return the trajectory after running within the timeout period.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.
-4	int	The current in-position equipment verification fails, indicating that the current in-position equipment is not a joint.
-5	int	The single-thread mode does not receive a return value after the timeout, indicating that the timeout period may be improper.

• Usage demo

//By default, the drag teaching trajectory is replayed in the multi-thread, blocking mode
int block = 1;
ret = rm_run_drag_trajectory(robot_handle,block);

Pause the trajectory replay rm_pause_drag_trajectory()

Control the pause of the robotic arm during the trajectory replay.

• Method prototype:

int rm_pause_drag_trajectory(rm_robot_handle * handle)

Jump to rm_robot_handle for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.

• Usage demo

//Pause the trajectory replay
ret = rm_pause_drag_trajectory(robot_handle);

Continue the trajectory replay rm_continue_drag_trajectory()

Control the continuation of the robotic arm after a pause during the trajectory replay.

• Method prototype:

int rm_continue_drag_trajectory(rm_robot_handle * handle)

Jump to rm_robot_handle for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.

• Usage demo

//Continue the trajectory replay
ret = rm_continue_drag_trajectory(robot_handle);

Stop the trajectory replay rm_stop_drag_trajectory()

Control the stop of the robotic arm during the trajectory replay.

• Method prototype:

int rm_stop_drag_trajectory(rm_robot_handle * handle)

Jump to rm_robot_handle for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.

• Usage demo

//Stop the trajectory replay
ret = rm_stop_drag_trajectory(robot_handle);

Save the drag teaching trajectory rm_save_trajectory()

• Method prototype:

int rm_save_trajectory(rm_robot_handle * handle,char * name,int * num)

Jump to rm_robot_handle for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.
name	Input	Path and name of the file to save the trajectory, including less than 300 characters, e.g., d:/rm_test.txt.
num	Output	Number of trajectory points.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.
-4	int	File open fails.
-5	int	File name interception fails.
-6	int	The obtained point parsing error occurs and the save fails.

• Usage demo

//Save the drag teaching point to the specified path
char *name = "/home/realman/work/example.txt";
int num = -1;
ret = rm_save_trajectory(robot_handle, name, &num);
printf("rm_save_trajectory result :%d, num:%d\n", ret, num);

Set the force-position hybrid control rm_set_force_position()

In Cartesian space trajectory planning, this function is available to ensure that the contact force of the end effector is constant when the force is not in the same direction as the robotic arm movement. Turn on the force-position hybrid control, perform the Cartesian space movement, and wait for 2s to issue the next movement command after receiving the feedback of the movement completion.

• Method prototype:

int rm_set_force_position(rm_robot_handle * handle,int sensor,int mode,int direction,float N)

Jump to rm_robot_handle for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.
sensor	Input	0: 1-DoF force, 1: 6-DoF force.
mode	Input	0: force control in the base frame, 1: force control in the tool frame.
direction	Input	Force control direction, 0: along the X-axis, 1: along the Y-axis, 2: along the Z-axis, 3: along the RX orientation, 4: along the RY orientation, 5: along the RZ orientation.
N	Input	Magnitude of the force, in N.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.

• Usage demo

//Set the force control at the Z-axis of the 6-DoF force base frame to 5 N 
int sensor = 1;
int mode = 0;
int direction = 2;
float N = 5;                          
ret = rm_set_force_position(robot_handle, sensor, mode, direction, N);

Set the force-position hybrid control (new parameters) rm_set_force_position_new()

In Cartesian space trajectory planning, this function is available to ensure that the contact force of the end effector is constant when the force is not in the same direction as the robotic arm movement. Turn on the force-position hybrid control, perform the Cartesian space movement, and wait for 2s to issue the next movement command after receiving the feedback of the movement completion.

• Method prototype:

int rm_set_force_position_new(rm_robot_handle * handle, rm_force_position_t param)

Jump to rm_robot_handle for details of the structureJump to rm_force_position_t for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.
param	Input	Force-position hybrid control parameters.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.

• Usage demo

rm_force_position_t param = {
    1,
    1,
    {3, 3, 4, 3, 3, 3},
    {0, 0, 1, 0, 0, 0},
    {0.1, 0.1, 0.1, 10, 10, 10},
};

rm_set_force_position_new(robot_handle, param);

Stop the force-position hybrid control rm_stop_force_position()

• Method prototype:

int rm_stop_force_position(rm_robot_handle * handle)

Jump to rm_robot_handle for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.

• Usage demo

//Stop the force-position hybrid control
ret = rm_stop_force_position(robot_handle);

Set the drag teaching sensitivity of the current loop rm_set_drag_teach_sensitivity()

• Method prototype:

int rm_set_drag_teach_sensitivity(rm_robot_handle * handle, int grade)

Jump to rm_robot_handle for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.
grade	Input	Grades 0−100, in %. The initial state is kept when it is 100.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.

• Usage demo

//Set the sensitivity to 50%
ret = rm_set_drag_teach_sensitivity(robot_handle, 50);

Get the drag teaching sensitivity of the current loop rm_get_drag_teach_sensitivity()

• Method prototype:

int rm_get_drag_teach_sensitivity(rm_robot_handle * handle, int* grade)

Jump to rm_robot_handle for details of the structure

• Parameter description:

Parameter	Type	Description
handle	Input	Robotic arm handle.
grade	Output	Grades 0−100, in %. The initial state is kept when it is 100.

• Return value:

Parameter	Type	Description
0	int	Success.
1	int	The controller returns false, indicating that the parameters are sent incorrectly or the robotic arm state is wrong.
-1	int	The data transmission fails, indicating that a problem occurs during the communication.
-2	int	The data reception fails, indicating that a problem occurs during the communication, or the controller has a return timeout.
-3	int	The return value parse fails, indicating that the received data format is incorrect or incomplete.

• Usage demo

int grade;
ret = rm_get_drag_teach_sensitivity(robot_handle, &grade);