Python Language

JAKAAbout 58 min

Python Language

This document will introduce the data types and APIs defined in the JAKA SDK (Python), mainly intended for software developers using Python to create robot applications that communicate with virtual or real controllers. It will also be helpful for users who need to understand JAKA robot controller applications.

Document Notes

Runtime environment:
- Linux Python 3.5 and above 32-bit.
- Windows Python 3.7 and above 64-bit.
Units used for parameters: millimeters (mm), radians (rad).
In code examples without special instructions, it is assumed that the robot has already been powered on and enabled.
All code examples in this document assume there are no interferences within the robot's workspace.
Examples in this document assume the user's Python interpreter can locate the jkrc module.

Usage under Linux

Under Linux, libjakaAPI.so and jkrc.so need to be placed in the same folder, and the current folder path must be added to the environment variable: export LD_LIBRARY_PATH=/xx/xx/

Usage under Windows

Under Windows, jkrc and jakaAPI.dll need to be placed in the same folder. Common issues can be found in the FAQ.

Interface List

robot Arm Basics

Instantiating the Robot

Instantiate a robot object.

RC(ip)

Parameter description
- ip: The robot's IP address. Only objects instantiated with the correct IP address can control the robot.
Return Value
- Success: Returns a robot object
- Failure: The created object will be destroyed
Code Example

import jkrc
robot = jkrc.RC("192.168.2.64") # Returns a robot object

Connect to the robot controller

Note:

V3 controllers are recommended to use grpc to connect to the robot controller first
Controller versions above V3.2.10 require SDK account password verification

login()
login(use_grpc) #V3 controllers are recommended to use grpc first
login(use_grpc, username, password) #Controller versions above V3.2.10 require SDK account password verification

Parameter description
- use_grpc: Whether to use grpc to connect to the robot controller, if not filled in the default value is false, using the tcp interface
- username: SDK account username, default is empty
- password: SDK account password, default is empty
Return Value
- Success: (0,)
- Failure: others
Code Example

import jkrc
robot = jkrc.RC("192.168.2.64") # Returns a robot object
robot.login(1, "username", "password")       #Log in
robot.power_on()    #Power on
robot.logout()      #Log out

Robot logout

Disconnect from the controller

logout()

Return Value
- Success: (0,)
- Failure: others
Code Example

import jkrc
robot = jkrc.RC("192.168.2.64") # Returns a robot object
robot.login(1)  #Log in
robot.logout() #Log out

Turn on the robot power

Turn on the robot power, powering on the real robot will have about an 8-second delay.

power_on()

Return Value
- Success: (0,)
- Failure: others
Code Example

import jkrc
robot = jkrc.RC("192.168.2.64") # Returns a robot object
robot.login(1)       #Log in
robot.power_on()    #Power on
robot.logout()      #Log out

Turn off the robot power

power_off()

Return Value
- Success: (0,)
- Failure: others

Shut down the robot control cabinet

shut_down()

Return Value
- Success: (0,)
- Failure: others

Enable control on the robot

enable_robot()

Return Value
- Success: (0,)
- Failure: others
Code Example

import jkrc
robot = jkrc.RC("192.168.2.64")#Returns a robot object
robot.login(1)  #Log in
robot.enable_robot()#
robot.logout() #Log out

Disable control on the robot

disable_robot()

Return Value
- Success: (0,)
- Failure: others

Query SDK version

Get SDK version number

get_sdk_version()

Return Value
- Success: (0, version)
- Failure: others
Code Example

import jkrc
robot = jkrc.RC("192.168.2.64")
robot.login(1)
ret = robot.get_sdk_version()
print("SDK version is:", ret[1])
robot.logout()  #Log out

Get controller IP

get_controller_ip ()

Return Value
- Success: (0, ip_list), ip_list: list of controller IPs. When the controller name is a specific value, returns the IP address corresponding to that name. When the controller name is empty, returns all controller IP addresses within the subnet.
- Failure: others

Control the robot to enter or exit drag mode

drag_mode_enable(enable)

Return Value
- Success: (0,)
- Failure: others
Code Example

import jkrc    
import time    

robot = jkrc.RC("192.168.220.155")    
robot.login(1)    
robot.power_on()    
robot.enable_robot()
robot.drag_mode_enable(True)
time.sleep(1)
ret = robot.is_in_drag_mode()    
print(ret)    
robot.drag_mode_enable(False)
time.sleep(1)
ret = robot.is_in_drag_mode()    
print(ret)    
robot.logout()

Check whether the robot is in drag mode

is_in_drag_mode()

Return Value
- Success: (0,state) state equal to 1 means the robot is in drag mode, 0 means the opposite
- Failure: others

Set joint friction compensation coefficient

Only compatible with controller version 1.7.2 Set the friction compensation coefficient for each axis of the robot arm

Parameter Description
- joint Joint number 0~5
- gain Friction compensation coefficient, value range 0-200, 200 compensates 200% of the friction
Return Value
- Success: (0,)
- Failure: others

set_drag_friction_compensation_gain(joint, gain)

Get joint friction compensation coefficient

get_drag_friction_compensation_gain()

Return Value
- Success: (0,list), list is a six-dimensional array, representing six axes respectively
- Failure: others

Set whether SDK enables debug mode

This interface has been deprecated

Set whether SDK enables debug mode

set_debug_mode(mode)

Parameter description
- When mode is set to TRUE, debug mode starts, and debug information will be output to the standard output stream; when set to FALSE, it will not be enabled
Return Value
- Success: (0,)
- Failure: others

Set SDK log path

set_SDK_filepath(filepath)

Parameter description
- filepath: file path
Return Value
- Success: (0,)
- Failure: others

Robot arm motion

Set the robot arm motion planner type

Set the type of planner used for robot arm motion

set_motion_planner(type)

Parameter description
- type: motion planner type, -1 means disable planner (default is T planning), 0 means T planning (speed priority), 1 means S planning (compliance priority)
Return Value
- Success: (0,)
- Failure: others

Control robot movement in manual mode

jog(aj_num , move_mode, coord_type, jog_vel, pos_cmd)

Parameter description
- aj_num: axis_joint_based identification value, in joint space it represents axis number, axes 1 through 6 correspond to numbers 0 through 5 respectively; in Cartesian space, x, y, z, rx, ry, rz correspond to numbers 0 through 5 respectively
- move_mode: 0 means absolute movement, 1 means incremental movement, 2 means continuous movement
- coord_type: robot motion coordinate system, tool coordinate system, base coordinate system (current world/user coordinate system), or joint space
- jog_vel: Command speed, rotation axis or joint motion unit is rad/s, linear axis unit is mm/s, the positive or negative value of the speed determines the positive or negative direction of movement.
- pos_cmd: Command position, rotation axis or joint motion unit is rad, linear axis unit is mm; when move_mode is absolute motion, the parameter description can be ignored.
Return Value
- Success: (0,)
- Failure: others
  Tip:
  When calling the jog function before reaching the target position, this point needs to be continuously sent. (Controller requires within 500 ms)
Code Example JOG motion in joint space

# -*- coding: utf-8 -*-
import time
import jkrc
import math
# Coordinate system
COORD_BASE  = 0
COORD_JOINT = 1
COORD_TOOL  = 2

# Motion mode
ABS  = 0
INCR = 1

# Joints 1~6 correspond to 0~5 in sequence
robot = jkrc.RC("192.168.220.144")  # Returns robot object
ret = robot.logout()
ret = robot.login(1, "jaka_sdk", "password")
robot.power_on()                      # Power on
robot.enable_robot()

# ===== Parameters =====
joint_id = 1              
vel = 0.5                 # rad/s
value = math.pi / 6       # Incremental target
period = 0.1              # 100 ms
eps = 0.001               # Position threshold

# ===== Read current joint angle =====
ret = robot.get_joint_position()
if ret[0] != 0:
    raise RuntimeError("get_joint_position failed")

start = ret[1][joint_id]
target = start + value

print("start =", start, "target =", target)

# ===== Continuous jog sending =====
while True:
    # Current joint angle
    ret = robot.get_joint_position()
    cur = ret[1][joint_id]
    print("cur =", cur, "target =", target)
    # Send jog (continuously sending the same target)
    robot.jog(
        aj_num=joint_id,
        move_mode=INCR,
        coord_type=COORD_JOINT,
        jog_vel=vel,
        pos_cmd=value
    )
    # Position arrival check
    if abs(target - cur) < eps:
        break
    time.sleep(period)   # Must be < 500ms

# ===== Stop jog =====
robot.jog_stop(joint_id)
time.sleep(1)

robot.disable_robot()
robot.power_off()
robot.logout()

Stop robot movement in manual mode

Stop robot movement in manual mode, used to stop JOG

jog_stop(joint_num)

Parameter description
- joint_num: num represents the joint axis number to stop movement, axis numbers 0 to 5 correspond to joint 1 to joint 6 respectively. -1 means stopping movement of all axes.
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-  
import time        
import jkrc  

#Coordinate system  
COORD_BASE  = 0  
COORD_JOINT = 1  
COORD_TOOL  = 2  
#Motion mode  
ABS = 0  
INCR = 1  
#Joints 1~6 correspond to 0~5 in order  

robot = jkrc.RC("192.168.220.155") #Return robot object  
robot.login(1) #Login  
robot.power_on() #Power on  
robot.enable_robot()  
print("move1")  
robot.jog(0, INCR, COORD_JOINT, 0.1, 1)  
time.sleep(5) #jog is a non-blocking command, jog commands received during motion will be discarded  
print("move2")  
robot.jog(0, INCR, COORD_JOINT, 0.1, -1)  
time.sleep(0.5)  
robot.jog_stop(-1)  #Stop after 0.5 seconds of motion
robot.logout()

Robot joint movement

Robot joint movement to target position

joint_move(joint_pos, move_mode, is_block, speed)

Parameter description
- joint_pos: Target position for robot joint movement.
- move_mode: 0 represents absolute movement, 1 represents relative movement
- is_block: Sets whether the interface is blocking; TRUE means blocking, FALSE means non-blocking. Blocking means there will be a return value only after the robot finishes its movement, non-blocking means there will be an immediate return value after the interface call is completed.
- speed: Robot joint movement speed, unit: rad/s
- acc: Default joint acceleration 3.5 rad/s^2
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import time
import math
import jkrc

# Motion mode
ABS  = 0
INCR = 1

# Target joint angles (unit: radians)
joint_pos = [math.pi, math.pi/2, 0, math.pi/4, 0, 0]

# Return the robot object
robot = jkrc.RC("192.168.220.155")
robot.login(1)         # Log in
robot.power_on()      # Power on
robot.enable_robot()  # Enable robot

print("move1")
robot.joint_move(joint_pos, ABS, True, 0.1)
time.sleep(3)

robot.logout()

Robot extended joint movement

Robot extended joint movement. Add joint angular acceleration and joint movement endpoint tolerance.

joint_move_extend(joint_pos, move_mode, is_block, speed, acc, tol)

Parameter description
- joint_pos: Target angles for each joint in robot joint movement.
- move_mode: Specifies movement mode, 0 for absolute movement, 1 for incremental movement, 2 for continuous movement.
- is_block: Whether the interface is blocking; True for blocking, False for non-blocking.
- speed: Robot joint movement speed, unit: rad/s
- acc: Robot joint movement angular acceleration.
- tol: Robot movement endpoint tolerance.
Return Value
- Success: (0, )
- Failure: others
Code example:

# -*- coding: utf-8 -*-
import jkrc                           # Import module  
robot = jkrc.RC("192.168.220.155")  #Returns a robot object  
robot.login(1)  
robot.joint_move_extend(joint_pos=[1, 1, 1, 1, 1, 1], move_mode=0, is_block=True, speed=0.2, acc=1, tol=0.1)  
robot.joint_move_extend(joint_pos=[-1, 1, 1, 1, 1, 0], move_mode=0, is_block=True, speed=0.2, acc=1, tol=0.1)  
robot.logout() #Log out

Robot end linear motion

The robot end moves linearly to the target position.

linear_move(end_pos, move_mode, is_block, speed)

Parameter description
- end_pos: The target position for the robot end movement
- move_mode: 0 represents absolute movement, 1 represents relative movement
- is_block: Sets whether the interface is blocking. TRUE is blocking, FALSE is non-blocking. Blocking means there will be a return value only after the robot finishes its movement, non-blocking means there will be an immediate return value after the interface call is completed.
- speed: Robot linear motion speed, unit: mm/s, default is 500 mm/s
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import time
import jkrc
# Motion mode
ABS  = 0
INCR = 1
# TCP target position (unit: mm)
tcp_pos = [0, 0, -30, 0, 0, 0]
# Return the robot object
robot = jkrc.RC("192.168.220.155")
robot.login(1)         # Log in
robot.power_on()      # Power on
robot.enable_robot()  # Enable robot
print("move1")
# Blocking, move 30 mm along the negative Z-axis direction at 10 mm/s
ret = robot.linear_move(tcp_pos, INCR, True, 10)
print(ret[0])
time.sleep(3)
robot.logout()

Tip:

Due to differences in robot models, the pose in the above example may fail inverse kinematics, returning -4

Robot extended end linear motion

Robot extended end linear motion. Add spatial acceleration and spatial motion endpoint error.

linear_move_extend(end_pos, move_mode, is_block, speed, acc, tol)

Parameter description
- end_pos: The target position for the robot end movement.
- move_mode: Specifies the motion mode, 0 for absolute movement, 1 for incremental movement
- is_block: Whether the interface is blocking; True for blocking, False for non-blocking.
- speed: Robot Cartesian space motion speed, unit: mm/s
- acc: Robot Cartesian space acceleration, unit: mm/s^2.
- tol: Robot movement endpoint tolerance.
Return Value
- Success: (0,)
- Failure: others

Robot extended end linear motion

Robot extended end linear motion. Add orientation speed and orientation acceleration.

linear_move_extend_ori(end_pos, move_mode, is_block, speed, accel, tol, ori_vel, ori_acc)

Parameter description
- end_pos: The target position for the robot end movement.
- move_mode: Specifies the motion mode, 0 for absolute movement, 1 for incremental movement
- is_block: Whether the interface is blocking; True for blocking, False for non-blocking.
- speed: Robot Cartesian space motion speed, unit: mm/s
- acc: Robot Cartesian space acceleration, unit: mm/s^2.
- tol: Robot movement endpoint tolerance.
- ori_vel: Orientation speed, default value is 3.14 rad/s
- ori_acc: Orientation acceleration, default value is 12.56 rad/s²
Return Value
- Success: (0,)
- Failure: others

Robot end circular arc motion

circular_move (end_pos, mid_pos, move_mode, is_block, speed, acc, tol)

Parameter description
- end_pos: The target position for the robot end movement.
- mid_pos: Intermediate point of the robot end motion.
- move_mode: Specifies movement mode, 0 for absolute movement, 1 for incremental movement, 2 for continuous movement.
- is_block: Whether the interface is blocking; True for blocking, False for non-blocking.
- speed: Robot linear motion speed, unit: mm/s
- acc: Robot linear motion angular acceleration, unit: mm/s^2
- tol: Robot movement endpoint tolerance.
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import time
import math
import jkrc

# Motion mode
ABS  = 0
INCR = 1

# Circular arc motion target point (Cartesian pose, unit: mm / rad)
end_pos = [ -200, 400, 400, -math.pi/2, 0, 0 ]
mid_pos = [ -300, 400, 500, -math.pi/2, 0, 0 ]

# Joint starting position (unit: rad)
joint_pos = [ 105.791*math.pi/180,
              63.471*math.pi/180,
              -60.442*math.pi/180,
              176.971*math.pi/180,
              74.515*math.pi/180,
              0 ]

# Create robot object
robot = jkrc.RC("192.168.220.155")
robot.login(1)
robot.power_on()
robot.enable_robot()

# First perform joint space motion to the starting point
robot.joint_move(joint_pos, ABS, True, 1)  # Blocking motion, speed 1 rad/s
time.sleep(1)  # Ensure motion completion

# Then perform circular arc motion
robot.circular_move(end_pos=end_pos,
                    mid_pos=mid_pos,
                    move_mode=ABS,
                    is_block=True,
                    speed=20,   # mm/s
                    acc=1,      # acceleration
                    tol=0.1,    # endpoint error
                    )
time.sleep(1)

robot.logout()

Robot extended end circular motion

Robot end circular motion with added loop count setting

circular_move_extend (end_pos, mid_pos, move_mode, is_block, speed, acc, tol, opt_cond, cricle_cnt)

Parameter description
- end_pos: The target position for the robot end movement.
- mid_pos: Intermediate point of the robot end motion.
- move_mode: Specifies movement mode, 0 for absolute movement, 1 for incremental movement, 2 for continuous movement.
- is_block: Whether the interface is blocking; True for blocking, False for non-blocking.
- speed: Robot linear motion speed, unit: mm/s
- acc: Robot linear motion acceleration, unit: mm/s^2
- tol: Robot movement endpoint tolerance.
- opt_cond: Placeholder, pass none.
- circle_cnt: Number of loops in circular motion.
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import time
import math
import jkrc

# Motion mode
ABS  = 0
INCR = 1

# Circular arc motion target point (Cartesian pose, unit: mm / rad)
end_pos = [ -200, 400, 400, -math.pi/2, 0, 0 ]
mid_pos = [ -300, 400, 500, -math.pi/2, 0, 0 ]

# Joint starting position (unit: rad)
joint_pos = [ 105.791*math.pi/180,
              63.471*math.pi/180,
              -60.442*math.pi/180,
              176.971*math.pi/180,
              74.515*math.pi/180,
              0 ]

# Create robot object
robot = jkrc.RC("192.168.220.155")
robot.login(1)
robot.power_on()
robot.enable_robot()

# First perform joint space motion to the starting point
robot.joint_move(joint_pos, ABS, True, 1)  # Blocking motion, speed 1 rad/s
time.sleep(1)  # Ensure motion completion

# Then perform circular arc motion
robot.circular_move_extend(end_pos=end_pos,
                    mid_pos=mid_pos,
                    move_mode=ABS,
                    is_block=True,
                    speed=20,   # speed mm/s
                    acc=1,      # acceleration mm/s^2
                    tol=0.1,    # endpoint error
                    opt_cond=None,
                    circle_cnt=1) # rotate 1 loop
time.sleep(1)

robot.logout()

Robot extended end circular motion

Robot end circular motion with added circular motion scheme setting

circular_move_extend_mode(end_pos, mid_pos, move_mode, is_block, speed, accel, tol, option_cond, circle_cnt, circle_mode)

Parameter description
- end_pos: The target position for the robot end movement.
- mid_pos: Intermediate point of the robot end motion.
- move_mode: Specifies movement mode, 0 for absolute movement, 1 for incremental movement, 2 for continuous movement.
- is_block: Whether the interface is blocking; True for blocking, False for non-blocking.
- speed: Robot linear motion speed, unit: mm/s
- acc: Robot linear motion acceleration, unit: mm/s^2
- tol: Robot movement endpoint tolerance.
- opt_cond: Placeholder, pass none.
- circle_cnt: Number of loops in circular motion.
- circle_mode: Specify robot arm circular motion mode, default value is 0, parameter explanation as follows:
  - 0: Fixed to use the axis-angle from start pose to end pose with rotation angle less than 180° for pose change. (Current scheme)
  - 1: Fixed to use the axis-angle from start pose to end pose with rotation angle greater than 180° for pose change.
  - 2: Automatically choose whether the angle is less than 180° or greater than 180° based on the midpoint pose.
  - 3: The pose angle remains consistent with the arc axis at all times (current full circle motion).
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import time
import math
import jkrc

# Motion mode
ABS  = 0
INCR = 1

# Circular arc motion target point (Cartesian pose, unit: mm / rad)
end_pos = [ -200, 400, 400, -math.pi/2, 0, 0 ]
mid_pos = [ -300, 400, 500, -math.pi/2, 0, 0 ]

# Joint starting position (unit: rad)
joint_pos = [ 105.791*math.pi/180,
              63.471*math.pi/180,
              -60.442*math.pi/180,
              176.971*math.pi/180,
              74.515*math.pi/180,
              0 ]

# Create robot object
robot = jkrc.RC("192.168.220.155")
robot.login(1)
robot.power_on()
robot.enable_robot()

# First perform joint space motion to the starting point
robot.joint_move(joint_pos, ABS, True, 1)  # Blocking motion, speed 1 rad/s
time.sleep(1)  # Ensure motion completion

# Then perform circular arc motion
robot.circular_move_extend_mode(end_pos=end_pos,
                    mid_pos=mid_pos,
                    move_mode=ABS,
                    is_block=True,
                    speed=20,   # speed mm/s
                    acc=1,      # acceleration mm/s^2
                    tol=0.1,    # endpoint error
                    opt_cond=None,
                    circle_cnt=1, # rotate 1 loop
                    circle_mode=0)
time.sleep(1)

robot.logout()

Terminate current robot arm motion

You can terminate the robot’s motion under any circumstances.

motion_abort ()

Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import time
import jkrc

robot = jkrc.RC("192.168.220.155")  # return robot object
robot.login(1)
robot.power_on()
robot.enable_robot()

print("move1")
# Joint incremental motion (non-blocking)
robot.joint_move(
    joint_pos=[1, 0, 0, 0, 0, 0],
    move_mode=1,      # INCR
    is_block=False,   # Non-blocking
    speed=0.05
)

print("wait")
time.sleep(2)

print("stop")
robot.motion_abort()  # Force interrupt current motion

robot.logout()

Check if robot motion has stopped

is_in_pos()

Return Value
- Success: (0, state), state = 1 means the robot has stopped, 0 means the opposite
- Failure: others

Check robot motion status

get_motion_status()

Return Value
- Success: (0, data),
  - motion_line ID of the current motion command
  - motion_line_sdk Reserved parameter
  - inpos Whether the current movement is completed
  - err_add_line Failed to add motion command (robot arm is already at the target position)
  - queue Number of motion commands waiting to be processed in the queue
  - active_queue Number of commands currently in motion in the queue
  - queue_full Whether the command queue is full, 0: queue not full, 1: queue full
  - paused Whether the robot arm is paused, 0: robot arm not paused, 1: robot arm paused
  - isOnLimit Whether the robot arm is in soft limit mode, 0: robot arm normal, 1: robot arm reached soft limit
  - isInEstop Whether the robot arm is in emergency stop mode, 0: robot arm normal, 1: robot arm in emergency stop
  - isInCollision Whether the robot arm is in collision state, 0: robot arm normal, 1: robot arm triggered collision
- Failure: others

Set blocking motion timeout for the robot arm

This interface has been deprecated

Set blocking motion timeout for the robot arm.

set_block_wait_timeout(seconds)

Parameter description Seconds greater than 0.5
Return Value
- Success: (0,)
- Failure: others

robot arm operation information settings and queries

Obtain robot status monitoring data

Obtain robot status monitoring data, supports multi-thread safety

get_robot_status()

Return Value
- Success: (0, robotstatus), robotstatus length is 24, robotstatus return data order is as follows:
  - errcode Error code when the robot encounters a fault; 0 means running normally, other values indicate an exception
  - inpos Flag indicating whether the robot's movement has reached the target position; 0 means not in position, 1 means in position
  - powered_on Flag indicating whether the robot is powered on; 0 means not powered on, 1 means powered on
  - enabled Flag indicating whether the robot is enabled; 0 means not enabled, 1 means enabled
  - rapidrate Robot operation speed ratio
  - protective_stop Indicates whether the robot has detected a collision; 0 means no collision detected, 1 means collision detected
  - drag_status Indicates whether the robot is in drag mode; 0 means not in drag mode, 1 means in drag mode
  - on_soft_limit Indicates whether the robot is at the travel limit; 0 means limit protection not triggered, 1 means limit protection triggered
  - current_user_id ID of the user coordinate system currently used by the robot
  - current_tool_id ID of the tool coordinate system currently used by the robot
  - dout Digital output signal of the robot control cabinet
  - din Digital input signal of the robot control cabinet
  - aout Analog output signal of the robot control cabinet
  - ain Analog input signal of the robot control cabinet
  - tio_dout Digital output signal of the robot's end tool
  - tio_din Digital input signal of the robot's end tool
  - tio_ain Analog input signal of the robot's end tool
  - extio IO signal of the robot's external expansion module
  - cart_position Cartesian space position values of the robot's end
  - joint_position Position in the robot joint space
  - robot_monitor_data Robot status monitoring data (SCB major version number, SCB minor version number, controller temperature, robot average voltage, robot average current, monitoring data for the robot's 6 joints (instantaneous current, instantaneous voltage, instantaneous temperature))
  - torq_sensor_monitor_data Robot torque sensor status monitoring data (torque sensor IP address, torque sensor port number, tool load (load mass, center of mass x-axis coordinate, center of mass y-axis coordinate, center of mass z-axis coordinate), torque sensor status, torque sensor error code, actual contact force values of 6 torque sensors, raw reading values of 6 torque sensors, actual contact force values of 6 torque sensors (not affected by initialization options))
  - is_socket_connect Indicates whether the connection channel between the SDK and controller is normal; 0 means abnormal, 1 means normal
  - emergency_stop Indicates whether the robot is in emergency stop; 0 means emergency stop not pressed, 1 means pressed
  - tio_key Robot end tool button [0free]; [1point]; [2end ]light button
- Failure: others

Tip:

If the robot has no corresponding IO, it will return a string like “no extio.”

# -*- coding: utf-8 -*-
import jkrc  

robot = jkrc.RC("192.168.220.155")  
robot.login(1)  
ret = robot.get_robot_status()  
if ret[0] == 0:  
    print("the joint position is :",ret[1])   
    print(len(ret[1]))  
    for i in range(len(ret[1])):  
        print(ret[1][i])  
else:  
    print("some things happened, the errcode is: ",ret[0])  
robot.logout()

Get robot arm status (simple)

Get Robot Arm Status

get_robot_status_simple()

Return Value
- Success: (0,data)
  - errcode: Error code
  - errmsg: Error message
  - powered_on: Whether powered on
  - enabled: Whether enabled
- Failure: others

Get the current six joint angle values of the robot (servo feedback)

get_actual_joint_position()

Return Value
- Success: (0, joint_pos), joint_pos is a tuple containing 6 elements (j1, j2, j3, j4, j5, j6), j1, j2, j3, j4, j5, j6 represent the angle values of joints 1 to 6 respectively.
- Failure: others
Code Example

# -*- coding: utf-8 -*-    
import jkrc  

robot = jkrc.RC("192.168.220.155")#Returns a robot object  
ret = robot.login(1)#Login  
ret = robot.get_actual_joint_position()  
if ret[0] == 0:  
    print("the actual joint position is :",ret[1])  
else:  
    print("some things happened, the errcode is: ",ret[0])  
robot.logout()  #Log out

Get the current six joint angle values of the robot

get_joint_position()

Return Value
- Success: (0, joint_pos), joint_pos is a tuple containing 6 elements (j1, j2, j3, j4, j5, j6), j1, j2, j3, j4, j5, j6 represent the angle values of joints 1 to 6 respectively.
- Failure: others
Code Example

# -*- coding: utf-8 -*-    
import jkrc  

robot = jkrc.RC("192.168.220.155")#Returns a robot object  
ret = robot.login(1)#Login  
ret = robot.get_joint_position()  
if ret[0] == 0:  
    print("the joint position is :",ret[1])  
else:  
    print("some things happened, the errcode is: ",ret[0])  
robot.logout()  #Log out

Set the robot arm operation mode. In automatic mode, safety-related settings for the robot arm cannot be made; in manual mode, it will automatically enter retraction mode to ensure operational safety.

set_auto_manual_mode(mode|robot_id)

Parameter description
- mode mode parameter, 0: manual mode, 1: automatic mode
- robot_id Robot ID, default is 0 (optional parameter)
Return Value
- Success: (0,)
- Failure: others

Get the current robot arm operation mode

get_auto_manual_mode(|robot_id)

Parameter description
- robot_id Robot ID, default is 0 (optional parameter)
Return Value
- Success: (0, mode), mode mode parameter, 0: manual mode, 1: automatic mode
- Failure: others

Obtain the pose of the tool end under the current settings (servo feedback)

get_actual_tcp_position()

Return Value
- Success: (0, cartesian_pose), cartesian_pose is a tuple containing 6 elements (x, y, z, rx, ry, rz), x, y, z, rx, ry, rz represent the pose values of the robot tool end
- Failure: others
Code Example

# -*- coding: utf-8 -*-         
import jkrc  

robot = jkrc.RC("192.168.220.155")#Returns a robot object  
ret = robot.login(1)#Login  
ret = robot.get_actual_tcp_position()  
if ret[0] == 0:  
    print("the actual tcp position is :", ret[1])  
else:  
    print("some things happened, the errcode is: ",ret[0])  
robot.logout()  #Log out

Get the pose of the tool endpoint under the current settings

get_tcp_position()

Return Value
- Success: (0, cartesian_pose), cartesian_pose is a tuple containing 6 elements (x, y, z, rx, ry, rz), x, y, z, rx, ry, rz represent the pose values of the robot tool end
- Failure: others
Code Example

# -*- coding: utf-8 -*-         
import jkrc  

robot = jkrc.RC("192.168.220.155")#Returns a robot object  
ret = robot.login(1)#Login  
ret = robot.get_tcp_position()  
if ret[0] == 0:  
    print("the tcp position is :", ret[1])  
else:  
    print("some things happened, the errcode is: ",ret[0])  
robot.logout()  #Log out

Get robot DH parameters

Get user coordinate system information

get_dh_param()

Return Value
- Success: (0, {'alpha': (0.0, 1.5707963, 0.0, 0.0, 1.5707963, -1.5707963), 'a': (0.0, 0.0, 897.0, 744.5, 0.0, 0.0), 'd': (196.5, 0.0, 0.0, -188.35000610351562, 138.5, 120.5), 'joint_homeoff': (0.0, 0.0, 0.0, 0.0, 0.0, 0.0)})
DH parameter explanation

Parameter name	Type	Description	Unit
`alpha` (α)	Link twist angle	Angle between adjacent Z-axes (rotation angle around the X-axis)	Radian (rad)
`a`	Link length	Link length along the X-axis (distance between perpendicular lines of two adjacent Z-axes)	Millimeters (mm)
`D`	Link offset	Translation distance along the Z-axis (offset between adjacent X-axes)	Millimeters (mm)
`joint_homeoff`	Joint zero position offset	Zero position calibration offset of the joint (corrects the robot arm’s zero point)	Radian (rad)

Failure: Others

Set user coordinate system information

set_user_frame_data(id, user_frame, name)

Parameter description
- id: User coordinate system ID, selectable IDs are 1 to 15, 0 represents the robot’s base coordinate system
- user_frame: Description of user coordinate system parameters [x,y,z,rx,ry,rz]
- name: Alias of the user coordinate system
Return Value
- Success: (0,)
- Failure: others

Get user coordinate system information

get_user_frame_data(id)

Parameter description
- id User coordinate system ID query result
Return Value
- Success: (0, id, tcp), id: User coordinate system ID, selectable IDs are 1 to 15, 0 represents the robot’s base coordinate system tcp: Description of user coordinate system parameters [x,y,z,rx,ry,rz]
- Failure: others

Query the user coordinate system ID currently in use

get_user_frame_id()

Return Value
- Success: (0, id), id value range is 0 to 15, 0 represents the robot’s base coordinate system
- Failure: others

Set the user coordinate system ID currently in use

set_user_frame_id(id)

Parameter description
- id: User coordinate system ID
Return Value
- Success: (0,)
- Failure: others

Set the tool information of the specified number

set_tool_data(id, tcp, name)

Parameter description
- id: Tool ID to set, selectable IDs are 1 to 15, 0 represents the end flange, already used by the controller.
- tcp: Description of tool coordinate system parameters [x,y,z,rx,ry,rz]
- name: Alias of the user coordinate system
Return Value
- Success: (0,)
- Failure: others

Query the target tool coordinate system information

Query the tool information used by the robot

get_tool_data(id)

Return Value
- Success: (0, id, tcp), id value range is 0 to 15, 0 represents the end flange, already used by the controller. Tool coordinate system parameter description [x,y,z,rx,ry,rz]
- Failure: others

Query the tool ID currently used by the robot

get_tool_id()

Return Value
- Success: (0, id), id value range is 0 to 15, 0 represents the end flange, already used by the controller.
- Failure: others

Set the currently used tool ID

set_tool_id(id)

Parameter description
- id: Tool coordinate system ID
Return Value
- Success: (0,)
- Failure: others
Code example:

# -*- coding: utf-8 -*-  
import time        
import jkrc  
robot = jkrc.RC("192.168.220.155") #Returns a robot object  
robot.login(1)                        #Login  
ret = robot.get_tool_data(1)    #Query tool coordinate system data  
if ret[0] == 0:  
    print("the tool data is :",ret)  
else:  
    print("some things happened, the errcode is: ",ret[0])  
ret = robot.set_tool_data(1,[0,0,1,0,0,0],'test') #Set tool coordinate system data  
print("set tool data ret:",ret)
time.sleep(0.5)  
ret = robot.get_tool_data(1)    #Query tool coordinate system data  
if ret[0] == 0:  
    print("the tool data is :",ret)  
else:  
    print("some things happened, the errcode is: ",ret[0])  
ret = robot.get_tool_id()     #Query tool coordinate system id  
print("tool_id",ret)  
robot.set_tool_id(2)          #Set tool coordinate system data  
time.sleep(0.5)    
ret = robot.get_tool_id()     #Query tool coordinate system id  
print("tool_id",ret)  
robot.logout()

Set the value of a digital output variable (DO)

set_digital_output(iotype, index, value)

Parameter description
- iotype: DO type
- index: DO index (starting from 0)
- value: DO set value
Return Value
- Success: (0,)
- Failure: others
Code example: Set the value of DO3 to 1

# -*- coding: utf-8 -*-  
import jkrc
IO_CABINET  =0  #Control cabinet panel IO
IO_TOOL = 1     #Tool IO
IO_EXTEND = 2   #Extended IO
robot = jkrc.RC("192.168.220.155")
robot.login(1)  
ret = robot.set_analog_output(iotype = IO_CABINET,index = 0,value = 1.55)# Set control cabinet panel IO0 output value to 1.55
if ret[0] == 0:  
    print("set_analog_output success, ret = ",ret[1])  
else:  
    print("some things happened, the errcode is: ",ret[0])  
robot.logout()  #Log out

Set the value of the analog output variable (AO)

set_analog_output(iotype, index, value)

Parameter description
- iotype: AO type
- index: AO index (starting from 0)
- value: AO set value
Return Value
- Success: (0,)
- Failure: others
Code example: Set the value of AO1 to 1.55

import jkrc
IO_CABINET  =0  #Control cabinet panel IO
IO_TOOL = 1     #Tool IO
IO_EXTEND = 2   #Extended IO
robot = jkrc.RC("192.168.2.64")
robot.login(1)  
robot.set_analog_output(iotype = IO_CABINET,index = 0,value = 1.55)#    
robot.logout()  #Log out

Set the value of the digital output variable (DO) during motion

set_motion_digital_output(iotype, index, value, rel, distance)

Parameter description
- iotype: DO type
- index DO index (starting from 0)
- value DO value to set
- rel 0: relative to the motion start point, 1: relative to the motion end point
- distance Distance, refers to how far from the start or end point (based on the rel parameter) to trigger DO
Return Value
- Success: (0,)
- Failure: others

Set the value of the analog output variable (AO) during motion

set_motion_analog_output(iotype, index, value, rel, distance)

Parameter description
- iotype: AO type
- index AO index (starting from 0)
- value AO set value
- rel 0: relative to the motion start point, 1: relative to the motion end point
- distance Distance, refers to how far from the start or end point (based on the rel parameter) to trigger AO
Return Value
- Success: (0,)
- Failure: others

Query digital input (DI) status

get_digital_input(iotype, index)

Parameter description
- iotype: DI type
- index: DI index (starting from 0)
Return Value
- Success: (0, value), value: DI status query result
- Failure: others

Query digital output (DO) status

get_digital_output(iotype, index)

Parameter description
- iotype: DO type
- index: DO index (starting from 0)
Return Value
- Success: (0, value), value: DO status query result
- Failure: others

Query the value of the analog input variable (AI)

get_analog_input(iotype, index)

Parameter description
- iotype: AI type
- index: AI index (starting from 0)
Return Value
- Success: (0, value), value is the AI status query result, as a floating-point number
- Failure: others

Query the value of the analog output variable (AO)

get_analog_output(type, index)

Parameter description
- type: AO type
- index: AO index (starting from 0)
Return Value
- Success: (0, value), value is the AO status query result, as a floating-point number
- Failure: others
Code example: query the value of AO1 as

# -*- coding: utf-8 -*-  
import jkrc
IO_CABINET  =0  #Control cabinet panel IO
IO_TOOL = 1     #Tool IO
IO_EXTEND = 2   #Extended IO
robot = jkrc.RC("192.168.220.155")
robot.login(1)  
robot.set_analog_output(iotype = IO_CABINET,index = 0,value = 1.55)    
ret = robot.get_analog_output(iotype = IO_CABINET,index = 0)
print("AO value is:",ret[1])
robot.logout()  #Log out

Check whether the extended IO module is running

is_extio_running()

Return Value
- Success: (0, status), when status is 1 it indicates the extended IO module is running, 0 means it is not
- Failure: others

Robot payload settings

set_payload(mass = m, centroid = [x,y,z])

Parameter description
- mass: payload mass, unit: kg
- centroid: payload centroid[ coordinates x, y, z], unit: mm
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-  
import jkrc                               #Import module
robot = jkrc.RC("192.168.220.155")      #Return a robot object
robot.login(1)
robot.set_payload(mass= 1, centroid =[0.01,0.02,0.03])
robot.logout() 							#Logout

Get robot payload data

get_payload()

Return Value
- Success: (0, payload), payload is a tuple of length 2 (mass, (x,y,z)), the first element is the payload mass, the second element is the centroid coordinates.
- Failure: others
Code example:

# -*- coding: utf-8 -*-  
import jkrc  
robot = jkrc.RC("192.168.220.155") #Returns a robot object  
robot.login(1)                       #Login  
robot.set_payload(mass= 1,centroid =[0.01,0.02,0.03])   
ret = robot.get_payload()    
if ret[0] == 0:  
    print("the payload is :",ret[1])  
else:  
    print("some things happened, the errcode is: ",ret[0])  
robot.logout()

Set TIO V3 voltage parameters

set_tio_vout_param(vout_enable,vout_vol)

Parameter description
- vout_enable Voltage enable, 0: Off, 1: On
- vout_vol Voltage level 0: 24v 1: 12v
Return Value
- Success: (0)
- Failure: others

Get TIO V3 voltage parameters

get_tio_vout_param(vout_enable ,vout_vol)

Parameter description
- vout_enable Voltage enable, 0: Off, 1: On
- vout_vol Voltage level 0: 24v 1: 12v
Return Value
- Success: (0,(vout_enable ,vout_vol))
- Failure: others

Add or modify TIO semaphore

add_tio_rs_signal(sign_info)

Parameter description
- sign_info: dict semaphore attributes
  - sig_name semaphore name
  - chn_id channel ID
  - sig_type semaphore type
  - sig_addr semaphore address
  - value semaphore initial value
  - frequency semaphore frequency
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import jkrc  

robot = jkrc.RC("192.168.220.155")  # Return a robot object  
robot.login(1)                       # Login  

ret = robot.add_tio_rs_signal({
    'sig_name': 'signal_tmp',   # Semaphore name
    'chn_id': 0,                # RS485 channel ID
    'sig_type': 0,              # Semaphore type
    'sig_addr': 0x1,            # Semaphore address
    'value': 5,                 # Semaphore initial value
    'frequency': 5              # Semaphore frequency
})

if ret[0] == 0:  
    print("add_tio_rs_signal success, ret =", ret[0])  
else:  
    print("some things happened, errcode =", ret[0])   

robot.logout()

TIO delete semaphore

del_tio_rs_signal(sign_name)

Parameter description
- sign_info: str Signal identifier name
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import jkrc  

robot = jkrc.RC("192.168.220.155")  # Return a robot object  
robot.login(1)                       # Login  
ret = robot.del_tio_rs_signal('signal_tmp')  
if ret[0] == 0:  
    print("del_tio_rs_signal success, ret =", ret[0])  
else:  
    print("some things happened, errcode =", ret[0])   

robot.logout()

TIO RS485 send command

send_tio_rs_command(chn_id, cmd)

Parameter description
- chn_id: int Channel number
  - 0 - Channel 1
  - 1 - Channel 2
- cmd: str Data field (bytearray, variable-length byte array)
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import jkrc

robot = jkrc.RC("192.168.220.155")
robot.login(1)

cmd = bytearray(b"test_cmd")
ret = robot.send_tio_rs_command(0, cmd)

if ret[0] == 0:
    print("send_tio_rs_command success, ret =", ret[0])
else:
    print("some things happened, errcode =", ret[0])

robot.logout()

TIO refresh semaphore information

update_tio_rs_signal(sign_info)

Parameter description
- sign_info: dict Signal attributes, a dictionary type data
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import jkrc

robot = jkrc.RC("192.168.220.155")
robot.login(1)
ret = robot.update_tio_rs_signal({  
        'sig_name': 'signal_tmp',
        'frequency': 5
})
if ret[0] == 0:
    print("update_tio_rs_signal success, ret =", ret[0])
else:
    print("some things happened, errcode =", ret[0])
robot.logout()

TIO get semaphore information

get_rs485_signal_info()

Return Value
- Success: (0, sign_info_list) sign_info_list: list Array of semaphore information
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import jkrc

robot = jkrc.RC("192.168.220.155")
robot.login(1)
ret = robot.get_rs485_signal_info()
if ret[0] == 0:
    print("get_rs485_signal_info success, sign_info_list: {}".format(ret, ret[1]))
else:
    print("some things happened, errcode =", ret[0])
robot.logout()

Set TIO mode

set_tio_pin_mode(pin_type, pin_mode)

Parameter description
- pin_type: tio type 0 for DI Pins, 1 for DO Pins, 2 for AI Pins
- pin_mode: tio mode
  - DI Pins: 0:0x00 DI2 is NPN, DI1 is NPN; 1:0x01 DI2 is NPN, DI1 is PNP; 2:0x10 DI2 is PNP, DI1 is NPN; 3:0x11 DI2 is PNP, DI1 is PNP
  - DO Pins: For the lower 8 bits of data, the high 4 bits are DO2 configuration and the low 4 bits are DO1 configuration; 0x0 DO is NPN output; 0x1 DO is PNP output; 0x2 DO is push-pull output; 0xF RS485H interface
  - AI Pins: 0: Analog input function enabled, RS485L disabled; 1: RS485L interface enabled, analog input function disabled
Return Value
- Success: (0,)
- Failure: others

Get TIO mode

get_tio_pin_mode(pin_type)

Parameter description pin_type: tio type. 0 for DI Pins, 1 for DO Pins, 2 for AI Pins.
Return Value
- Success: (0, pin_mode)
- Failure: others

TIO RS485 communication parameter configuration

set_rs485_chn_comm(chn_id, slave_id, baudrate, databit, stopbit, parity)

Parameter description
- chn_id: RS485 channel ID. When querying, chn_id is used as an input parameter.
- slaveId: When the channel mode is set to Modbus RTU, you must additionally specify the Modbus slave node ID; other modes can ignore this.
- baudrate: Baud rate 4800, 9600, 14400, 19200, 38400, 57600, 115200, 230400
- databit: Data bits 7, 8
- stopbit: Stop bits 1, 2
- parity: Parity 78 → None; 79 → Odd; 69 → Even

TIO RS485 communication parameter description query

get_rs485_chn_comm(chn_id)

Return Value
- Success: (0, (chn_id, slave_id, baudrate, databit, stopbit, parity))
- Failure: others

TIO RS485 communication mode configuration

set_rs485_chn_mode(chn_id, chn_mode)

Parameter description
- chn_id: 0: RS485H, channel 1; 1: RS485L, channel 2
- chn_mode: 0: Modbus RTU; 1: Raw RS485; 2: torque sensor

TIO RS485 communication mode query

get_rs485_chn_mode(chn_id)

Parameter description
- chn_id: 0: RS485H, channel 1; 1: RS485L, channel 2
Return Value
- Success: (0, chn_mode)
  - chn_mode: 0: Modbus RTU; 1: Raw RS485; 2: torque sensor
- Failure: others

Set robot installation angle

set_installation_angle(anglex, angley)

Parameter description
- anglex: Installation angle in the x direction, range[ 0 to ]PI degrees
- anglez: Installation angle in the z direction, range[ 0 to 360 ]degrees
Return Value
- Success: (0)
- Failure: Other

Get robot installation angle

get_installation_angle()

Parameter description
- anglex: Installation angle in the x direction
- anglez: Installation angle in the z direction
Return Value
- Success: (0,[ qs, qx, qy, qz, rx, ry, rz]). Installation angle quaternion representation:[ qx, qy, qz, qs]; installation angle Euler representation:[ rx, ry, rz], where ry is fixed at 0.
- Failure: Other.
Code Example

# -*- coding: utf-8 -*-
import jkrc  
robot = jkrc.RC("192.168.220.156")  
res = robot.login(1)  
if res[0] != 0:  
    raise "RC login failed."  

anglex = 3.14  
angley = 0  
res = robot.set_installation_angle(anglex, angley)  
if res[0] != 0:  
    raise "Set installation angle failed."  

res = robot.get_installation_angle()  
if res[0] != 0:  
    raise "Get installation angle failed."  

print("Installation angle:")  
print("quat: [{x}, {y}, {z}, {s}]".format(s=res[1][0], x=res[1][1], y=res[1][2], z=res[1][3]))  
print("rpy: [{rx}, {ry}, {rz}]".format(rx=res[1][4], ry=res[1][5], rz=res[1][6]))  

robot.logout()

Get Robot Arm Status

get_robot_state()

Parameter description
- Success: (0, (estoped, power_on, servo_enabled))
  - estoped: Emergency stop. 0: Off, 1: On
  - power_on: Power up. 0: Off, 1: On
  - servo_enabled: Servo enable. 0: Off, 1: On
- Failure: others
Code example:

# -*- coding: utf-8 -*-
import jkrc  
robot = jkrc.RC("192.168.220.156")  
ret = robot.login(1)  
ret, (estoped, power_on, servo_enabled) = robot.get_robot_state()  
print('ret is {}, estop: {}, power_on {}, servo_enabled: {}'.format(ret, estoped, power_on, servo_enabled))  
robot.logout()

Set system variable

set_user_var(id, value, name)

Parameter description
- id: System variable ID
- value: Value of the system variable
- name: Alias of the system variable
Return Value
- Success: (0, )
- Failure: others

Get system variable

get_user_var()

Return Value
- Success: (0, data)
- Failure: others
Code example:

# -*- coding: utf-8 -*-
import jkrc  
robot = jkrc.RC("192.168.220.156")  
ret = robot.login(1)  
ret  = robot.set_user_var(5500, 1, "test")  
if ret[0] == 0:  
    print("set_user_var success")  
else:  
    print("some things happened, the errcode is: ",ret[0])
ret = robot.get_user_var()
print("get_user_var result is: ", ret)
robot.logout()

Set vibration suppression mode

set_vibsuppress_mode(mode| robot_id)

Parameter Description
- mode Vibration suppression mode, 0: Off, 1: Mode 1, 2: Mode 2
- robot_id: robot arm ID, default value is 0 (optional parameter)
Return Value
- Success: (0, )
- Failure: others

Enable vibration suppression settings

vibsuppress_on(frequency | damping, robot_id)

Parameter Description
- frequency Vibration frequency
- damping: Vibration damping, default value is 0.05 (optional parameter)
- robot_id: robot arm ID, default value is 0 (optional parameter)
Return Value
- Success: (0, )
- Failure: others

The initial default frequency for each model is shown in the table below:

Load/Model	Default frequency (Hz)
MiniCobot1	16
MiniCobot2	15
3kg (Zu3 and similar)	14
5kg (C5/A5/Dual-arm and similar)	12
7kg (Zu7 and similar)	12
12kg (Zu12 and similar)	8
16kg(Zu16)	7.5
18kg(Zu18)	7.5
20kg(Zu20)	7.5
30kg(Zu30)	7.4
Max40	5

Disable vibration suppression settings

vibsuppress_off(| robot_id)

Parameter Description
- robot_id: robot arm ID, default value is 0 (optional parameter)
Return Value
- Success: (0, )
- Failure: others
Code example:

# -*- coding: utf-8 -*-
import jkrc  
robot = jkrc.RC("192.168.220.156")  
ret = robot.login(1)  
ret  = robot.set_vibsuppress_mode(1)  
if ret[0] == 0:  
    print("set_vibsuppress_mode success")  
else:  
    print("some things happened, the errcode is: ",ret[0])

ret = robot.vibsuppress_on(14)
if ret[0] == 0:  
    print("vibsuppress_on success")  
else:  
    print("some things happened, the errcode is: ",ret[0])

ret = robot.vibsuppress_off()
if ret[0] == 0:  
    print("vibsuppress_off success")  
else:  
    print("some things happened, the errcode is: ",ret[0])
robot.logout()

Robot arm safety status settings

Check if the robot arm is in an emergency stop state

is_in_estop()

Return Value
- Success: (0, estop), estop equals 1 means the robot is in emergency stop, 0 means the opposite
- Failure: others

Check whether the robot exceeds the limit

is_on_limit()

Return Value
- Success: (0, state), state equals 1 means the robot exceeds the limit, 0 means the opposite
- Failure: others

Check whether the robot is in collision protection mode

is_in_collision()

Return Value
- Success: (0, state), state equals 1 means the robot is in collision protection mode, 0 means the opposite
- Failure: others

Recover from collision protection mode after collision

collision_recover()

Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import jkrc  
import time  

robot = jkrc.RC("192.168.220.156")  
robot.login(1)  
robot.power_on()  
robot.enable_robot()  
ret = robot.get_collision_level()#Get current collision level  
print(ret)  
robot.set_collision_level(1)#Set collision level  
ret = robot.get_collision_level()  
print(ret)  
num = 0  
while(1):  
    ret = robot.is_in_collision()  #Check whether it is in collision protection mode
    collision_status = ret[1]  
    if collision_status == 1:  
        time.sleep(5)  
        robot.collision_recover()   #If a collision occurs, recover from collision protection mode  
        print(" in collision "+ str(num))  
    else:  
        print("the robot is not in collision "+ str(num))  
    time.sleep(1)  
    num=num+1  

robot.logout()

Set robot collision level

set_collision_level(level)

Parameter description
- level: Collision level, value range [0–5], where 0 means collision is disabled, 1 means collision threshold 25N, 2 means collision threshold 50N, 3 means collision threshold 75N, 4 means collision threshold 100N, and 5 means collision threshold 125N
Return Value
- Success: (0,)
- Failure: others

Get robot collision level

get_collision_level()

Return Value
- Success: (0, level), level is the returned collision level, levels 0–5.
  - 0 means collision is disabled,
  - 1 means collision threshold 25N,
  - 2 means collision threshold 50N,
  - 3 means collision threshold 75N,
  - 4 means collision threshold 100N,
  - 5 means collision threshold 125N
- Failure: others

Set robot’s automatic motion termination type in case of network exception

Set network exception control handle, when the network encounters an abnormal situation, control the robot’s motion state.

set_network_exception_handle(millisecond, mnt)

Parameter description
- millisecond: Time parameter, unit: ms.
- mnt: The type of action the robot should take when a network abnormality occurs; 0 means the robot maintains its original movement, 1 means pause movement, 2 means terminate movement.
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-  
import time        
import jkrc  

#Motion mode  
ABS = 0  
INCR = 1  
robot = jkrc.RC("192.168.220.156")#Return the robot object  
robot.login(1) #Login  
robot.power_on() #Power on  
robot.enable_robot()  
robot.set_network_exception_handle(100,2)#Set 100ms, pause movement.    
print("move1")  
num=0  
while(1):  
    robot.joint_move([1,1,1,1,1,1],ABS,False,0.5)  
    robot.joint_move([-1,1,1,1,1,1],ABS,False,0.5)  
    num = num +1  
    print(num)  
    time.sleep(6)  
robot.logout()

Get the error code during the robot operation process

Retrieve the last error code during robot operation; when clear_error is called, the last error code will be reset to zero.

get_last_error()

Return Value
- Success: (0, error)
- Failure: others
Code Example

# -*- coding: utf-8 -*-  
import jkrc  
robot = jkrc.RC("192.168.220.156") # Returns a robot object  
robot.login(1)   # Log in  
robot.program_load("not_exist") # Intentionally load a non-existent program to trigger an error  
ret = robot.get_last_error () # Without setting the error code file path, only the error code can be obtained, not the detailed error information  
print(ret[1])   
robot.logout()  #Log out

Error status clear

clear_error()

Return Value
- Success: (0,)
- Failure: others

Set the file path for the error code

Deprecated interface

Set the error code file path; when using the get_last_error interface, if you want to obtain detailed error information, you need to use this interface to set the error code file path. If you only need to get the error code, there’s no need to call this interface.

Note

Note: The path cannot contain Chinese characters; otherwise, it cannot be used.

set_errorcode_file_path (errcode_file_path)

Parameter description
- errcode_file_path: The storage path of the error code file
Return Value
- Success: (0,)
- Failure: others

robot arm EDG (External Data Guider) function

robot arm EDG enable

Enable the robot arm EDG function; only after enabling can EDG-related interfaces be used

edg_init(en, edg_stat_ip)

Parameter description
- en: Enable switch; true enables the EDG function, false exits the function
- edg_stat_ip: SDK client IP address
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-  
import jkrc  
robot = jkrc.RC("192.168.220.156") # Returns a robot object  
robot.login(1)   # Log in  

ret = robot.edg_init(
    en=True,                      # Whether to enable the EDG function
    edg_stat_ip="192.168.220.144"  # IP address of the status feedback module
)
print("Return value of edg_init:", ret)
robot.logout()  #Log out

Attention:

When enabled, servo_j and servo_p cannot be called; edg_init(false) must be called to disable the EDG function before calling servo_j and servo_p

Robot arm EDG enable extension

Mechanical arm EDG enable extension, supports configuring the local port number and calling servo_j and servo_p.

edg_init_extend(en, edg_stat_ip, edg_port, edg_mode)

Parameter description
- en enable switch, true turns on this function, false exits this function
- edg_stat_ip SDK client IP address
- edg_port local port number
- edg_mode EDG mode, default value is 0, 0 means all EDG-related interfaces can be called, 1 means all interfaces except edg_servo_j and edg_servo_p can be called (servo_j and servo_p can be called in this case)
Return Value
- Success: (0,)
- Failure: others
Code example:

# -*- coding: utf-8 -*-  
import jkrc  
robot = jkrc.RC("192.168.220.156") # Returns a robot object  
robot.login(1)   # Log in  

ret = robot.edg_init_extend(
    en=True,
    edg_stat_ip="192.168.220.144",
    edg_port=30003,         # Port number
    edg_mode=1              # Mode number (according to protocol definition)
)
print("edg_init_extend return value:", ret)
robot.logout()  #Log out

robot arm high-speed acquisition of EDG feedback data

edg_get_stat(robot_index)

Parameter description
- robot_index uses the default value, no parameter passing required
Return Value
- Success: (0,status), status length is 6, status return data order is as follows:
  - joint_value current joint position
  - joint_vel current joint velocity
  - joint_torque current joint torque
  - cart_pose current Cartesian position
  - torque_sensor torque sensor data
  - io_state in order: din, dout, ain, aout, tool_din, tool_dout, tool_ain
- Failure: others
Code Example

# -*- coding: utf-8 -*-  
import jkrc  
robot = jkrc.RC("192.168.220.156") # Returns a robot object  
robot.login(1)   # Log in  

ret = robot.edg_init_extend(
    en=True,
    edg_stat_ip="192.168.220.144",
    edg_port=30003,         # Port number
    edg_mode=1              # Mode number (according to protocol definition)
)
print("edg_init_extend return value:", ret)
ret = robot.edg_get_stat(robot_index=0)
print("edg_get_stat return value:", ret)
robot.logout()  #Log out

Mechanical arm obtains EDG feedback send timestamp

robot arm acquisition of EDG feedback data issuance timestamp

edg_stat_details()

Return Value
- Success: (0, details), length of details is 3, data order: seconds, nanoseconds, timestamp count
- Failure: others
Code Example

# -*- coding: utf-8 -*-  
import jkrc  
robot = jkrc.RC("192.168.220.156") # Returns a robot object  
robot.login(1)   # Log in  

ret = robot.edg_init_extend(
    en=True,
    edg_stat_ip="192.168.220.144",
    edg_port=30003,         # Port number
    edg_mode=1              # Mode number (according to protocol definition)
)
print("edg_init_extend return value:", ret)
ret = robot.edg_get_stat(robot_index=0)
print("edg_get_stat return value:", ret)
# Get EDG status details
ret = robot.edg_stat_details()
print("edg_stat_details return value:", ret)
robot.logout()  #Log out

robot arm EDG joint space servo mode motion

edg_servo_j(joint_pos, move_mode, step_num, robot_index)

Parameter description
- joint_pos Target joint position for robot arm joint motion
- move_mode specifies motion mode: 0 represents absolute motion, 1 represents incremental motion
- step_num subdivides the cycle, edg_servo_j motion cycle is step_num*8ms, where step_num >= 1
- robot_index uses default value 0
Return Value
- Success: (0,)
- Failure: others
Code Example

# Servo control - Joint space
ret_val = rc.edg_servo_j(
    joint_pos=(0.0, -0.5, 1.0, 0.0, -0.5, 0.5),  # Six joint angles
    move_mode=1,      # Control mode (e.g., servo)
    step_num=50,      # Interpolation steps
    robot_index=0     # Robot ID
)
print("edg_servo_j return value:", ret_val)

robot arm EDG Cartesian space servo mode motion

Robot arm EDG Cartesian space position control mode

edg_servo_p(end_pos, move_mode, step_num, robot_index)

Parameter description
- cartesian_pose target position for robot arm Cartesian space motion
- move_mode specifies motion mode: 0 represents absolute motion, 1 represents incremental motion
- step_num multiplied subdivision cycle, edg_servo_p motion cycle is step_num*8ms, where step_num>=1
- robot_index uses default value 0
Return Value
- Success: (0,)
- Failure: others
Code Example

# Servo control - Cartesian space
ret_val = rc.edg_servo_p(
    end_pos=(500.0, 200.0, 300.0, 0.0, 3.14, 0.0),  # X, Y, Z, RX, RY, RZ
    move_mode=1,        # Motion mode
    step_num=50,        # Interpolation steps
    robot_index=0       # Robot ID
)
print("edg_servo_p return value:", ret_val)

Use App script program

Load the specified job program

program_load(file_name)

Parameter description
- file_name: Program name, the passed name is a string, for example “file_name”
Return Value
- Success: (0,)
- Failure: others

Get the name of the loaded job program

get_loaded_program()

Return Value
- Success: (0, file_name)
- Failure: others
Code Example

# -*- coding: utf-8 -*-  
import jkrc
robot = jkrc.RC("192.168.220.1564") # returns a robot object
robot.login(1)  #Log in
ret = robot.program_load("program_test") # loads the script written via the App; program_test needs to be written by yourself
ret = robot.get_loaded_program()  
print("the loaded program is:", ret[1])
robot.logout() #Log out

Get the current line number of the robot job program execution

get_current_line()

Return Value
- Success: (0, curr_line), curr_line: result of current line number query.
- Failure: others

Run the currently loaded job program

program_run()

Return Value
- Success: (0,)
- Failure: others

Pause the currently running job program

program_pause()

Return Value
- Success: (0,)
- Failure: others

Continue running the currently paused job program

program_resume()

Return Value
- Success: (0,)
- Failure: others

Terminate the currently executing job program

program_abort()

Return Value
- Success: (0,)
- Failure: others

Get the execution status of the robot job program

get_program_state()

Return Value
- Success: (0, state), state has three possible values: 0, 1, 2
  - 0 means the program has stopped running
  - 1 means the program is running
  - 2 means the program is paused
- Failure: others
Code Example

# -*- coding: utf-8 -*-  
import time
import jkrc
import threading

stop_flag = threading.Event()

def print_state(name, robot):
    while not stop_flag.is_set():
        ret = robot.get_program_state()
        print("the robot program state is:", ret[1])
        time.sleep(1)

robot = jkrc.RC("192.168.220.156")
robot.login(1)
ret = robot.program_load("program_test")
ret = robot.get_loaded_program()    
print("the loaded program is:", ret[1])
robot.program_run()

t = threading.Thread(target=print_state, args=("p1_state", robot))
t.start()  # Normal subthread, daemon not set

time.sleep(2)
robot.program_pause()
time.sleep(2)
robot.program_resume()
time.sleep(2)
robot.program_abort()
time.sleep(3)

# Notify the subthread to exit and wait
stop_flag.set()
t.join()

robot.logout()

Get information of robot arm job program

Get robot arm task program information

get_program_info()

Return Value
- Success: (0, logic_line, motion_line, file, program_state)
  - logic_line Program script execution line number
  - motion_line Motion CMD id being executed
  - file Current program file
  - program_state Program execution status
- Failure: others
Code Example

# -*- coding: utf-8 -*-  
import time
import jkrc
import threading

stop_flag = threading.Event()

def print_state(name, robot):
    while not stop_flag.is_set():
        ret = robot.get_program_info()
        print("the robot program info is:", ret)
        time.sleep(1)

robot = jkrc.RC("192.168.220.157")
robot.login(1)
ret = robot.program_load("program_test")
ret = robot.get_loaded_program()    
print("the loaded program is:", ret[1])
robot.program_run()

t = threading.Thread(target=print_state, args=("p1_state", robot))
t.start()  # Normal subthread, daemon not set

time.sleep(2)
robot.program_pause()
time.sleep(2)
robot.program_resume()
time.sleep(2)
robot.program_abort()
time.sleep(3)

# Notify the subthread to exit and wait
stop_flag.set()
t.join()

robot.logout()
import time
import jkrc
import threading

stop_flag = threading.Event()

def print_state(name, robot):
    while not stop_flag.is_set():
        ret = robot.get_program_info()
        print("the robot program info is:", ret)
        time.sleep(1)

robot = jkrc.RC("192.168.220.157")
robot.login(1)
ret = robot.program_load("program_test")
ret = robot.get_loaded_program()    
print("the loaded program is:", ret[1])
robot.program_run()

t = threading.Thread(target=print_state, args=("p1_state", robot))
t.start()  # Normal subthread, daemon not set

time.sleep(2)
robot.program_pause()
time.sleep(2)
robot.program_resume()
time.sleep(2)
robot.program_abort()
time.sleep(3)

# Notify the subthread to exit and wait
stop_flag.set()
t.join()

robot.logout()

Set robot operating speed ratio

set_rapidrate(rapid_rate)

Parameter description
- rapid_rate: Robot operating speed ratio
Return Value
- Success: (0,)
- Failure: others

Get robot operating speed ratio

get_rapidrate()

Return Value
- Success: (0, rapidrate), rapidrate is the speed ratio, return value is in the closed interval between 0 and 1
- Failure: others

Trajectory Replay

Set trajectory reproduction configuration parameters

Set the trajectory replay configuration parameters, which can set spatial position acquisition accuracy, attitude acquisition accuracy, script execution speed, and script execution acceleration.

set_traj_config(xyz_interval, rpy_interval, vel, acc)

Parameter description
- xyz_interval: Coordinate accuracy for trajectory replay
- rpy_interval: Attitude accuracy for trajectory replay
- vel: Execution speed for trajectory replay
- acc: Execution acceleration for trajectory replay
Return Value
- Success: (0,)
- Failure: others
Code Example

import jkrc  
import time  

#Coordinate system  
COORD_BASE  = 0  
COORD_JOINT = 1  
COORD_TOOL  = 2  
#Motion mode  
ABS = 0  
INCR = 1  

robot = jkrc.RC("192.168.2.160")  
robot.login(1)  
robot.power_on()  
robot.enable_robot()  
robot.joint_move(joint_pos =[1,1,1,1,1,1] ,move_mode = 0 ,is_block = True ,speed = 10 )  
print("joint")  
robot.set_traj_config([0.1, 0.1, 25, 100]) #Set the trajectory replay parameters, valid only during recording  
time.sleep(0.1)  
ret = robot.get_traj_config()#Get trajectory replay parameters  
print("traj_config:")  
print(ret)  
robot.set_traj_sample_mode(True, 'pythonTrack')#Start trajectory replay acquisition  
time.sleep(0.1)  
robot.joint_move(joint_pos =[-1,1,1,1,1,1] ,move_mode = 0 ,is_block = True ,speed = 30*3.14/180 )#Blocking motion  
robot.joint_move(joint_pos =[1,1,1,1,1,1] ,move_mode = 0 ,is_block = True ,speed = 30*3.14/180 )  
# robot.jog(2,INCR,COORD_BASE,10,-2)  
# robot.jog(2,INCR,COORD_BASE,10,2)  
robot.set_traj_sample_mode(False, 'pythonTrack')#End trajectory replay acquisition  
time.sleep(1)  
res = robot.generate_traj_exe_file('pythonTrack')#Convert the acquired trajectory replay file into an executable script  
print(res)  
robot.program_load("track/pythonTrack")#Load trajectory program  
time.sleep(0.1)  
robot.program_run()

Get trajectory reproduction configuration parameters

Obtain trajectory replay configuration parameters, including spatial position acquisition accuracy, attitude acquisition accuracy, script execution speed, and script execution acceleration.

get_traj_config()

Return Value
- Success: (0 , ( xyz_interval, rpy_interval, vel, acc))
  - xyz_interval: Spatial position data acquisition speed
  - rpy_interval: Attitude data acquisition accuracy
  - vel: Script execution speed
  - acc: Script execution acceleration
- Failure: others

Collect trajectory reproduction data control switch

set_traj_sample_mode(mode, filename)

Parameter description
- mode: Control mode, True means starting data acquisition, False means ending data acquisition.
- filename: Name of the file where the data is stored.
Return Value
- Success: (0,)
- Failure: others

Query status of collected trajectory reproduction data

Hint:

When in data acquisition state, it is not allowed to turn on the data acquisition switch again.

get_traj_sample_status()

Return Value
- Success: (0, sample_status), sample_status: Data status, True means data is being acquired, False means data acquisition has ended.
- Failure: others

Query the names of existing trajectory reproduction data files in the controller

This interface has been deprecated

get_exist_traj_file_name ()

Return Value
- Success: (0,)
- Failure: others

Rename file names of trajectory reproduction data

This interface has been deprecated

rename_traj_file_name (src, dest)

Parameter description
- src: Source file name
- dest: Target file name, file name length cannot exceed 100 characters, cannot be empty, Chinese characters are not supported in target file name.
Return Value
- Success: (0,)
- Failure: others
Code Example

import jkrc                               #Import module  
robot = jkrc.RC("192.168.2.226")      #Returns a robot object  
robot.login(1)  
robot.rename_traj_file_name('/home/src', '/home/dst')  
robot.logout() #Log out

Delete trajectory reproduction data files in the controller

This interface has been deprecated

remove_traj_file(filename)

Parameter description
- filename: The name of the file to be deleted
Return Value
- Success: (0, )
- Failure: others
Code Example

import jkrc                           # Import module  
robot = jkrc.RC("192.168.2.226")  #Returns a robot object  
robot.login(1)  
robot.remove_traj_file('test')  
robot.logout() #Log out

Generate controller execution script from trajectory reproduction data files in the controller

generate_traj_exe_file(filename)

Parameter description
- filename: The filename of the data
Return Value
- Success: (0, )
- Failure: others

Robot kinematics

Calculate the robot inverse solution

Calculate the inverse solution for the specified pose under the current tool, current installation angle, and current user coordinate system settings.

kine_inverse(ref_pos, cartesian_pose)

Parameter description
- ref_pos: Joint space reference position, it is recommended to use the robot's current joint position.
- cartesian_pose: Result of Cartesian space pose calculation.
Return Value
- Success: (0 , joint_pos) joint_pos is a tuple containing 6 elements (j1, j2, j3, j4, j5, j6), j1, j2, j3, j4, j5, j6 respectively represent the angle values of joints 1 to 6
- Failure: others

Extended robot inverse solution

Calculate the inverse solution for the specified pose under the specified tool, current installation angle, and specified user coordinate system settings.

kine_inverse_extend(ref_pos, cartesian_pose, tool, userFrame)

Parameter description
- ref_pos: Joint space reference position, it is recommended to use the robot's current joint position.
- cartesian_pose: Result of Cartesian space pose calculation.
- tool: Specified tool coordinate system
- userFrame: Specified user coordinate system
Return Value
- Success: (0 , joint_pos) joint_pos is a tuple containing 6 elements (j1, j2, j3, j4, j5, j6), j1, j2, j3, j4, j5, j6 respectively represent the angle values of joints 1 to 6
- Failure: others

Calculate the robot forward solution

Calculate the pose value of the specified joint position under the current tool, current installation angle, and current user coordinate system settings.

kine_forward(joint_pos)

Parameter description
- joint_pos: Joint space position
Return Value
- Success: (0, cartesian_pose), cartesian_pose is a tuple containing 6 elements (x, y, z, rx, ry, rz), where x, y, z, rx, ry, rz represent the pose values of the robot tool end
- Failure: others
Code Example

# -*- coding: utf-8 -*-  
import jkrc  

robot = jkrc.RC("192.168.220.158") #Return a robot object  
robot.login(1)                   #Login  
ret = robot.get_joint_position()  
if ret[0] == 0:  
    print("the joint position is :",ret[1])  
else:  
    print("some things happened, the errcode is: ",ret[0])       
joint_pos = ret[1]      
ret = robot.kine_forward(joint_pos)   #Calculate the robot forward solution
if ret[0] == 0:  
    print("kine_forward success, result = :",ret[1])  
else:  
    print("some things happened, the errcode is: ",ret[0])               
robot.logout()  #Log out

Extended robot forward solution

Calculate the pose value of the specified joint position under the specified tool, current installation angle, and specified user coordinate system settings.

kine_forward_extend(joint_pos, tool, userFrame)

Parameter description
- joint_pos: Joint space position
- tool: Specified tool coordinate system
- userFrame: Specified user coordinate system
Return Value
- Success: (0, cartesian_pose), cartesian_pose is a tuple containing 6 elements (x, y, z, rx, ry, rz), where x, y, z, rx, ry, rz represent the pose values of the robot tool end
- Failure: others

Convert Euler angles to rotation matrix

rpy_to_rot_matrix(rpy = [rx,ry,rz])

Parameter description
- rpy: Euler angle data [rx, ry, rz to be converted]
Return Value
- Success: (0, rot_matrix), rot_matrix is a 3x3 rotation matrix (row-major order)
- Failure: others

Convert rotation matrix to Euler angles

rot_matrix_to_rpy(rot_matrix)

Parameter description
- rot_matrix: rotation matrix data to be converted
Return Value
- Success: (0, rpy), rpy is a tuple of Euler angles with length 3 (rx, ry, rz)
- Failure: others

Convert quaternion to rotation matrix

quaternion_to_rot_matrix(quaternion = [w,x,y,z])

Parameter description
- quaternion: quaternion data to be converted
Return Value
- Success: (0, rot_matrix), rot_matrix is a 3x3 rotation matrix
- Failure: others

Convert rotation matrix to quaternion

rot_matrix_to_quaternion(rot_matrix)

Parameter description
- rot_matrix: 3x3 rotation matrix
Return Value
- Success: (0, quaternion), quaternion is a tuple of length 4 (w, x, y, z)
- Failure: others
Code Example

import jkrc  
robot = jkrc.RC("192.168.2.160")  
robot.login(1)  
ret = robot.get_tcp_position()  
print(ret)  
rpy = [ret[1][3], ret[1][4], ret[1][5]]#Get rpy  
ret = robot.rpy_to_rot_matrix(rpy)#Convert rpy to rotation matrix  
print(ret)  
rot_matrix = ret[1]#Get rotation matrix  
ret = robot.rot_matrix_to_rpy(rot_matrix)#Convert rotation matrix to rpy  
print(ret)  
ret = robot.rot_matrix_to_quaternion(rot_matrix)#Convert rotation matrix to quaternion  
print(ret)  
quaternion = ret[1]  
ret = robot.quaternion_to_rot_matrix(quaternion)#Convert quaternion to rotation matrix  
print(ret)  
robot.logout()

Get the DH parameters of the currently connected robot arm

Get robot arm DH parameters

get_dh_param()

Return Value
- Success: (0, dhparam), dhparam is the DH parameters
- Failure: others
Code Example

# -*- coding: utf-8 -*-  
import jkrc  

robot = jkrc.RC("192.168.220.158") #Return a robot object  
robot.login(1)                   #Login   
ret = robot.get_dh_param()
if ret[0] == 0:  
    print("get_dh_param success, result is: ", ret[1])  
else:  
    print("some things happened, the errcode is: ",ret[0])               
robot.logout()  #Log out

Robot servo motion

Hint:

When the user uses this interface, they must first call servo_move_enable(True) to enter position control mode.
This command is generally used in university research when performing trajectory planning.
When the user controls the robot’s movement in this mode, the controller’s planner does not participate in motion interpolation, and the position commands are sent directly to the servo. Therefore, the user needs to perform trajectory planning themselves; otherwise, the robot’s motion performance will be poor, such as severe shaking, and will not meet the user’s expectations.
Since the controller's control cycle is 8ms, it is recommended that the user's sending cycle also be 8ms, and it must be sent continuously; sending only once will have no effect. If the network condition is poor, the sending cycle can be less than 8ms.
The maximum joint speed of the JAKA robot is 180 degrees/second. If the sent joint angles cause the joint speed to exceed this limit, the command will fail. For example, if the sent joint angles are 1.5, 0.5, 0.5, 0.5, 0.5, 0.5, and the sending cycle is 8ms, then 1.5/0.008 = 187.5 degrees/second, which exceeds the joint speed limit. The command will therefore fail.
After using this command, you need to call servo_move_enable(False) to exit position control mode.
This command differs significantly from the previously mentioned joint_move(); joint_move’s interpolation is handled by the controller, and the user does not need to worry about it. When using the servo_j command, users must perform trajectory planning in advance; otherwise, the results will be poor and will not meet expectations. Unless there is a special need, it is recommended to use joint_move instead of servo_j for robot movement in joint space.

Query whether the robot arm is in servo motion state

is_in_servomove()

Return Value
- Success: (0, in_servo), where in_servo equals 1 means the robot is in servo motion mode, and 0 means the opposite.
- Failure: others

Enable robot servo move mode

servo_move_enable(enable|is_block, robot_id)

Parameter description
- enable: TRUE enters SERVO MOVE mode, FALSE exits the mode.
- is_block: TRUE for blocking mode, FALSE for non-blocking mode, default value is TRUE (optional parameter).
- robot_id: robot arm ID, default value is 0 (optional parameter).
Return Value
- Success: (0,)
- Failure: others

Robot joint space servo mode motion

servo_j(joint_pos, move_mode|step_num, do_info, robot_id)

Parameter description
- joint_pos: target position for robot joint movement.
- move_mode: specifies the motion mode. 0 for absolute motion, 1 for incremental motion.
- step_num: Multiple cycle period, servo_j motion period is step_num*8ms, where step_num>=1, default value is 1 (optional parameter)
- do_info: Specify DO information, default value is nullptr (optional parameter)
- robot_id: robot arm ID, default value is 0 (optional parameter)
Return Value
- Success: (0, queue_num), queue_num returns the queue length of the controller (cannot exceed 100)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import jkrc
import time
import math

ABS = 0
Enable = True

robot = jkrc.RC("192.168.220.158")
robot.login(1)
robot.power_on()
robot.enable_robot()
robot.servo_move_enable(Enable, False) #Enable servo motion mode in non-blocking mode

print("servo mode enabled")

target_joint = [0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
do_info = [0, 0, 1]
step_num = 1

# ===== Motion Parameters =====
amp_deg = 10.0
amp = math.radians(amp_deg)
freq = 0.2                 # Hz
dt = 0.008                 # 8 ms → 125 Hz

t = 0.0

try:
    while True:
        ret = robot.servo_j(target_joint, ABS, step_num, do_info)

        if ret[0] != 0:
            print("servo_j error:", ret)
            break

        queue_len = ret[1]
        print("queue_len =", queue_len)

        # === Queue rate limiting ===
        if queue_len > 10:
            time.sleep(0.01)
            continue

        # === Generate reciprocating trajectory ===
        target_joint[0] = amp * math.sin(2 * math.pi * freq * t)
        t += dt

except KeyboardInterrupt:
    print("Interrupted by user")

finally:
    robot.servo_move_enable(False, False)
    robot.logout()
    print("servo mode disabled")

Robot Cartesian space servo mode motion

servo_p(cartesian_pose, move_mode|step_num, do_info, robot_id)

Parameter description
- cartesian_pose: Target position for robot Cartesian space motion.
- move_mode: Specifies the motion mode, 0 for absolute motion, 1 for incremental motion.
- step_num: Multiple cycle period, servo_j motion period is step_num*8ms, where step_num>=1, default value is 1 (optional parameter)
- do_info: Specify DO information, default value is nullptr (optional parameter)
- robot_id: robot arm ID, default value is 0 (optional parameter)
Return Value
- Success: (0, queue_num), queue_num returns the queue length of the controller (cannot exceed 100)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import jkrc
import time
import math

ABS = 0
Enable = True

robot = jkrc.RC("192.168.220.158")
robot.login(1)
robot.power_on()
robot.enable_robot()

start_joint = [0.0, -0.5, 1.2, 0.0, 1.0, 0.0]
robot.joint_move(start_joint, ABS, True, 0.5)

robot.servo_move_enable(Enable, True) # Blocking mode enables servo motion mode

print("servo_p mode enabled")

# ===== Read the current TCP pose as the reference =====
ret = robot.get_tcp_position()
if ret[0] != 0:
    raise RuntimeError("get_tcp_position failed")

base_pose = list(ret[1])   # [x, y, z, rx, ry, rz]

print("base_pose:", base_pose)

# ===== Servo parameters =====
do_info = [0, 0, 1]
step_num = 1

amp_mm = 8.0              # Translation amplitude
amp_rot = 0.02            # Pose disturbance
freq = 0.2                # Hz
dt = 0.008                # 8 ms

t = 0.0

try:
    while True:
        # === Generate Cartesian reciprocating trajectory ===
        pose = base_pose.copy()
        # ---- Translation: reciprocating in X direction ----
        pose[0] = base_pose[0] + amp_mm * math.sin(2 * math.pi * freq * t)

        # ---- Attitude perturbation: around Z axis ----
        pose[5] = base_pose[5] + amp_rot * math.sin(2 * math.pi * freq * t)

        # === Send servo_p ===
        t_start = time.perf_counter()
        ret = robot.servo_p(pose, ABS, step_num, do_info)
        t_end = time.perf_counter()
        servo_cost_ms = (t_end - t_start) * 1000.0
        print("servo_p cost: %.2f ms" % servo_cost_ms)
        if ret[0] != 0:
            print("servo_p error:", ret)
            break

        t += dt

except KeyboardInterrupt:
    print("Interrupted by user")

finally:
    robot.servo_move_enable(False)
    robot.logout()
    print("servo mode disabled")

Disable filter in robot servo mode

Disable filter in robot SERVO mode. This command cannot be set in SERVO mode, but can be set after exiting SERVO.

servo_move_use_none_filter()

Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import jkrc                           # Import module  
robot = jkrc.RC("192.168.220.158")  # Returns a robot object  
robot.login(1)  
robot.servo_move_use_none_filter()  
robot.logout() #Log out

First-order low-pass filter in joint space in robot servo mode

First-order low-pass filter in joint space in robot SERVO mode. This command cannot be set in SERVO mode, but can be set after exiting SERVO.

servo_move_use_joint_LPF(cutoffFreq)

Parameter description
- cutoffFreq: cutoff frequency of the first-order low-pass filter.
Return Value
- Success: (0,)
- Failure: others
Code Example

import jkrc                           # Import module  
robot = jkrc.RC("192.168.2.226")  #Returns a robot object  
robot.login(1)  
robot.servo_move_use_joint_LPF(0.5)  
robot.logout() #Log out

Nonlinear filtering in joint space in robot servo mode

Nonlinear filtering in joint space under robot SERVO mode. This command cannot be set in SERVO mode; it can be set after exiting SERVO.

servo_move_use_joint_NLF(max_vr, max_ar, max_jr)

Parameter description
- max_vr: Upper limit value (absolute value) of orientation change speed in Cartesian space °/s
- max_ar: Upper limit value (absolute value) of acceleration of orientation change speed in Cartesian space °/s^2
- max_jr: Upper limit value (absolute value) of jerk of orientation change speed in Cartesian space °/s^3
Code Example

import jkrc                           # Import module  
robot = jkrc.RC("192.168.2.226")  #Returns a robot object  
robot.login(1)  
robot.servo_move_use_joint_NLF(max_vr=2, max_ar=2, max_jr=4)  
robot.logout() #Log out

Nonlinear filtering in Cartesian space under robot servo mode

Nonlinear filtering in Cartesian space under robot SERVO mode. This command cannot be set in SERVO mode; it can be set after exiting SERVO.

servo_move_use_carte_NLF(max_vp, max_ap, max_jp, max_vr, max_ar, max_jr|ori_quat)

Parameter description
- max_vp: Upper limit value (absolute value) of movement command speed in Cartesian space mm/s
- max_ap: Upper limit value (absolute value) of movement command acceleration in Cartesian space mm/s^2
- max_jp: Upper limit value (absolute value) of movement command jerk in Cartesian space mm/s^3
- max_vr: Upper limit value (absolute value) of orientation change speed in Cartesian space °/s
- max_ar: Upper limit value (absolute value) of acceleration of orientation change speed in Cartesian space °/s^2
- max_jr: Upper limit value (absolute value) of jerk of orientation change speed in Cartesian space °/s^3
- ori_quat: Specifies the representation method for describing Cartesian space orientation. 0 means use Euler angles, 1 means use quaternions. Default is 0 (optional parameter)
Return Value
- Success: (0,)
- Failure: others
Code Example

import jkrc                           # Import module  
robot = jkrc.RC("192.168.2.226")  #Returns a robot object  
robot.login(1)  
robot.servo_move_use_carte_NLF(max_vp=2, max_ap=2, max_jp=4,max_vr=2, max_ar=2, max_jr=4)  
robot.logout() #Log out

Multi-order mean filtering in joint space under robot servo mode

Multi-order mean filtering in joint space under robot SERVO mode. This command cannot be set in SERVO mode; it can be set after exiting SERVO.

servo_move_use_joint_MMF(max_buf, kp, kv, ka)

Parameter description
- max_buf: Size of the mean filter buffer.
- kp: Acceleration filter coefficient.
- kv: Velocity filter coefficient.
- ka: Position filter coefficient.
Return Value
- Success: (0,)
- Failure: others
Code Example

import jkrc                           # Import module  
robot = jkrc.RC("192.168.2.226")  #Returns a robot object  
robot.login(1)  
robot.servo_move_use_joint_MMF(max_buf=20 , kp=0.2 , kv=0.4 ,ka=0.2)  
robot.logout() #Log out

Velocity foresight parameter setting in Servo mode

Speed foresight filter in SERVO mode. This command cannot be set in SERVO mode, but can be set after exiting SERVO.

servo_speed_foresight(max_buf, kp|ori_quat)

Parameter description
- max_buf: Size of the mean filter buffer.
- kp: Acceleration filter coefficient.
- ori_quat: Specifies the representation method for describing Cartesian space orientation. 0 means use Euler angles, 1 means use quaternions. Default is 0 (optional parameter)
Return Value
- Success: (0,)
- Failure: others

Joint space PCM filtering settings in Servo mode

Joint space PCM filter under SERVO mode; this command cannot be set in SERVO mode, can be set after exiting SERVO

servo_move_use_joint_PCM(max_buf, kp)

Parameter description
- max_buf: Size of the mean filter buffer.
- kp: Acceleration filter coefficient.
Return Value
- Success: (0,)
- Failure: others

Cartesian space PCM filtering settings in Servo mode

Cartesian space PCM filter under SERVO mode; this command cannot be set in SERVO mode, can be set after exiting SERVO

servo_move_use_carte_PCM(max_buf, kp)

Parameter description
- max_buf: Size of the mean filter buffer.
- kp: Acceleration filter coefficient.
Return Value
- Success: (0,)
- Failure: others

Robot force control interface

JAKA robots provide a set of force control interfaces based on end force sensors. Users can use these interfaces to achieve advanced force control functions such as constant force compliance control, thereby implementing more complex application scenarios such as specified directional dragging in Cartesian space, force-controlled assembly, polishing, etc.

It should be noted that these interfaces rely on the end force sensor.

It is recommended to read this section after completing the Force Control product user manualopen in new window, and to refer to the JAKA SDK Force Control Function Quick Start Guide for open in new windowbetter understanding. To avoid lengthy text, in this section “force control” refers to “force compliance control”, and “end force sensor,” “force sensor,” and “sensor” all refer to 6-dimensional or 1-dimensional force/torque sensors installed at the robot’s end.

Set end force sensor model

Set the sensor model. Input a number representing the corresponding sensor model.

set_torsensor_brand(sensor_brand)

Parameter description
- sensor_brand Sensor model, value range is 1-6 or 10, which must match the model number engraved on the sensor's hardware casing. Among them, 10 specifically refers to a sensor built into the robot flange. This type of sensor is automatically managed by the system and requires no configuration via this interface.
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import jkrc                       #Import module  
robot = jkrc.RC("192.168.220.158")  # Returns a robot object  
robot.login(1)  
ret = robot.set_torsenosr_brand(2)
if ret[0] == 0:  
    print("set_torsenosr_brand success")  
else:  
    print("some things happened, the errcode is: ",ret[0])  
robot.logout() #Log out

Get end force sensor model

get_torsensor_brand()

Return Value
- Success: (0, sensor_brand), sensor_brand: sensor model.
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import jkrc                       #Import module  
robot = jkrc.RC("192.168.220.158")  # Returns a robot object  
robot.login(1)  
ret=robot.get_torsenosr_brand()  
if ret[0] == 0:  
    print("the sensor_band is", ret[1])
else:  
    print("some things happened, the errcode is: ",ret[0])  
robot.logout() #Log out

Enable or disable end force sensor

set_torque_sensor_mode(sensor_mode)

Parameter description
- sensor_mode: Sensor operating mode. 0 means turning off the sensor, 1 means turning on the sensor.
Return Value
- Success: (0,)
- Failure: others

Set sensor end load

Set the end load of the sensor. Input is the load mass and the coordinates of the load’s center of gravity.

Note: Please carefully distinguish between set_torq_sensor_tool_payload and set_payload.

payload affects the dynamics of the robot arm;

tool_payload affects the force control effect (i.e., force and torque compensation during force control)

Note: For robot arm models with built-in sensors in the end flange (such as the S series), the sensor’s end load is no different from the robot arm’s load. In this case, the two corresponding setting and query interfaces are equivalent.

set_torq_sensor_tool_payload (mass, centroid)

Parameter description
- mass: payload mass, unit: kg
- centroid: Coordinates of the load’s center[ of gravity x, y, z], unit: mm
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import jkrc                       #Import module  
robot = jkrc.RC("192.168.220.158")  # Returns a robot object  
robot.login(1)  
ret = robot.set_torq_sensor_tool_payload(mass= 1, centroid =[10,10,0])  
if ret[0] == 0:  
    print("set_torq_sensor_tool_payload success")
else:  
    print("some things happened, the errcode is: ",ret[0])  
robot.logout() #Log out

Get sensor end load

Obtain the load mass at the end of the sensor and the position coordinates of the load’s center of mass.

get_torq_sensor_tool_payload ()

Return Value
- Success: (0,(mass, centroid))
  - mass: load mass, unit: kg.
  - centroid: load center of mass position[ x, y, z], unit: mm.
- Failure: others

Get end load identification status

get_torq_sensor_identify_status()

Parameter description
- identify_status: identification status, 0 means identification is complete and the result is ready to read, 1 means no result available to read yet, 2 means identification failed.
Return Value
- Success: (0,identify_status)
- Failure: others

Start identifying the load at the tool end

Start identifying the load at the tool end, input is a tuple containing 6 elements, corresponding to the 6 joint angles at the end position. Note: This is a command that will trigger movement, causing the robot to move to the position specified by joint_pos.

start_torq_sensor_payload_identify(joint_pos)

Parameter description
- joint_pos: the end point for load identification. For precautions about setting the end position, please refer to the relevant function description in the force control product manualopen in new window.
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-   
import time        
import jkrc  
PI = 3.1415926  

robot = jkrc.RC("192.168.220.158") # returns a robot object  
ret = robot.login(1)#Login  
ret = robot.power_on()  
ret = robot.enable_robot()  
robot.set_torsenosr_brand(2)  
robot.set_torque_sensor_mode(1)  
robot.set_compliant_type(1, 1)  
print("inint sensor comple")  
print("ready to run")  
ret = robot.get_joint_position()  
joint_pos_origin = ret[1]  
joint_pos = ret[1]  
print(joint_pos)  
joint_pos[3] += PI / 4  
if (joint_pos[3] > 265 * PI / 180):  
    joint_pos[3] -= 90  
joint_pos[4] += PI / 4  
if (joint_pos[4] > 320 * PI / 180):  
    joint_pos[4] -= 90  
joint_pos[5] += PI / 4  
if (joint_pos[5] > 265 * PI / 180):  
    joint_pos[5] -= PI  
print(joint_pos)  
ret = robot.start_torq_sensor_payload_identify(joint_pos)  
time.sleep(1)  
flag = 1  
while (1 == flag):  
    ret = robot.get_torq_sensor_identify_staus()  
    print(ret)  
    time.sleep(1)  
    flag = ret[1]  
print("identy_finish")  
ret = robot.get_torq_sensor_payload_identify_result()  
print(ret)  
ret = robot.set_torq_sensor_payload()  
print(ret)  
ret = robot.get_torq_sensor_payload_identify_result()  
print(ret)  
robot.joint_move(joint_pos_origin,0,1,10)  
print("back")  
robot.logout()  #Log out

Get end load identification result

Get end load identification result. Input is load mass and load centroid position coordinates.

get_torq_sensor_payload_identify_result()

Parameter description
- mass: payload mass, unit: kg
- centroid: load centroid position[ x, y, z], unit: mm
Return Value
- Success: (0,)
- Failure: others

Set end force sensor communication parameters

set_torque_sensor_comm(type, ip_addr, port)

Parameter description
- type: Sensor type
- ip_addr: Sensor IP address
- port: Port number
- When set to 1 or using USB, ip_addr and port are not applicable. Just use the default parameters as shown in the example.
Return Value
- Success: (0,)
- Failure: others

Get end force sensor communication parameters

get_torque_sensor_comm()

Return Value
- Success: (0, type, ip_addr, port)
  - type: 0 for using Ethernet or USB, 1 for using TIO.
  - ip_addr: Sensor IP address when using Ethernet.
  - port: Force control sensor port number when using Ethernet.
  - When using TIO or USB, ip_addr and port are invalid parameters, and the return value has no actual meaning.
- Failure: others

Set end force sensor low-pass filter cutoff frequency

set_torque_sensor_filter(torque_sensor_filter)

Parameter description
- torque_sensor_filter: Low-pass filter parameter, float, unit: Hz
Return Value
- Success: (0,)
- Failure: others

Get end force sensor low-pass filter cutoff frequency

get_torque_sensor_filter()

Parameter description
Return Value
- Success: (0, torque_sensor_filter)
  - torque_sensor_filter: Low-pass filter parameter, float, unit: Hz
- Failure: others

Set end force sensor soft limit

set_torque_sensor_soft_limit(fx, fy, fz, tx, ty, tz)

Parameter description
- fx: Force along the x-axis, unit: N
- fy: Force along the y-axis, unit: N
- fz: Force along the z-axis, unit: N
- tx: Torque around the x-axis, unit: Nm
- ty: Torque around the y-axis, unit: Nm
- tz: Torque around the z-axis, unit: Nm
Return Value
- Success: (0,)
- Failure: others

Get end force sensor soft limit

get_torque_sensor_soft_limit()

Return Value
- Success: (0, (fx, fy, fz, tx, ty, tz))
  - fx: Force along the x-axis, unit: N
  - fy: Force along the y-axis, unit: N
  - fz: Force along the z-axis, unit: N
  - tx: Torque around the x-axis, unit: Nm
  - ty: Torque around the y-axis, unit: Nm
  - tz: Torque around the z-axis, unit: Nm
- Failure: others

Enable or disable tool dragging

Compatibility interface reserved.

Compatible with controller 1.7.1, for 1.7.2 please use the alternative interface.

To enable or disable tool dragging, the sensor must be turned on and appropriate compliance control parameters set. In addition, it is recommended to perform at least one sensor zero calibration before enabling tool dragging.

enable_admittance_ctrl(enable_flag)

The corresponding interface for controller 1.7.2 is

set_ft_ctrl_mode(enable_flag)

Parameter description
- enable_flag: Flag, 0 disables force control drag enable, 1 enables it.
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-       
import jkrc  

robot = jkrc.RC("192.168.220.158") # returns a robot object  
ret = robot.login(1)#Login  
ret = robot.power_on()  
ret = robot.enable_robot()  
robot.set_torsenosr_brand(2)  
robot.set_torque_sensor_mode(1)  
robot.set_compliant_type(1, 1)  
print("inint sensor comple")  
print("ready to run")  
#Set compliance control parameters  
ret = robot.set_admit_ctrl_config(0, 0, 20, 5, 0, 0)  
ret = robot.set_admit_ctrl_config(1, 0, 20, 5, 0, 0)  
ret = robot.set_admit_ctrl_config(2, 1, 20, 10, 0, 0)
ret = robot.set_admit_ctrl_config(3, 0, 20, 5, 0, 0)  
ret = robot.set_admit_ctrl_config(4, 0, 20, 5, 0, 0)  
ret = robot.set_admit_ctrl_config(5, 0, 20, 5, 0, 0)  
#Set force control drag enable, 1 on, 0 off  
ret = robot.enable_admittance_ctrl(1)  
print("enable_admittance_ctrl open!")  
print("input any word to quit:")  
a = input()  
ret = robot.enable_admittance_ctrl(0)  
ret = robot.set_admit_ctrl_config(2, 0, 20, 5, 0, 0)  
robot.set_torque_sensor_mode(0)  
robot.logout()  #Log out

Set force control type and zero calibration (initialization) options

Compatibility interface reserved.

Adapted for 1.7.1 controller, split into multiple corresponding replacement interfaces in 1.7.2. When the 1.7.2 controller calls this interface, it only performs sensor zeroing trigger and sets the force control type function. Note that when sensor_compensation is set to 1, the compliance_type parameter must be set to 0, and you must wait 1 second before calling this interface again to set the compliance_type parameter.

set_compliant_type(sensor_compensation, compliance_type)

The 1.7.2 controller sensor zeroing interface is:

zero_end_sensor()

Parameter description
- sensor_compensation: 1 means immediately perform sensor zeroing once, and switch the APP's real-time force curve display and torqsensor11 returned on port 10000 to [][]actual external force; 0 means no zeroing operation, and when not in force control state, switch the APP's real-time force curve display and torqsensor11 returned on port 10000 to []the sensor's []original readings (if in force control state, it will still be actual external force).
- compliance_type: 0 means no compliance control method is used, 1 means constant force compliance control is enabled, 2 means speed compliance control is enabled.
Return Value
- Success: (0,)
- Failure: others
Code Example

# -*- coding: utf-8 -*-       
import jkrc  
robot = jkrc.RC("192.168.220.158") # returns a robot object  
ret = robot.login(1)#Login  
ret = robot.set_compliant_type(1,1)
if ret[0] == 0:  
    print("set_compliant_type success")  
else:  
    print("some things happened, the errcode is: ",ret[0])  
robot.logout()  #Log out

Obtain force control type and reading display (initialization) status

Compatibility interface reserved.

Adapt to 1.7.1 controller, 1.7.2 is the corresponding replacement interface. When the 1.7.2 controller calls this interface, it only implements the function of obtaining the force control type, and the sensor_compensation parameter is meaningless.

Get force control type and sensor initialization status

get_compliant_type()

Return Value
- Success: (0, sensor_compensation, compliance_type)
  - sensor_compensation: Whether to enable sensor compensation. 1 means that the APP's real-time force curve display and torq_sensor_monitor_data.actTorque represent the actual external force; 0 means that when not in force control mode, the APP's real-time force curve display and torq_sensor_monitor_data.actTorque represent the sensor's original readings (if in force control mode, they still represent the actual external force).
  - compliance_type 0 means no compliance control method is used; 1 means constant force compliance control; 2 means speed compliance control
- Failure: others

Set compliance control parameters

Set parameters for joint coordinate axis numbers, compliance direction, damping force, rebound force, constant force, and normal tracking during robot compliance control.

set_admit_ctrl_config(axis, opt, ftUser, ftConstant, ftNormalTrack, ftReboundFK)

Parameter description
- axis: Represents the Cartesian space coordinate axis number, with values from 0 to 5 corresponding respectively to fx, fy, fz, mx, my, mz directions.
- opt: Compliance direction, 0 means off, 1 means on.
- ftUser: Damping force, indicates the amount of force the user needs to apply for the robot to move in a certain direction at maximum speed.
- ftConstant: Constant force, set all to 0 during manual operation.
- ftNormalTrack: Normal tracking, set all to 0 during manual operation.
- ftReboundFK: Rebound force, indicates the robot's ability to return to its initial state.
Return Value
- Success: (0,)
- Failure: others

Set Sensor Coordinates

Compatibility interface reserved.

Adapt to 1.7.1 controller, in 1.7.2 different force control functions are split into multiple corresponding replacement interfaces. When the 1.7.2 controller calls this interface, it will call all replacement interfaces and set them to the same parameters.

set_ft_ctrl_frame(ftFrame)

Parameter description
- ftFrame: 0 Tool; 1 World
Return Value
- Success: (0,)
- Failure: others

Set Sensor Coordinates

Compatibility interface reserved.

Adapt to 1.7.1 controller, in 1.7.2 different force control functions are split into multiple corresponding replacement interfaces. When the 1.7.2 controller calls this interface, it will return the force control coordinate system corresponding to the constant force compliance control function.

Set Sensor Coordinates

get_ft_ctrl_frame()

Return Value
- Success: (0, ftFrame)
  - ftFrame: 0 Tool; 1 World
- Failure: others

Set force control compliance parameters

Compatibility interface reserved.

Obtain force control compliance parameters, acquiring the compliance direction, damping force, rebound force, constant force, and normal tracking for the six joints.

set_admit_ctrl_config(axis, opt, ftUser, ftReboundFK, ftConstant, ftNnormalTrack)

Parameter description
- axis: 0, x-axis; 1, y-axis; 2, z-axis; 3, rx; 4, ry; 5, rz.
- opt: 0 off, 1 on.
- ftUser: damping, affects the stiffness the robot’s end shows to the external environment. The larger this parameter is, the greater the stiffness displayed by the robot’s end. Unit: ×8 N·s/m (for x/y/z), ×16 Nm·s/π (for rx/ry/rz)
- ftReboundFK: rebound, indicates the elasticity coefficient between the robot’s compliance control process and the commanded trajectory (or initial position), units N/mm (for x/y/z), Nm/rad (for rx/ry/rz).
- ftConstant: represents target force, units N (for x/y/z), Nm (for rx/ry/rz).
- ftNnormalTrack: historical compatibility interface, currently must be set to 0 in all cases to ensure normal operation.
- For further understanding of the above parameters, please refer to the relevant descriptions in the Force Control product user manualopen in new window.
Return Value
- Success: (0,)
- Failure: others

Obtain force control compliance parameters

Compatibility interface reserved.

Adapt to 1.7.1 controller, in 1.7.2 different force control functions are split into multiple corresponding replacement interfaces. When the controller calls this interface in version 1.7.2, it will return the compliance parameters corresponding to the constant force compliance control function.

Obtain force control compliance parameters

get_admit_ctrl_config()

Return Value
- Success: (0, [[opt, ftUser, ftReboundFK, ftConstant, ftNormanlTrack], ……])
  - opt: 0 off, 1 on.
  - ftUser: Damping force, indicates the amount of force the user needs to apply for the robot to move in a certain direction at maximum speed.
  - ftReboundFK: Rebound force, indicates the robot's ability to return to its initial state.
  - ftConstant: Constant force, set all to 0 during manual operation.
  - ftNormalTrack: Normal tracking, set all to 0 during manual operation.
- Failure: others

Disable torque control

Disable force compliance control (effective for constant force compliance control and speed compliance control, but not effective for tool dragging)

disable_force_control ()

Return Value
- Success: (0,)
- Failure: others

Set speed compliance control parameters

Interface 1.7.2 is deprecated and not recommended for use

Set the speed compliance control parameters. Speed compliance control has 3 levels and 4 ratio levels.

set_vel_compliant_ctrl (level, rate1, rate2, rate3, rate4)

Parameter description
- level: Compliance control level, levels are: 1, 2, 3
  - rate1: Ratio level 1
  - rate2: Ratio level 2
  - rate3: Ratio level 3
  - rate4: Ratio level 4
    Note:
    Relationship between the ratio levels: 0<rate4<rate3<rate2<rate1<1;
When level=1, only rate1 and rate2 can be set, while rate3 and rate4 values are all 0
When level=2, only rate1, rate2, and rate3 can be set, while rate4 value is 0
When level=3, values for rate1, rate2, rate3, and rate4 can be set :::
Return Value
- Success: (0,)
- Failure: others

Set compliance control torque conditions

Interface 1.7.2 is deprecated and not recommended for use

set_compliance_condition(fx, fy, fz, tx, ty, tz)

Parameter description (The following parameters are torque limits for compliance control; exceeding the limit will stop)
- fx: Force along the x-axis, unit: N
- fy: Force along the y-axis, unit: N
- fz: Force along the z-axis, unit: N
- tx: Torque around the x-axis, unit: Nm
- ty: Torque around the y-axis, unit: Nm
- tz: Torque around the z-axis, unit: Nm
Return Value
- Success: (0,)
- Failure: others

Note:

The following interfaces are only for controllers version 1.7.2 and above. Controllers version 1.7.2 and above should preferentially use these interfaces.

Zero Sensor

Trigger sensor zero calibration and block for 0.5 seconds.

zero_end_sensor()

Return Value
- Success: (0,)
- Failure: others

Sensor hardware-level calibration

Trigger sensor hardware-level calibration to improve sensor reading accuracy.

tio_sensor_calib(type)

Parameter description
- type: 0: no action. 1: perform calibration. 2: query current calibration values.
Return Value
- Success: (0,)
- Failure: others
  Warning
  This command will not take effect immediately; it will calibrate based on the current sensor state during the first power-on after restarting the robot control cabinet. The calibration process may take 5-10 seconds, so after issuing this command, wait 5-10 seconds at the next restart and power-on before enabling to ensure the best calibration result.

This command is only used when extreme improvement of sensor value accuracy is needed. Incorrect use may cause excessive zero-point shift leading to unexpected situations. Frequent or repeated calibration is not recommended. For general sensor value calibration, it is recommended to perform software zeroing through the sensor zeroing interface.

After this command takes effect, be sure to record the current calibration result displayed in the app after startup, and ensure that the sum of the actual applied force during subsequent use and this calibration result does not exceed the sensor's range. :::

Get sensor operating status

get_torque_sensor_mode()

Return Value
- Success: (0,sensor_mode)
  - sensor_mode: Sensor on or off state, 0 is off; 1 is on
- Failure: others

Get sensor status and data

get_torque_sensor_data(type)

Parameter description
- type: Type of data acquisition, 1: same as torq_sensor_monitor_data.actTorque; 2: same as torq_sensor_monitor_data.torque, the sensor's raw reading; 3: same as torq_sensor_monitor_data.realTorque, actual force after subtracting load gravity compensation and sensor offset;
Return Value
- Success: (0,(errorCode, status, data))
  - errorCode: Error code
  - status: Status
  - data: Data
- Failure: others

Set constant-force compliance control parameters

set_ft_ctrl_config(type)

Parameter description
- type: Type of data acquisition, 1: same as torq_sensor_monitor_data.actTorque; 2: same as torq_sensor_monitor_data.torque, the sensor's raw reading; 3: same as torq_sensor_monitor_data.realTorque, actual force after subtracting load gravity compensation and sensor offset;
Return Value
- Success: (0,(errorCode, status, data))
  - errorCode: Error code
  - status: Status
  - data: Data
- Failure: others

Obtain the force control tool drag enable status

get_tool_drive_state()

Return Value
- Success: (0,enable_flag, drive_state)
  - enable_flag: 0 to disable force-control drag enable, 1 to enable
  - drive_state is the current drag state, indicating whether a singularity, speed, or joint limit warning is triggered
- Failure: others

Get tool drag coordinate system

get_tool_drive_frame()

Return Value
- Success: (0, ftFrame)
  - ftFrame: 0 Tool; 1 World
- Failure: others

Set tool drag coordinate system

set_tool_drive_frame(ftFrame)

Parameter description
- ftFrame: 0 Tool; 1 World
Return Value
- Success: (0,)
- Failure: others

Get fusion drag sensitivity

get_fusion_drive_sensitivity_level()

Return Value
- Success: (0,level)
  - level: Sensitivity level, value 0-5, 0 is off
- Failure: others

Set fusion drag sensitivity

set_fusion_drive_sensitivity_level(level)

Parameter description
- level: Sensitivity level, value 0-5, 0 is off
Return Value
- Success: (0,)
- Failure: others

Get motion restriction (singularity and joint limit) warning range

get_motion_limit_warning_range(warningRange)

Return Value
- Success: (0,warningRange) warningRange: Warning range
- Failure: others

Set motion restriction (singularity and joint limit) warning range

set_motion_limit_warning_range(warningRange)

Parameter description
- warningRange: Warning range
Return Value
- Success: (0,)
- Failure: others

Get force control speed limit

get_compliant_speed_limit(vel, angularvel)

Return Value
- Success: (0, vel, angularvel)
  - vel: Linear speed limit, mm/s:
  - angularvel: Angular speed limit, rad/s
- Failure: others

Set force control speed limit

set_compliant_speed_limit(vel, angularvel)

Parameter description
- vel: Linear speed limit, mm/s:
- angularvel: Angular speed limit, rad/s
Return Value
- Success: (0,)
- Failure: others

Get torque reference center

get_torque_ref_point()

Return Value
- Success: (0, refpoint)
  - refpoint: 0: Sensor center; 1: TCP center
- Failure: others

Set torque reference center

set_torque_ref_point(refpoint)

Parameter description
- refpoint: 0: Sensor center. 1: TCP center
Return Value
- Success: (0,)
- Failure: others

Get sensor sensitivity

get_end_sensor_sensitivity_threshold()

Return Value
- Success: (0,data)
  - fx: Force along the x-axis, unit: N
  - fy: Force along the y-axis, unit: N
  - fz: Force along the z-axis, unit: N
  - tx: Torque around the x-axis, unit: Nm
  - ty: Torque around the y-axis, unit: Nm
  - tz: Torque around the z-axis, unit: Nm
- Failure: others

Set sensor sensitivity

set_end_sensor_sensitivity_threshold(fx, fy, fz, tx, ty, tz)

Parameter description
- fx: Force along the x-axis, unit: N
- fy: Force along the y-axis, unit: N
- fz: Force along the z-axis, unit: N
- tx: Torque around the x-axis, unit: Nm
- ty: Torque around the y-axis, unit: Nm
- tz: Torque around the z-axis, unit: Nm
- 6-dimensional array, 0~1, the larger the value, the less sensitive the sensor
Return Value
- Success: (0,data)
- Failure: others

Set constant-force compliance control parameters

Set constant force compliance control parameters, same as the original set_admit_ctrl_config function, except the ftNnormalTrack input parameter is removed

Parameter description
- axis: Indicates which axis to configure; optional values are 0~5 compliance directions, corresponding to fx fy fz mx my mz
- opt 0 means unchecked, non-zero value means checked
- ftDamping: Damping force, indicating the stiffness of the robot during force control
- ftConstant: Represents the target force
- ftReboundFK: Rebound, indicates the strength with which the robot arm elastically returns to the commanded trajectory
Return Value Success: (0,) Failure: Others

set_cst_force_ctrl_config(axis, opt, ftDamping, ftConstant, ftReboundFK)

Get constant-force compliance control parameters

Get constant force compliance control parameters, same as the original get_admit_ctrl_config

Return Value
- Success: (0, ((0.0, 50.0, 0.0, 0.0, 0.0), (0.0, 50.0, 0.0, 0.0, 0.0), (1.0, 25.0, 0.0, 5.0, 0.0), (0.0, 5.0, 0.0, 0.0, 0.0), (0.0, 5.0, 0.0, 0.0, 0.0), (0.0, 5.0, 0.0, 0.0, 0.0)))
  - Parameter description: Returns six 5-dimensional arrays, representing the data corresponding to six axes. The meaning of each array's 5 elements refers to the description of the previous interface.
- Failure: Others

get_cst_force_ctrl_config()

Set constant-force compliance control coordinate system

Set constant force compliance control coordinate system, call the new internal controller interface

Parameter description
- cstForceFrame 0 tool 1 world
Return Value Success: (0,) Failure: Others

set_cst_force_ctrl_frame(cstForceFrame)

Get constant-force compliance control coordinate system

Obtain the constant force compliance control coordinate system, calling the controller's internal new interface.

Return value Success: (0, cstForceFrame)
- cstForceFrame 0 tool 1 world Failure: Others

get_cst_force_ctrl_frame()

Set force control drag feel parameters

Set the force control drag feel parameters, calling the corresponding internal interface of the controller.

Parameter description
- axis: Indicates which axis to configure; optional values are 0~5 compliance directions, corresponding to fx fy fz mx my mz
- opt 0 means unchecked, non-zero value means checked
- rigidity: Drag feel, range 0~1; the larger the value, the harder
- rebound: Indicates the strength with which the robot arm elastically returns to its initial position
Return Value Success: (0,) Failure: Others

set_tool_drive_config(axis, opt, rigidity, rebound)

Get tool dragging parameters

Obtain the tool drag parameters, calling the controller's internal new interface.

Parameter description
- admit_ctrl_cfg Storage address for robot arm force control compliance parameters
Return Value Success:

(0, ((0, 1, 0.0, 0.30000001192092896, <NULL>), (1, 1, 0.0, 0.30000001192092896, <NULL>), (2, 1, 0.0, 0.30000001192092896, <NULL>), (3, 1, 0.0, 0.30000001192092896, <NULL>), (4, 1, 0.0, 0.30000001192092896, <NULL>), (5, 1, 0.0, 0.30000001192092896, <NULL>)))

Parameter description: Returns six 5-dimensional arrays, each representing the data for one of the six axes. The meaning of each array’s 4 elements refers to the previous interface description. Failure: Others

get_tool_drive_config()

Force control tool drag enable

Force control tool drag enable, consistent with enable_admittance_ctrl. Tool drag parameters must be set first, and the force control sensor must be enabled and zeroed.

Parameter description
- enable_flag 0 means disable force control drag enable, 1 means enable
Return Value Success: (0,) Failure: Others

enable_tool_drive(enable_flag)

Activate/Deactivate Constant Force Compliant Control

Parameter description
- enable_flag 0 means disable, 1 means enable. Assigns a value to the compliantType variable inside the controller, consistent with the original set_compliant_type interface
Return Value Success: (0,) Failure: Others

enable_cst_force_ctrl(enable_flag)

Set force control termination condition

Set force control stop condition, same meaning as the command with the same name in APP graphical programming

set_force_stop_condition([opt, lowerlimiton, lowerlimit, upperlimiton, upperlimit], [...], [...], [...], [...], [...])

Parameter description
- opt: A 6-dimensional array indicating whether torque control termination conditions are enabled for each dimension; 0 means not selected, non-zero means selected
- lowerlimiton 6-dimensional array, 0 means no lower limit set, non-zero value means set
- lowerlimit: A 6-dimensional array; lower limit values
- upperlimiton 6-dimensional array, 0 means no upper limit set, non-zero value means set
- upperlimit: A 6-dimensional array; upper limit values The interface receives 6 lists (representing the 6 axes), each list contains 5 pieces of data, the specific meaning is as above.
Return Value Success: (0,) Failure: Others

set_force_stop_condition([0,1,2,3,4],[0,0,0,0,0],[0,0,0,0,0],[0,0,0,0,0],[0,0,0,0,0],[0,0,0,0,0])

Get constant-force compliance enable status

Get constant force compliance enable status, just read the compliantType value inside the controller

Return Value Success: (0, cst_force_ctrl_stat)
- cst_force_ctrl_stat, 0 means not enabled, 1 means enabled, 2 means speed mode (compatibility, new version will not have 2) Failure: Others

get_cst_force_ctrl_stat()

Set approach speed limit

Parameter description
- speed_limit linear speed limit, mm/s
- angular_speed_limit Angular velocity limit, rad/s
Return Value Success: (0, speed_limit, angular_speed_limit) Failure: Others

set_approach_speed_limit(speed_limit, angular_speed_limit)

Get approach speed limit

Return Value Success: (0, speed_limit, angular_speed_limit)
- speed_limit Linear speed limit, mm/s
- angular_speed_limit Angular speed limit, rad/s Failure: Others

get_approach_speed_limit()

Set constant-force control tolerance

Parameter description
- force_tol Force tolerance
- torque_tol Torque tolerance
Return Value
- Success: (0,)
- Failure: others

set_cst_force_ctrl_tol(force_tol, torque_tol)

Get constant-force control tolerance

Set constant-force control tolerance

Return Value
- Success: (0, force_tol, torque_tol)
  - force_tol Force tolerance
  - torque_tol Torque tolerance
- Failure: others

get_cst_force_ctrl_tol()

FTP

FTP initialization

Initialize ftp client, establish connection with control cabinet, can import/export program, track

init_ftp_client()

Return Value
- Success: (0,)
- Failure: others

FTP shutdown

close_ftp_client()

Return Value
- Success: (0,)
- Failure: others

Query the controller's FTP directory

get_ftp_dir(remotedir, type)

Parameter description
- remotedir: Name of the internal folder in the controller
- type: 0 files and folders 1 files 2 folders
Return Value
- Success: (0, ret) ret is a string
- Failure: others
Code Example

# -*- coding: utf-8 -*-
import jkrc                           # Import module  
robot = jkrc.RC("192.168.220.158")  # Returns a robot object  
robot.login(1)  
dir= "/program/"  
robot.init_ftp_client()  
result = robot.get_ftp_dir("/program/", 0)  
print(result)  
robot.close_ftp_client()  
robot.logout()

Download FTP file

Download a file or folder from the robot control cabinet’s FTP to the local system. To query trajectories use "/track/", to query script programs use "/program/".

download_file(local, remote, opt)

Parameter description
- remote The absolute path of the filename inside the controller. For a folder, it must end with "" or “/” depending on the system. For example, a single file "/program/test/test.jks" or a folder "/program/test/"
- local The absolute path of the filename to download to the local system
- opt: 1 single file, 2 folder
Return Value
- Success: (0,)
- Failure: others
Code example: Download the program folder on the FTP side to the program folder on the desktop

import jkrc  
robot = jkrc.RC("192.168.2.26") #VMmodel  
robot.login(1)  
remote = "/program/"  
local = "C:\\Users\\Administrator\\Desktop\\program\\track\\"  
robot.init_ftp_client()  
result = robot.download_file(local, remote, 2)  
print(result)  
robot.close_ftp_client()  
robot.logout()

Upload file to FTP

Upload a file of the specified type and name from the local system to the controller.

upload_file(local, remote, opt)

Parameter description
- remote The absolute path of the filename inside the controller where the file will be uploaded. For a folder, it must end with "" or “/” depending on the system.
- local The absolute path of the filename on the local system
- opt: 1 single file, 2 folder
Return Value
- Success: (0,)
- Failure: others
Code example: Upload all files and folders inside the lxxpro folder on the desktop to the FTP’s program/ folder

import jkrc  
robot = jkrc.RC("192.168.2.26") #VMmodel  
robot.login(1)  
remote = "/program/"  
local = "C:\\Users\\Administrator\\Desktop\\lxxpro\\"  
robot.init_ftp_client()  
result = robot.upload_file(local, remote, 2)  
print(result)  
robot.close_ftp_client()  
robot.logout()

Rename file on FTP

Rename the file of the specified type and name in the controller.

rename_ftp_file(local, remote, opt)

Parameter description
- remote The absolute path of the filename inside the controller. For a folder, it must end with "" or “/” depending on the system.
- des Target name for renaming
- opt 1 for a single file, 2 for a folder. Renaming a file will also rename all files inside the folder, which is convenient for /track/ usage.
Return Value
- Success: (0,)
- Failure: others
Code example: Rename all files and folders in the lxxpro folder on FTP to lxx

import jkrc  

robot = jkrc.RC("192.168.2.26") #VMmodel  
robot.login(1)  
remote = "/lxxpro/"  
des = "lxx"  
robot.init_ftp_client()  
result = robot.rename_ftp_file(remote, des, 2)  
print(result)  
robot.close_ftp_client()  
robot.logout()

Delete files to FTP

Delete files of the specified type and name from the controller.

del_ftp_file(remote, opt)

Parameter description
- remote The absolute path of the filename inside the controller. For a folder, it must end with "" or “/” depending on the system.
- opt: 1 single file, 2 folder
Return Value
- Success: (0,)
- Failure: others
Code example (Operate with caution, this example will delete all programs)

import jkrc  

robot = jkrc.RC("192.168.2.26") #VMmodel  
robot.login(1)  
dir= "/program/"  
robot.init_ftp_client()  
result = robot.del_ftp_file("/program/", 2)  
print(result)  
robot.close_ftp_client()  
robot.logout()

Interface call return value list and troubleshooting

Error codes	Description	Handling suggestions
0	success	null
2	interface error or controller not supported	Check the controller and SDK version information, upgrade or use another interface
-1	invalid handler	Please check whether login is done before calling the interface
-2	invalid parameter	Please check whether the parameters are correct
-3	failed to connect	Please check the network connection status, or whether the robot IP is correct
-4	inverse kinematics error	Inverse kinematics failed, please check the current coordinate system, or whether the reference joint angles are reasonable
-5	emergency stop	Emergency stop state, status retained
-6	not powered on	Not powered on
-7	not enabled	Not enabled
-8	not in servo mode	Not in servo mode. When executing servoJP, you must first enter servo mode. Please check whether the corresponding interface is called
-9	must disable enable before powering off	Must disable enable before powering off
-10	cannot operate, program is running	Cannot operate, a program is currently running. Please close the program first
-11	cannot open file, or file does not exist	Cannot open file, or file does not exist
-12	motion abnormal	Abnormal movement, possibly near a singularity point or exceeding robot movement limits
-14	ftp error	ftp abnormal
-15	socket msg or value oversize	Exceeding limit abnormal
-16	kine_forward error	Forward kinematics failed
-17	not support empty folder	Empty folders are not supported
-20	protective stop	Safeguard (Protective) Stop
-21	emergency stop	Emergency stop
-22	on soft limit	In soft limit position, manual drag of the robot is not possible; use the teaching function in the APP to approach the soft limit
-30	fail to encode cmd string	Command encoding failed, usually due to an error while parsing the message returned by the controller
-31	fail to decode cmd string	Command decoding failed, usually due to an error while parsing the message returned by the controller
-32	fail to uncompress port 10004 string	Failed to decompress data from port 10004, possibly due to network fluctuations or excessive data size
-40	move linear error	Linear movement failed, please check if there are any singular regions in the path
-41	move joint error	Joint movement failed, please check the set joint angles
-42	move circular error	Arc motion failed, please check the set parameters
-50	block_wait timeout	Blocking wait timeout
-51	power on timeout	Power-on timeout
-52	power off timeout	Power-off timeout
-53	enable timeoff	Enable timeout
-54	disable timeout	Disable timeout
-55	set userframe timeout	Setting user coordinate system timeout
-56	set tool timeout	Setting tool coordinate system timeout
-57	edg init failed	EDG function initialization failed
-58	edg is running, cannot use servo_j or servo_p	EDG function is running, cannot use servo_j or servo_p interface
-59	Current EDG mode does not support using edg_servo_j or edg_servo_p.	EDG function is running, cannot use edg_servo_j or edg_servo_p interface
-60	set io timeout	Setting IO timeout
-61	operation timeout	Interface timeout
-62	servo queue is full	Servo queue is full
-63	servo is not running	Servo mode is not started
-9997	not implement	Interface not implemented
-9998	deprecated interface	Interface will be removed in the future (function still available)
-9999	obsolete interface	Interface will be removed in the future (function unavailable)

Issue feedback

If there are any inaccurate descriptions or mistakes in the document, we kindly ask readers for their understanding and corrections. If you find any problems or wish to provide suggestions while reading, you can send an email to support@jaka.com , and we will reply to you as soon as possible.