[Fix] rename parameter ik to motion_type and update docs

Author: vimior

ReadMe.md

@@ -11,10 +11,10 @@
 - Protect the arm before unlocking the motor.
 
 ## Update Summary
-- > ### 1.11.4
+- > ### 1.11.5
   - Optimization pause time is too long (wait=true)
   - Add common motion api (Enabled after firmware version 1.11.100)
-  - The Cartesian motion-related interface adds IK parameters to find an IK value for the given target position for joint planning (Enabled after firmware version 1.11.100)
+  - The Cartesian motion-related interface adds the motion_type parameter to determine the planning method (Enabled after firmware version 1.11.100)
 
 - > ### 1.11.0
   - Support transparent transmission (240/241)

demo/csharp_studio/xarm/xarm_wrapper.cc

@@ -112,11 +112,11 @@ namespace XArmWrapper
   int __stdcall clean_error(void) {
     return arm->clean_error();
   }
-  int __stdcall set_position(fp32 pose[6], fp32 radius, fp32 speed, fp32 acc, fp32 mvtime, bool wait, fp32 timeout, bool relative, unsigned char ik) {
-    return arm->set_position(pose, radius, speed, acc, mvtime, wait, timeout, relative, ik);
+  int __stdcall set_position(fp32 pose[6], fp32 radius, fp32 speed, fp32 acc, fp32 mvtime, bool wait, fp32 timeout, bool relative, unsigned char motion_type) {
+    return arm->set_position(pose, radius, speed, acc, mvtime, wait, timeout, relative, motion_type);
   }
-  int __stdcall set_tool_position(fp32 pose[6], fp32 speed, fp32 acc, fp32 mvtime, bool wait, fp32 timeout, fp32 radius, unsigned char ik) {
-    return arm->set_tool_position(pose, speed, acc, mvtime, wait, timeout, radius, ik);
+  int __stdcall set_tool_position(fp32 pose[6], fp32 speed, fp32 acc, fp32 mvtime, bool wait, fp32 timeout, fp32 radius, unsigned char motion_type) {
+    return arm->set_tool_position(pose, speed, acc, mvtime, wait, timeout, radius, motion_type);
   }
   int __stdcall set_servo_angle(fp32 angles[7], fp32 speed, fp32 acc, fp32 mvtime, bool wait, fp32 timeout, fp32 radius, bool relative) {
     return arm->set_servo_angle(angles, speed, acc, mvtime, wait, timeout, radius, relative);
@@ -351,8 +351,8 @@ namespace XArmWrapper
   int __stdcall is_tcp_limit(fp32 pose[6], int *limit) {
     return arm->is_tcp_limit(pose, limit);
   }
-  int __stdcall set_position_aa(fp32 pose[6], fp32 speed, fp32 acc, fp32 mvtime, bool is_tool_coord, bool relative, bool wait, fp32 timeout, fp32 radius, unsigned char ik) {
-    return arm->set_position_aa(pose, speed, acc, mvtime, is_tool_coord, relative, wait, timeout, radius, ik);
+  int __stdcall set_position_aa(fp32 pose[6], fp32 speed, fp32 acc, fp32 mvtime, bool is_tool_coord, bool relative, bool wait, fp32 timeout, fp32 radius, unsigned char motion_type) {
+    return arm->set_position_aa(pose, speed, acc, mvtime, is_tool_coord, relative, wait, timeout, radius, motion_type);
   }
   int __stdcall set_servo_cartesian_aa(fp32 pose[6], fp32 speed, fp32 acc, bool is_tool_coord, bool relative) {
     return arm->set_servo_cartesian_aa(pose, speed, acc, is_tool_coord, relative);

demo/csharp_studio/xarm/xarm_wrapper.h

@@ -38,8 +38,8 @@ namespace XArmWrapper {
   extern "C" __declspec(dllexport) int __stdcall clean_warn(void);
   extern "C" __declspec(dllexport) int __stdcall clean_error(void);
 
-  extern "C" __declspec(dllexport) int __stdcall set_position(fp32 pose[6], fp32 radius = -1, fp32 speed = 0, fp32 acc = 0, fp32 mvtime = 0, bool wait = false, fp32 timeout = NO_TIMEOUT, bool relative = false, unsigned char ik = 0);
-  extern "C" __declspec(dllexport) int __stdcall set_tool_position(fp32 pose[6], fp32 speed=0, fp32 acc=0, fp32 mvtime=0, bool wait=false, fp32 timeout=0, fp32 radius = -1, unsigned char ik = 0);
+  extern "C" __declspec(dllexport) int __stdcall set_position(fp32 pose[6], fp32 radius = -1, fp32 speed = 0, fp32 acc = 0, fp32 mvtime = 0, bool wait = false, fp32 timeout = NO_TIMEOUT, bool relative = false, unsigned char motion_type = 0);
+  extern "C" __declspec(dllexport) int __stdcall set_tool_position(fp32 pose[6], fp32 speed=0, fp32 acc=0, fp32 mvtime=0, bool wait=false, fp32 timeout=0, fp32 radius = -1, unsigned char motion_type = 0);
   extern "C" __declspec(dllexport) int __stdcall set_servo_angle(fp32 angles[7], fp32 speed = 0, fp32 acc = 0, fp32 mvtime = 0, bool wait = false, fp32 timeout = NO_TIMEOUT, fp32 radius = -1, bool relative = false);
   extern "C" __declspec(dllexport) int __stdcall set_servo_angle_j(fp32 angles[7], fp32 speed=0, fp32 acc=0, fp32 mvtime=0);
   extern "C" __declspec(dllexport) int __stdcall set_servo_cartesian(fp32 pose[6], fp32 speed = 0, fp32 acc = 0, fp32 mvtime = 0, bool is_tool_coord = false);
@@ -123,7 +123,7 @@ namespace XArmWrapper {
   extern "C" __declspec(dllexport) int __stdcall set_cgpio_digital_with_xyz(int ionum, int value, float xyz[3], float tol_r);
   extern "C" __declspec(dllexport) int __stdcall set_cgpio_analog_with_xyz(int ionum, float value, float xyz[3], float tol_r);
 
-  extern "C" __declspec(dllexport) int __stdcall set_position_aa(fp32 pose[6], fp32 speed = 0, fp32 acc = 0, fp32 mvtime = 0, bool is_tool_coord = false, bool relative = false, bool wait = false, fp32 timeout = NO_TIMEOUT, fp32 radius = -1, unsigned char ik = 0);
+  extern "C" __declspec(dllexport) int __stdcall set_position_aa(fp32 pose[6], fp32 speed = 0, fp32 acc = 0, fp32 mvtime = 0, bool is_tool_coord = false, bool relative = false, bool wait = false, fp32 timeout = NO_TIMEOUT, fp32 radius = -1, unsigned char motion_type = 0);
   extern "C" __declspec(dllexport) int __stdcall set_servo_cartesian_aa(fp32 pose[6], fp32 speed = 0, fp32 acc = 0, bool is_tool_coord = false, bool relative = false);
 
   extern "C" __declspec(dllexport) int __stdcall robotiq_reset(unsigned char ret_data[6] = NULL);

demo/csharp_studio/xarm_csharp_demo/XArmAPI.cs

@@ -57,11 +57,11 @@ public static extern int create_instance(
         [DllImport("xarm.dll")]
         public static extern int set_position(float[] pose, float radius = -1,
             float speed = 0, float acc = 0, float mvtime = 0,
-            bool wait = false, float timeout = NO_TIMEOUT, bool relative = false, byte ik = 0);
+            bool wait = false, float timeout = NO_TIMEOUT, bool relative = false, byte motion_type = 0);
         [DllImport("xarm.dll")]
         public static extern int set_tool_position(float[] pose,
             float speed = 0, float acc = 0, float mvtime = 0,
-            bool wait = false, float timeout = NO_TIMEOUT, float radius = -1, byte ik = 0);
+            bool wait = false, float timeout = NO_TIMEOUT, float radius = -1, byte motion_type = 0);
         [DllImport("xarm.dll")]
         public static extern int set_servo_angle(float[] angles,
             float speed = 0, float acc = 0, float mvtime = 0,
@@ -224,7 +224,7 @@ public static extern int move_gohome(
         [DllImport("xarm.dll")]
         public static extern int is_tcp_limit(float[] pose, ref int limit);
         [DllImport("xarm.dll")]
-        public static extern int set_position_aa(float[] pose, float speed = 0, float acc = 0, float mvtime = 0, bool is_tool_coord = false, bool relative = false, bool wait = false, float timeout = NO_TIMEOUT, float radius = -1, byte ik = 0);
+        public static extern int set_position_aa(float[] pose, float speed = 0, float acc = 0, float mvtime = 0, bool is_tool_coord = false, bool relative = false, bool wait = false, float timeout = NO_TIMEOUT, float radius = -1, byte motion_type = 0);
         [DllImport("xarm.dll")]
         public static extern int set_servo_cartesian_aa(float[] pose, float speed = 0, float acc = 0, bool is_tool_coord = false, bool relative = false);
 

doc/xarm_cplus_api.md

@@ -514,9 +514,9 @@ __XArmAPI(const std::string &port="",
   > @return: see the [API Code Documentation](./xarm_api_code.md#api-code) for details.
 
 
-- __int set_position(fp32 pose[6], fp32 radius=-1, fp32 speed=0, fp32 acc=0, fp32 mvtime=0, bool wait=false, fp32 timeout=NO_TIMEOUT, bool relative = false, unsigned char ik=0)__
-- __int set_position(fp32 pose[6], fp32 radius, bool wait, fp32 timeout=NO_TIMEOUT, bool relative=false, unsigned char ik=0)__
-- __int set_position(fp32 pose[6], bool wait, fp32 timeout=NO_TIMEOUT, bool relative=false, unsigned char ik=0)__
+- __int set_position(fp32 pose[6], fp32 radius=-1, fp32 speed=0, fp32 acc=0, fp32 mvtime=0, bool wait=false, fp32 timeout=NO_TIMEOUT, bool relative = false, unsigned char motion_type=0)__
+- __int set_position(fp32 pose[6], fp32 radius, bool wait, fp32 timeout=NO_TIMEOUT, bool relative=false, unsigned char motion_type=0)__
+- __int set_position(fp32 pose[6], bool wait, fp32 timeout=NO_TIMEOUT, bool relative=false, unsigned char motion_type=0)__
   > Set the position  
   >     MoveLine: Linear motion  
   >     MoveArcLine: Linear arc motion with interpolation  
@@ -532,16 +532,23 @@ __XArmAPI(const std::string &port="",
   > @param timeout: maximum waiting time(unit: second), default is no timeout, only valid if wait is true  
   > @param relative: relative move or not  
   >     Note: only available if firmware_version >= 1.8.100  
-  > @param ik: whether to convert to joint planning through IK    
-  >     Note1: only available if firmware_version >= 1.11.100  
-  >     Note2: the specified radius is not supported, that is, the radius can only be -1   
-  >     Note3: if there is no suitable IK, a C40 error will be triggered   
+  > @param motion_type: motion planning type, default is 0    
+  >     motion_type == 0: default, linear planning   
+  >     motion_type == 1: prioritize linear planning, and turn to IK for joint planning when linear planning is not possible  
+  >     motion_type == 2: direct transfer to IK using joint planning  
+  >     Note:  
+  >       1. only available if firmware_version >= 1.11.100  
+  >       2. when motion_type is 1 or 2, linear motion cannot be guaranteed  
+  >       3. once IK is transferred to joint planning, the given Cartesian velocity and acceleration are converted into joint velocity and acceleration according to the percentage    
+  >         `speed = speed / max_tcp_speed * max_joint_speed`  
+  >         `acc = acc / max_tcp_acc * max_joint_acc`  
+  >       4. if there is no suitable IK, a C40 error will be triggered     
   >
   > @return: see the [API Code Documentation](./xarm_api_code.md#api-code) for details.   
 
 
-- __int set_tool_position(fp32 pose[6], fp32 speed=0, fp32 acc=0, fp32 mvtime=0, bool wait=false, fp32 timeout=NO_TIMEOUT, unsigned char ik=0)__
-- __int set_tool_position(fp32 pose[6], bool wait, fp32 timeout=NO_TIMEOUT, unsigned char ik=0)__
+- __int set_tool_position(fp32 pose[6], fp32 speed=0, fp32 acc=0, fp32 mvtime=0, bool wait=false, fp32 timeout=NO_TIMEOUT, unsigned char motion_type=0)__
+- __int set_tool_position(fp32 pose[6], bool wait, fp32 timeout=NO_TIMEOUT, unsigned char motion_type=0)__
   > Movement relative to the tool coordinate system  
   >     MoveToolLine: Linear motion  
   >     MoveToolArcLine: Linear arc motion with interpolation  
@@ -556,10 +563,17 @@ __XArmAPI(const std::string &port="",
   > @param timeout: maximum waiting time(unit: second), default is no timeout, only valid if wait is true  
   > @param radius: move radius, if radius less than 0, will MoveToolLine, else MoveToolArcLine  
   >     Note: only available if firmware_version >= 1.11.100  
-  > @param ik: whether to convert to joint planning through IK  
-  >     Note1: only available if firmware_version >= 1.11.100  
-  >     Note2: the specified radius is not supported, that is, the radius can only be -1   
-  >     Note3: if there is no suitable IK, a C40 error will be triggered  
+  > @param motion_type: motion planning type, default is 0    
+  >     motion_type == 0: default, linear planning   
+  >     motion_type == 1: prioritize linear planning, and turn to IK for joint planning when linear planning is not possible  
+  >     motion_type == 2: direct transfer to IK using joint planning  
+  >     Note:  
+  >       1. only available if firmware_version >= 1.11.100  
+  >       2. when motion_type is 1 or 2, linear motion cannot be guaranteed  
+  >       3. once IK is transferred to joint planning, the given Cartesian velocity and acceleration are converted into joint velocity and acceleration according to the percentage    
+  >         `speed = speed / max_tcp_speed * max_joint_speed`  
+  >         `acc = acc / max_tcp_acc * max_joint_acc`  
+  >       4. if there is no suitable IK, a C40 error will be triggered  
   >  
   > @return: see the [API Code Documentation](./xarm_api_code.md#api-code) for details.
 
@@ -1313,8 +1327,8 @@ __int move_gohome(bool wait=false, fp32 timeout=NO_TIMEOUT)__
   > @return: see the [API Code Documentation](./xarm_api_code.md#api-code) for details.
 
 
-- __int set_position_aa(fp32 pose[6], fp32 speed = 0, fp32 acc = 0, fp32 mvtime = 0, bool is_tool_coord = false, bool relative = false, bool wait = false, fp32 timeout = NO_TIMEOUT, unsigned char ik = 0)__
-- __int set_position_aa(fp32 pose[6], bool is_tool_coord, bool relative = false, bool wait = false, fp32 timeout = NO_TIMEOUT, unsigned char ik = 0)__
+- __int set_position_aa(fp32 pose[6], fp32 speed = 0, fp32 acc = 0, fp32 mvtime = 0, bool is_tool_coord = false, bool relative = false, bool wait = false, fp32 timeout = NO_TIMEOUT, unsigned char motion_type = 0)__
+- __int set_position_aa(fp32 pose[6], bool is_tool_coord, bool relative = false, bool wait = false, fp32 timeout = NO_TIMEOUT, unsigned char motion_type = 0)__
   > Set the pose represented by the axis angle pose  
   >     MoveLineAA: Linear motion  
   >     MoveArcLineAA: Linear arc motion with interpolation  
@@ -1331,10 +1345,17 @@ __int move_gohome(bool wait=false, fp32 timeout=NO_TIMEOUT)__
   > @param timeout: maximum waiting time(unit: second), default is no timeout, only valid if wait is true  
   > @param radius: move radius, if radius less than 0, will MoveLineAA, else MoveArcLineAA  
   >     Note: only available if firmware_version >= 1.11.100
-  > @param ik: whether to convert to joint planning through IK  
-  >     Note1: only available if firmware_version >= 1.11.100  
-  >     Note2: the specified radius is not supported, that is, the radius can only be -1   
-  >     Note3: if there is no suitable IK, a C40 error will be triggered  
+  > @param motion_type: motion planning type, default is 0    
+  >     motion_type == 0: default, linear planning   
+  >     motion_type == 1: prioritize linear planning, and turn to IK for joint planning when linear planning is not possible  
+  >     motion_type == 2: direct transfer to IK using joint planning  
+  >     Note:  
+  >       1. only available if firmware_version >= 1.11.100  
+  >       2. when motion_type is 1 or 2, linear motion cannot be guaranteed  
+  >       3. once IK is transferred to joint planning, the given Cartesian velocity and acceleration are converted into joint velocity and acceleration according to the percentage    
+  >         `speed = speed / max_tcp_speed * max_joint_speed`  
+  >         `acc = acc / max_tcp_acc * max_joint_acc`  
+  >       4. if there is no suitable IK, a C40 error will be triggered  
   > 
   > @return: see the [API Code Documentation](./xarm_api_code.md#api-code) for details.
 

include/xarm/core/instruction/uxbus_cmd.h

@@ -121,12 +121,12 @@ class UxbusCmd {
   int clean_war(void);
   int set_brake(int axis, int en);
   int set_mode(int value, int detection_param = -1);
-  int move_line(float mvpose[6], float mvvelo, float mvacc, float mvtime, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL, unsigned char ik = 0);
+  int move_line(float mvpose[6], float mvvelo, float mvacc, float mvtime, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL, unsigned char motion_type = 0);
   int move_lineb(float mvpose[6], float mvvelo, float mvacc, float mvtime,
-    float mvradii, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL);
+    float mvradii, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL, unsigned char motion_type = 0);
   int move_joint(float mvjoint[7], float mvvelo, float mvacc, float mvtime, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL);
   int move_jointb(float mvjoint[7], float mvvelo, float mvacc, float mvradii, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL);
-  int move_line_tool(float mvpose[6], float mvvelo, float mvacc, float mvtime, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL, unsigned char ik = 0);
+  int move_line_tool(float mvpose[6], float mvvelo, float mvacc, float mvtime, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL, unsigned char motion_type = 0);
   int move_gohome(float mvvelo, float mvacc, float mvtime, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL);
   int move_servoj(float mvjoint[7], float mvvelo, float mvacc, float mvtime);
   int move_servo_cartesian(float mvpose[6], float mvvelo, float mvacc, float mvtime);
@@ -211,9 +211,9 @@ class UxbusCmd {
 
   int get_pose_offset(float pose1[6], float pose2[6], float offset[6], int orient_type_in=0, int orient_type_out=0);
   int get_position_aa(float pose[6]);
-  int move_line_aa(float mvpose[6], float mvvelo, float mvacc, float mvtime, int mvcoord=0, int relative=0, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL, unsigned char ik = 0);
+  int move_line_aa(float mvpose[6], float mvvelo, float mvacc, float mvtime, int mvcoord=0, int relative=0, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL, unsigned char motion_type = 0);
   int move_servo_cart_aa(float mvpose[6], float mvvelo, float mvacc, int tool_coord=0, int relative=0);
-  int move_relative(float mvpose[7], float mvvelo, float mvacc, float mvtime, float radius, int is_joint_motion = false, bool is_axis_angle = false, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL, unsigned char ik = 0);
+  int move_relative(float mvpose[7], float mvvelo, float mvacc, float mvtime, float radius, int is_joint_motion = false, bool is_axis_angle = false, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL, unsigned char motion_type = 0);
 
   int tgpio_delay_set_digital(int ionum, int value, float delay_sec);
   int cgpio_delay_set_digital(int ionum, int value, float delay_sec);
@@ -264,7 +264,7 @@ class UxbusCmd {
 
   int iden_joint_friction(unsigned char sn[14], float *result);
 
-  int move_line_common(float mvpose[6], float mvvelo, float mvacc, float mvtime, float radius = -1.0, int coord = 0, bool is_axis_angle = false, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL, unsigned char ik = 0);
+  int move_line_common(float mvpose[6], float mvvelo, float mvacc, float mvtime, float radius = -1.0, int coord = 0, bool is_axis_angle = false, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL, unsigned char motion_type = 0);
   int move_circle_common(float pose1[6], float pose2[6], float mvvelo, float mvacc, float mvtime, float percent, int coord = 0, bool is_axis_angle = false, unsigned char only_check_type = 0, unsigned char *only_check_result = NULL);
 
   virtual void close(void);