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 Name | Applicable Models |
|---|---|
| xMateRobot | Collaborative 6-axis |
| xMateErProRobot | Collaborative 7-axis |
| StandardRobot | Industrial 6-axis |
| xMateCr5Robot | Collaborative CR5-axis |
| PCB4Robot | Industrial 4-axis |
| PCB3Robot | Industrial 3-axis |
Robot Basic Operations and Information Query
| Description | Interface | Parameters | Return |
|---|---|---|---|
| Connect to Robot | connectToRobot() | ||
| Connect to Robot | connectToRobot(remoteIP,localIP) | remoteIP - Robot IP address localIP - Local address. Used for real-time mode data transmission | |
| Disconnect | disconnectFromRobot() | ||
| Query Robot Basic Info | robotInfo() | Controller version, model, number of axes, MAC, etc. | |
| Robot Power On/Off and E-Stop Status | powerState() | on/off/Estop/Gstop | |
| Robot Power On/Off | setPowerState(state) | state - on/off | |
| Query Current Operation Mode | operateMode () | auto/manual | |
| Switch Manual/Auto Mode | setOperateMode(mode) | mode - auto/manual | |
| Query Robot Running Status | operationState() | idle/jog/RLprogram/moving etc. | |
| Get Current End/Flange Posture | posture(ct) | ct - Coordinate type | [X,Y,Z,Rx,Ry,Rz] |
| Get Current End/Flange Posture | cartPosture(ct) | ct - Coordinate type | [X,Y,Z,Rx,Ry,Rz] and axis configuration parameters |
| Get Current Joint Angles | jointPos() | Joint angles rad | |
| Get Current Joint Velocity | jointVel() | Joint velocity rad/s | |
| Get Joint Torque | jointTorque() | Joint torque Nm | |
| Receive Real-time Status / Read by Field | updateRobotState(timeout)getStateData(fieldName, data, …) | In real-time mode; field names see RtSupportedFields | Status data |
| Stop Receiving Real-time Status | stopReceiveRobotState() | Used to reconfigure subscription fields | |
| Query Base Frame | baseFrame() | [X,Y,Z,Rx,Ry,Rz] | |
| Set Base Frame | setBaseFrame(frame) | frame - Frame | |
| Query Current Tool/Workpiece Set | toolset() | End frame, reference frame, load info | |
| Set Tool/Workpiece Set | setToolset(toolset)setToolset(toolName,wobjName) | toolset- Tool/workpiece set info toolName- Tool name wobjName- Workpiece name | |
| Calculate Inverse Kinematics | robot.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 Kinematics | robot.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 Solutions | robot.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 Alarm | clearServoAlarm() | ||
| Query Controller Logs | queryControllerLog(count, level[, offset]) | count - Query count level - Log level offset - Offset from latest, default 0 | Controller log list |
| Set Collision Detection Parameters, Enable Collision Detection | Collaborative: enableCollisionDetection(sensitivity,behaviour,fallback)Industrial six-axis ( StandardRobot): enableCollisionDetection(sensitivity, fallback) | Collaborative: behaviour includes stop1/stop2/compliant, etc.Industrial: only stop1, no behaviour parameter fallback - Fallback distance or compliance | |
| Disable Collision Detection | disableCollisionDetection() | ||
| Frame Calibration | calibrateFrame(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 Values | getSoftLimit(limits) | limits - Soft limits per axis | Enabled/Disabled |
| Set Soft Limits | setSoftLimit(enable,limits) | enable - Enable/Disable limits - Soft limits per axis | |
| Recover State | recoverState(item) | item - Recovery option: E-stop recovery | |
| Reboot Industrial Computer | rebootSystem(ec) | Not allowed in auto mode/power off/moving/non-idle state | |
| Shutdown Industrial Computer | shutdownSystem(ec) | Controller needs to be powered on again after shutdown | |
| Connection Status Callback | setConnectionHandler(handler) | handler(bool): true connected / false disconnected | |
| Teach Pendant Mode | setTeachPendantMode(enable) | Blocks until switching is complete (about 2s order of magnitude) | |
| Read DH Parameters | getRobotCfg_DHparam(get_nominal, ec) | get_nominal: true nominal / false optimized or current setting | Axes Alpha[°], A[mm], D[mm], Theta[°] in order |
| Mechanical Unit / External Axis Information | getExtAxisInfo(name, info, value, ec)getMechUnit(name, info, value, ec) | name: axis1～axis6 or u1～u6; info is field name string | Writes to value output parameter |
| Set Rail Parameters | setRailParameter(name, value) | name - Parameter name value - Parameter value | |
| Read Rail Parameters | getRailParameter(name,value) | name - Parameter name value - Parameter value | |
| Configure NTP | configNtp(server_ip) | server_ip - NTP server IP | |
| Sync Time with NTP Server | syncTimeWithServer() | ||
| Query SDK Version | sdkVersion() | Version number |
Motion Control
Non-real-time motion control related interfaces.
| Description | Interface | Parameters | Return |
|---|---|---|---|
| Set Motion Control Mode | setMotionControlMode(mode) | mode - Idle / NrtCommandMode / NrtRLTask / RtCommandMode | |
| Start/Continue Motion | moveStart() | ||
| Motion Reset | moveReset() | ||
| Pause Robot Motion | stop() | ||
| Pause Motion (same as stop) | pause(ec) | ||
| Add Motion Command | moveAppend(command,id) | command - One or more MoveL/MoveJ/MoveAbsJ/MoveC/MoveCF/MoveSP commands id - Command ID for execution feedback | |
| Set Default Motion Speed | setDefaultSpeed(speed) | speed - Max end linear velocity | |
| Set Default Zone | setDefaultZone(zone) | zone - Zone radius | |
| Set Conf Usage | setDefaultConfOpt(forced) | forced - Use/Not use | |
| Set Max Cache Size | setMaxCacheSize(number) | number - Allowed range [1, 1000], default 300 | |
| Start Jog Robot | startJog(space,rate,step,index, direction) | space - Reference framerate - 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配合index、is_ext指定本体轴或机械单元轴 | |
| Adjust Speed Online | adjustSpeedOnline(scale) | scale - Speed ratio | |
| Set Event Watcher | setEventWatcher(eventType, callback) | eventType - Event type callback - Event callback | |
| Cancel Event Callback | setNoneEventWatcher(eventType, ec) | eventType - Consistent with setEventWatcher | |
| Auto Cancel Zone | setAutoIgnoreZone(enable, ec) | enable - Whether to automatically cancel zone, initially true | |
| Query Event Info | queryEventInfo(eventType) | eventType - Event type | Event info |
| Execute Motion Command | executeCommand(command) | command - One or more MoveL/MoveJ/MoveAbsJ/MoveC/MoveCF/MoveSP commands | |
| Get Current Acceleration | getAcceleration(acc,jerk) | acc - Acceleration jerk - Jerk | |
| Set Motion Acceleration | adjustAcceleration(acc,jerk) | acc - Acceleration jerk - Jerk | |
| Enable Singularity Avoidance | setAvoidSingularity(method, enable,threshold) | method - Singularity avoidance method enable - Enable/Disable threshold - Threshold parameter | |
| Query Singularity Avoidance Status | getAvoidSingularity(method) | method - Singularity avoidance method | Enabled/Disabled |
| Check Cartesian Path Reachability | checkPath(start,start_joint, target) | start - Start point start_joint - Start joint angles target - Target point | Calculated target joint angles |
Communication Related
| Description | Interface | Parameters | Return |
|---|---|---|---|
| Query DI Signal | getDI(board,port) | board - IO board index port - Signal port | on |
| Set DI Signal | setDI(board,port,state) | board - IO board index port - Signal port state - Signal value | |
| Query DO Signal | getDO(board,port) | board - IO board index port - Signal port | on |
| Set DO Signal | setDO(board,port,state) | board - IO board index port - Signal port state - Signal value | |
| Query AI Signal | getAI(board,port) | board - IO board index port - Signal port | Signal value |
| Set AO Signal | setAO(board,port,value) | board - IO board index port - Signal port value - Signal value | |
| Set Simulation Mode | setSimulationMode(state) | state - Enable/Disable | |
| Read Register | readRegister(name,index,value) | name - Register name index - Register array index value - Read value | |
| Write Register | writeRegister(name,index,value) | name - Register name index - Register array index value - Write value | |
| Set xPanel Output Mode | setxPanelVout(opt) | opt - Mode | |
| Get End Keypad State | getKeypadState() | End keypad state | |
| End Tool 485 Communication Switch | setxPanelRS485(Vopt,if_rs485) | Vopt - Output voltage if_rs485 - Enable 485 communication | |
| 485 Communication Read/Write Registers | XPRWModbusRTUReg(slave_addr,fun_cmd, reg_addr data_type,num,data_array,if_crc_reverse) | slave_addr - Slave address fun_cmd - Function code reg_addr - Register address data_type - Data type num - Data length data_array - Data array if_crc_reverse - CRC reverse | |
| 485 Communication Read/Write Coils or Discrete Inputs | XPRWModbusRTUCoil(slave_addr,fun_cmd, coil_addr,int num,data_array,if_crc_reverse) | slave_addr - Slave address fun_cmd - Function code coil_addr - Coil address num - Data length data_array - Data array if_crc_reverse - CRC reverse | |
| 485 Raw Data Transmission | XPRS485SendData(send_byte,rev_byte,send_data,rev_data,) | send_byte - Send length rev_byte - Receive length send_data - Send data rev_data - Receive data |
RL Project
The controller needs to have an RL project created, supporting query of project info and execution.
| Description | Interface | Parameters | Return |
|---|---|---|---|
| Query RL Project List | projectsInfo() | Project name and task names | |
| Load Project | loadProject(name,tasks) | name-Project name tasks-Task list | |
| pp-to-main | ppToMain() | ||
| Start Project | runProject() | ||
| Pause Project | pauseProject() | ||
| Set Run Rate and Loop Mode | setProjectRunningOpt(rate,loop) | rate-Run rate loop-Loop/Single | |
| Query Tool Info | toolsInfo() | Tool name, pose, load info | |
| Query Workpiece Info | wobjsInfo() | Workpiece name, pose, load info | |
| Import RL Project Zip Package | importProject(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 Project | removeProject(name, ec[, remove_all]) | name - Project nameremove_all - Whether to delete all projects, default false | |
| Import File to Controller | importFile(file_path, dest, overwrite, ec) | file_path - Local file pathdest - Controller target pathoverwrite - Whether to overwrite | Imported file name |
| Delete Controller File | removeFiles(file_path_list, ec) | Path list, see method description | |
| Set Tool Information | setToolInfo(tool_info, ec) | tool_info - Tool information | |
| Set Workpiece Information | setWobjInfo(wobj_info, ec) | wobj_info - Workpiece information |
Collaboration Related
Includes drag teaching and path recording functions.
| Description | Interface | Parameters | Return |
|---|---|---|---|
| Enable Drag | enableDrag(space,type,enable_drag_button) | space-Drag space type-Drag type enable_drag_button-No button drag | |
| Disable Drag | disableDrag() | ||
| Start Record Path | startRecordPath(duration) | duration-Record duration | |
| Stop Record Path | stopRecordPath() | ||
| Cancel Record | cancelRecordPath() | ||
| Save Path | saveRecordPath(name,saveAs) | name-Path name saveAs-Rename as | |
| Path Replay | replayPath(name,rate) | name-Path name rate-Replay rate | |
| Delete Saved Path | removePath(name,all) | name-Path name all -Delete all paths | |
| Query Path List | queryPathLists() | Path name list | |
| Force Sensor Calibration | calibrateForceSensor(all_axes,axis_index) | all_axes-Calibrate all axes axis_index-Single axis index | |
| Real-time Command Network Packet Loss Threshold | setRtNetworkTolerance(percent, ec) | percent - 0～100, corresponding to RobotAssist-RCI "Packet Loss Threshold"; must be set before switching to RtCommandMode |
Force Control Commands
| Description | Interface | Parameters | Return |
|---|---|---|---|
| Get Current Torque Info | getEndTorque(ref_type,joint,external,cart_torque,cart_force) | ref _type -Torque reference frame joint-Joint measurements external-External forces cart_torque-Cartesian torque cart_force-Cartesian force | |
| Force Control Init | fcInit(frame_type) | frame_type-Force control frame | |
| Start Force Control | fcStart() | ||
| Stop Force Control | fcStop() | ||
| Set Impedance Control Type | setControlType(type) | type-Impedance type | |
| Set Force Control Load | setLoad(load) | load-Load | |
| Set Joint Impedance Stiffness | setJointStiffness(stiffness) | stiffness-Stiffness | |
| Set Cartesian Impedance Stiffness | setCartesianStiffness(stiffness) | stiffness-Stiffness | |
| Set Cartesian Nullspace Impedance Stiffness | setCartesianNullspaceStiffness(stiffness) | stiffness-Stiffness | |
| Set Joint Desired Torque | setJointDesiredTorque(torque) | torque-Torque value | |
| Set Cartesian Desired Force/Torque | setCartesianDesiredForce(value) | value-Desired force/torque | |
| Set Sine Search Motion | setSineOverlay(line_dir,amplify,frequency,phase,bias) | line_dir-Reference axis amplify-Amplitude frequency-Frequency phase-Phase bias-Bias | |
| Set Lissajous Search Motion | setLissajousOverlay(plane,amplify_one,frequency_one,amplify_two,frequency_two,phase_diff,error_code &ec) | 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 Motion | startOverlay() | ||
| Stop Search Motion | stopOverlay() | ||
| Pause Search Motion | pauseOverlay() | ||
| Restart Paused Search Motion | restartOverlay() | ||
| Set Force-related Termination Condition | setForceCondition(range,isInside,timeout) | range-Force limit isInside-Exceed/Meet limit condition timeout-Timeout | |
| Set Torque-related Termination Condition | setTorqueCondition(range,isInside,timeout) | range-Torque limit isInside-Exceed/Meet limit condition timeout-Timeout | |
| Set Position-related Termination Condition | setPoseBoxCondition(supervising_frame,box,isInside,timeout) | supervising_frame-Reference frame of box box-Box isInside-Exceed/Meet limit condition timeout-Timeout | |
| Activate Termination Conditions and Wait | waitCondition() | ||
| Start/Stop Force Control Protection Monitor | fcMonitor(enable) | enable-Enable/Disable | |
| Set Joint Max Velocity in Force Control Mode | setJointMaxVel(velocity) | velocity-Joint velocity | |
| Set Cartesian Max Velocity in Force Control Mode | setCartesianMaxVel(velocity) | velocity-End velocity | |
| Set Joint Max Momentum in Force Control Mode | setJointMaxMomentum(momentum) | momentum-Momentum | |
| Set Joint Max Energy in Force Control Mode | setJointMaxEnergy(energy) | energy-Energy |