Skip to main content

API Description

This chapter lists the interfaces and function descriptions supported by each version of xCore SDK. Different language versions have basically the same functional definitions for interfaces, but parameters, return values, and calling methods may differ.

Python: Instantiate rokae::Robot Class​

Depending on the robot configuration and number of axes, the Python version of the SDK provides the following Robot classes that can be instantiated. During initialization, it checks whether the selected configuration and number of axes match the connected robot:

Class NameApplicable Models
xMateRobotCollaborative 6-axis
xMateErProRobotCollaborative 7-axis
StandardRobotIndustrial 6-axis
xMateCr5RobotCollaborative CR5-axis
PCB4RobotIndustrial 4-axis
PCB3RobotIndustrial 3-axis

Robot Basic Operations and Information Query​

DescriptionInterfaceParametersReturn
Connect to RobotconnectToRobot()
Connect to RobotconnectToRobot(remoteIP,localIP)remoteIP - Robot IP address
localIP - Local address for real-time data. Optional; not supported on PCB3 / PCB4
DisconnectdisconnectFromRobot()
Query Robot Basic InforobotInfo()Controller version, model, number of axes, MAC, etc.
Robot Power On/Off and E-Stop StatuspowerState()on/off/estop/gstop
Robot Power On/OffsetPowerState(on)on - true power on / false power off
Query Current Operation ModeoperateMode ()automatic/manual
Switch Manual/Auto ModesetOperateMode(mode)mode - automatic/manual
Query Robot Running StatusoperationState()idle/jog/rlProgram/moving etc.
Get Current End/Flange Postureposture(ct)ct - Coordinate type[X,Y,Z,Rx,Ry,Rz]
Get Current End/Flange PosturecartPosture(ct)ct - Coordinate type[X,Y,Z,Rx,Ry,Rz] and axis configuration parameters
Get Current Joint AnglesjointPos()Body in rad; external axes, rails, and additional axes in rad or m
Get Current Joint VelocityjointVel()Body in rad/s; external axes, rails, and additional axes in rad/s or m/s
Get Joint TorquejointTorque()Joint torque Nm
Receive Real-time Status / Read by FieldupdateRobotState(timeout)
getStateData(fieldName, data, …)
In real-time mode; field names see RtSupportedFieldsStatus data
Stop Receiving Real-time StatusstopReceiveRobotState()Used to reconfigure subscription fields
Query Base FramebaseFrame()[X,Y,Z,Rx,Ry,Rz]
Set Base FramesetBaseFrame(frame)frame - Frame
Query Current Tool/Workpiece Settoolset()End frame, reference frame, load info
Set Tool/Workpiece SetsetToolset(toolset)
setToolset(toolName,wobjName)
toolset- Tool/workpiece set info
toolName- Tool name
wobjName- Workpiece name
Calculate Inverse Kinematicsrobot.model().calcIk(posture)
robot.model().calcIk(posture,toolset)
posture - End posture relative to external reference frame
toolset- Tool/workpiece set info
Joint angles
Calculate Forward Kinematicsrobot.model().calcFk(joints)
robot.model().calcFk(joints,toolset)
joints- Joint angles
toolset - Tool/workpiece set info
End posture relative to external reference frame
Calculate All Inverse Kinematics Solutionsrobot.model().calcAllIkSolutions(posture, confs, ec)posture - Flange relative to base coordinate system
confs - Configuration data sets
Multiple sets of joint angles (not supported for xMateSR/XMS)
Clear Servo AlarmclearServoAlarm()
Query Controller LogsqueryControllerLog(count, level[, offset])count - Query count
level - Log level
offset - Offset from latest, default 0
Controller log list
Set Collision Detection Parameters, Enable Collision DetectionCollaborative: enableCollisionDetection(sensitivity,behaviour,fallback_compliance)
Industrial six-axis (StandardRobot): enableCollisionDetection(sensitivity, fallback)
Collaborative: behaviour includes stop1/stop2/compliant stop; fallback_compliance is fallback distance (m) or compliance
Industrial: stop1 only, no behaviour; fallback is fallback distance (m)
Disable Collision DetectiondisableCollisionDetection()
Frame CalibrationcalibrateFrame(type,points, is_held,base_aux)type - Frame type
points - Calibration joint angle list
is_held - Handheld/External tool
base_aux - Base frame calibration auxiliary point
Calibration result: frame and deviation
Get Current Soft Limit ValuesgetSoftLimit(limits)limits - Soft limits per axisEnabled/Disabled
Set Soft LimitssetSoftLimit(enable,limits)enable - Enable/Disable
limits - Soft limits per axis
Recover StaterecoverState(item)item - Recovery option: E-stop recovery
Reboot Industrial ComputerrebootSystem(ec)Reboot is not allowed in auto mode, powered on, moving, or non-idle
Shutdown Industrial ComputershutdownSystem(ec)Shutdown is not allowed in auto mode, powered on, moving, or non-idle. After cabinet power-off, power on again to start the controller software
Connection Status CallbacksetConnectionHandler(handler)handler(bool): true connected / false disconnected
Teach Pendant ModesetTeachPendantMode(enable)Blocks until switching is complete (about 2s order of magnitude)
Read DH ParametersgetRobotCfg_DHparam(get_nominal, ec)get_nominal: true nominal / false optimized or current settingAxes Alpha[°], A[mm], D[mm], Theta[°] in order
Additional Axis / Mechanical UnitgetExtAxisInfo(name, info, value, ec)
getMechUnit(name, info, value, ec)
getExtAxisInfo reads an additional axis, name is axis1 to axis6. getMechUnit reads a mechanical unit, name is u1 to u6Writes to value output parameter
Set Rail ParameterssetRailParameter(name, value)name - Parameter name
value - Parameter value
Read Rail ParametersgetRailParameter(name,value)name - Parameter name
value - Parameter value
Configure NTPconfigNtp(server_ip)server_ip - NTP server IP
Sync Time with NTP ServersyncTimeWithServer()
Query SDK VersionsdkVersion()Version number

Motion Control​

Non-real-time motion control related interfaces.

DescriptionInterfaceParametersReturn
Set Motion Control ModesetMotionControlMode(mode)mode - Idle / NrtCommandMode / NrtRLTask / RtCommandMode
Start/Continue MotionmoveStart()
Motion ResetmoveReset()
Pause Robot Motionstop()
Pause Motion (same as stop)pause(ec)
Add Motion CommandmoveAppend(command,id)command - One or more MoveL/MoveJ/MoveAbsJ/MoveC/MoveCF/MoveSP commands
id - Command ID for execution feedback
Set Default Motion SpeedsetDefaultSpeed(speed)speed - Max end linear velocity
Set Default ZonesetDefaultZone(zone)zone - Zone radius
Set Conf UsagesetDefaultConfOpt(forced) forced - Use/Not use
Set Max Cache SizesetMaxCacheSize(number)number - Allowed range [1, 1000], default 300
Start Jog RobotstartJog(space,rate,step,index, direction)space - Reference frame
rate - Speed
step - Step size
index - XYZABC/J1-7
direction - Direction
Jog (External Axis/Mechanical Unit)startJogWithExt(space, rate, step, index, direction, fixed_name, ec[, is_ext])fixed_name is used with index and is_ext to select a robot axis or a mechanical-unit axis
Adjust Speed OnlineadjustSpeedOnline(scale)scale - Speed ratio
Set Event WatchersetEventWatcher(eventType, callback)eventType - Event type
callback - Event callback
Cancel Event CallbacksetNoneEventWatcher(eventType, ec)eventType - Consistent with setEventWatcher
Auto Cancel ZonesetAutoIgnoreZone(enable, ec)enable - Whether to automatically cancel zone, initially true
Query Event InfoqueryEventInfo(eventType) eventType - Event typeEvent info
Execute Motion CommandexecuteCommand(command)command - One or more MoveL/MoveJ/MoveAbsJ/MoveC/MoveCF/MoveSP commands
Get Current AccelerationgetAcceleration(acc,jerk)acc - Acceleration
jerk - Jerk
Set Motion AccelerationadjustAcceleration(acc,jerk)acc - Acceleration
jerk - Jerk
Enable Singularity AvoidancexMateRobot: setAvoidSingularity(method, enable, limit)
StandardRobot: setAvoidSingularity(method, enable, threshold)
Lock axis 4: industrial 6-axis and xMateCR/SR 6-axis. Sacrifice orientation: all 6-axis. Joint-space interpolation: industrial 6-axis. Third parameter is limit on collaborative robots and threshold on industrial robots
Query Singularity Avoidance StatusgetAvoidSingularity(method)method - Singularity avoidance methodEnabled/Disabled
Check Cartesian Path ReachabilitycheckPath(start,start_joint, target)start - Start point
start_joint - Start joint angles
target - Target point
Calculated target joint angles
DescriptionInterfaceParametersReturn
Query DI SignalgetDI(board,port)board - IO board index
port - Signal port
on
Set DI SignalsetDI(board,port,state)board - IO board index
port - Signal port
state - Signal value
Query DO SignalgetDO(board,port)board - IO board index
port - Signal port
on
Set DO SignalsetDO(board,port,state)board - IO board index
port - Signal port
state - Signal value
Query AI SignalgetAI(board,port)board - IO board index
port - Signal port
Signal value
Set AO SignalsetAO(board,port,value)board - IO board index
port - Signal port
value - Signal value
Set Simulation ModesetSimulationMode(state)state - Enable/Disable
Read RegisterreadRegister(name,index,value)name - Register name
index - Register array index
value - Read value
Write RegisterwriteRegister(name,index,value)name - Register name
index - Register array index
value - Write value
Set xPanel Output ModesetxPanelVout(opt)opt - Mode
Get End Keypad StategetKeypadState()End keypad state
End Tool 485 SwitchsetxPanelRS485(opt, if_rs485, ec)opt - Supply mode: 0 off, 1 reserve, 2 12V, 3 24V
if_rs485 - Whether to enable 485
Init xPanel RS485 ParametersxPanelRS485Init(baud, check_bit, stop_bit, ec)baud - End RS485 baud rate
check_bit - Parity: none / odd / even
stop_bit - Stop bits: 1 or 2
Set xPanel RS485 TimeoutsetxPanelRS485Overtime(overtime_ms, ec)overtime_ms - RS485 timeout (ms), range 50~10000
Init xPanel CAN Baud RatesxPanelCANInit(arbitration_baud, data_baud, ec)arbitration_baud - Arbitration baud rate
data_baud - Data baud rate
485 Read/Write RegistersXPRWModbusRTUReg(slave_addr, fun_cmd, reg_addr, data_type, num, data_array, if_crc_reverse, ec)slave_addr - int, end-device address, 065535
fun_cmd - int, function code: 0x03/04/06/10
reg_addr - int, starting register address, 0
65535
data_type - string: int16/uint16/int32/uint32
num - int, consecutive register count; ignored for 0x06. CR/ER/SR: end firmware less than 301 → 16-bit [1,3], 32-bit 1; ≥301 → 16-bit [1,59], 32-bit [1,29]; AR: 16-bit [1,27], 32-bit [1,13]
data_array - buffer (PyTypeVectorInt); for 0x06 only [0] is used; for 0x10 length must match num
if_crc_reverse - bool, reverse CRC byte order; default False
485 Read/Write CoilsXPRWModbusRTUCoil(slave_addr, fun_cmd, coil_addr, num, data_array, if_crc_reverse, ec)slave_addr - int, end-device address
fun_cmd - int, function code: 0x01/0x02/0x05/0x0F
coil_addr - int, starting coil/discrete-input address
num - int, consecutive count; ignored for 0x05. CR/ER/SR: end firmware less than 301 → [1,48]; ≥301 → [1,944]; AR: [1,432]
data_array - boolean buffer (PyTypeVectorBool); for 0x05 only [0] is used
if_crc_reverse - bool, reverse CRC byte order; default False
485 Raw Data TransmissionXPRS485SendData(send_byte, rev_byte, send_data, rev_data, ec)send_byte - int, bytes to send
rev_byte - int, bytes to receive
send_data - send data; length must equal send_byte
rev_data - receive buffer; length must equal rev_byte
Receive CAN Raw DataCANReceiveData(timeout_ms, data_type, recv_frame, ec)timeout_ms - Receive timeout
data_type - Received data type: int16/uint16/uint8
recv_frame - CANFrame frame info and data
Send CAN Raw DataCANSendData(data_type, send_frames, ec)data_type - CAN frame data type: int16/uint16/uint8
send_frames - list[CANFrame] frames to send
Send and Receive CAN Frames in SequenceCANRwData(param, ec)param - CANRwParam, input request
ec - dict, populated with the error code and message
Returns list[list[list[int]]], received frames by group, each stored as raw bytes

RL Project​

The controller needs to have an RL project created, supporting query of project info and execution.

DescriptionInterfaceParametersReturn
Query RL Project ListprojectsInfo()Project name and task names
Load ProjectloadProject(name,tasks)name-Project name
tasks-Task list
pp-to-mainppToMain()
Start ProjectrunProject()
Pause ProjectpauseProject()
Set Run Rate and Loop ModesetProjectRunningOpt(rate,loop)rate-Run rate
loop-Loop/Single
Query Tool InfotoolsInfo()Tool name, pose, load info
Query Workpiece InfowobjsInfo()Workpiece name, pose, load info
Import RL Project Zip PackageimportProject(file_path, overwrite, ec)file_path - Local .zip path (≤10M)
overwrite - Whether to overwrite same name
Project name (renamed name when automatically renamed)
Delete RL ProjectremoveProject(name, ec[, remove_all])name - Project name
remove_all - Whether to delete all projects, default false
Import File to ControllerimportFile(file_path, dest, overwrite, ec)file_path - Local file path
dest - Controller target path
overwrite - Whether to overwrite
Imported file name
Delete Controller FileremoveFiles(file_path_list, ec)Path list, see method description
Set Tool InformationsetToolInfo(tool_info, ec)tool_info - Tool information
Set Workpiece InformationsetWobjInfo(wobj_info, ec)wobj_info - Workpiece information

Includes drag teaching and path recording functions.

DescriptionInterfaceParametersReturn
Enable DragenableDrag(space,type,enable_drag_button)space: 0 joint space, 1 Cartesian (joint space supports free drag only)
type: 0 translation only, 1 rotation only, 2 free drag
enable_drag_button: true means no need to hold the end button
Disable DragdisableDrag()
Start Record PathstartRecordPath(duration)duration-Record duration
Stop Record PathstopRecordPath()
Cancel RecordcancelRecordPath()
Save PathsaveRecordPath(name,saveAs)name-Path name
saveAs-Rename as
Path ReplayreplayPath(name,rate)name-Path name
rate-Replay rate
Delete Saved PathremovePath(name,removeAll)name-Path name
removeAll - whether to delete all paths, default false
Query Path ListqueryPathLists()Path name list
Force Sensor CalibrationcalibrateForceSensor(all_axes,axis_index)all_axes-Calibrate all axes
axis_index-Single axis index
Real-time Command Network Packet Loss ThresholdsetRtNetworkTolerance(percent, ec)percent - 0~100, corresponding to RobotAssist-RCI "Packet Loss Threshold"; must be set before switching to RtCommandMode
Parallel-base ModeenableCompletePostureLerp(enable, ec)xMateCr5Robot only. enable true to turn on, false to turn off

Force Control Commands​

DescriptionInterfaceParametersReturn
Get Current Torque InfogetEndTorque(ref_type,joint_torque_measured,external_torque_measured,cart_torque,cart_force)ref_type - torque reference frame
joint_torque_measured - measured joint torque
external_torque_measured - external joint torque
cart_torque - Cartesian torque
cart_force - Cartesian force
Force Control InitfcInit(frame_type)frame_type-Force control frame
Start Force ControlfcStart()
Stop Force ControlfcStop()
Set Impedance Control TypesetControlType(type)type-Impedance type
Set Force Control LoadsetLoad(load)load-Load
Set Joint Impedance StiffnesssetJointStiffness(stiffness)stiffness-Stiffness
Set Cartesian Impedance StiffnesssetCartesianStiffness(stiffness)stiffness-Stiffness
Set Cartesian Nullspace Impedance StiffnesssetCartesianNullspaceStiffness(stiffness)stiffness-Stiffness
Set Joint Desired TorquesetJointDesiredTorque(torque)torque-Torque value
Set Cartesian Desired Force/TorquesetCartesianDesiredForce(value)value-Desired force/torque
Set Sine Search MotionsetSineOverlay(line_dir,amplify,frequency,phase,bias)line_dir-Reference axis
amplify-Amplitude
frequency-Frequency
phase-Phase
bias-Bias
Set Lissajous Search MotionsetLissajousOverlay(plane,amplify_one,frequency_one,amplify_two,frequency_two,phase_diff)plane-Reference plane
amplify_one-Amplitude 1
frequency_one-Frequency 1
amplify_two-Amplitude 2
frequency_two-Frequency 2
phase_diff-Phase difference
Start Search MotionstartOverlay()
Stop Search MotionstopOverlay()
Pause Search MotionpauseOverlay()
Restart Paused Search MotionrestartOverlay()
Set Force-related Termination ConditionsetForceCondition(range,isInside,timeout)range-Force limit
isInside-Exceed/Meet limit condition
timeout-Timeout
Set Torque-related Termination ConditionsetTorqueCondition(range,isInside,timeout)range-Torque limit
isInside-Exceed/Meet limit condition
timeout-Timeout
Set Position-related Termination ConditionsetPoseBoxCondition(supervising_frame,box,isInside,timeout)supervising_frame-Reference frame of box
box-Box
isInside-Exceed/Meet limit condition
timeout-Timeout
Activate Termination Conditions and WaitwaitCondition()
Start/Stop Force Control Protection MonitorfcMonitor(enable)enable-Enable/Disable
Set Joint Max Velocity in Force Control ModesetJointMaxVel(velocity)velocity-Joint velocity
Set Cartesian Max Velocity in Force Control ModesetCartesianMaxVel(velocity)velocity-End velocity
Set Joint Max Momentum in Force Control ModesetJointMaxMomentum(momentum)momentum-Momentum
Set Joint Max Energy in Force Control ModesetJointMaxEnergy(energy)energy-Energy
Release Force-control Objectreset()No docstring on the bind
Per-axis Force-control BandwidthsetFcGain(gain, ec)Range [0, 60], default 20
Friction CompensationsetFriction(fric, ec)Range [0, 1], default 0.9
Impedance Joint Velocity LimitsetJointControlMaxVel(max_joint_vel, ec)rad/s, range [0, 10]
Impedance Joint Force LimitsetJointControlMaxTorque(max_torque, ec)Nm, range [0, 1000]
Impedance Cartesian Velocity LimitsetCartesianControlMaxVel(max_cart_vel, ec)XYZ [0, 3] m/s, ABC [0, 10] rad/s
Impedance Cartesian Force LimitsetCartesianControlMaxWrench(max_wrench, ec)XYZ in N, ABC in Nm, range [0, 1000]

Real-time Control​

Collaborative robots get motioncontrolRT.PyRTmotioncontrol5/6/7 from getRtMotionController(). Industrial robots do not have this call. State reception is on the robot object.

DescriptionInterfaceParametersReturn
Start Receiving Real-time StatestartReceiveRobotState(interval, fields)Interval 1ms/2ms/4ms/8ms/1s; fields at most 1024 bytes
Create Real-time ControllergetRtMotionController()Collaborative robots onlyController object
Send Real-time CommandsendCommand(cmd)JointPosition / CartesianPosition / Torque
Prepare MotionstartMove(rtMode)Motion starts after a command is sent
Stop MotionstopMove()

Periodic callbacks, impedance, filters, collision thresholds, and the deprecated MoveJ / MoveL / MoveC are in method appendix section 7.

Model​

Model_* in the model submodule provides the existing inverse and forward kinematics. With CMake option XMATE_MODEL (off by default), collaborative model() returns xmateModel_1_5/6/7, which also has setLoad(mass, cog, inertia), setTcpCoor, getCartPose / getCartVel / getCartAcc, getJointPos / getJointVel / getJointAcc, jacobian, and getTorqueNoFriction. Links use SegmentFrame. See method appendix section 8.

utility​

xCoreSDK_python.utility: degrees and radians, homogeneous matrices and poses, Euler angles and quaternions, and Toolset / flange / end frame conversion. See method appendix section 9.

planner​

xCoreSDK_python.planner: CartMotionGenerator and JointMotionGenerator (7 axes). FollowPosition_5/6/7 is bound only when XMATE_MODEL is on, same as xmateModel. See method appendix section 10.