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.
C#: Instantiate rokae::Robot Class
Depending on the robot configuration and number of axes, the C# 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 (xMateCR7/12, xMateSR3/4, xMateER3/7, etc.) |
| xMateErProRobot | Collaborative 7-axis (xMateER3 Pro / xMateER7 Pro) |
| StandardRobot | Industrial 6-axis |
| xMateCr5Robot | Collaborative 5-axis (XMC17_5 / XMC25_5) |
| PCB4Robot | Industrial 4-axis |
| PCB3Robot | Industrial 3-axis |
Robot Basic Operations and Information Query
| Description | Interface | Parameters | Return |
|---|---|---|---|
| Connect to Robot | connectToRobot(ec) | [out] ec - Error code; address passed when constructing the instance | |
| Connect to Robot | connectToRobot(remoteIP) | remoteIP - Robot IP | |
| Connect to Robot | connectToRobot(remoteIP, localIP) | localIP - Local address. Used for real-time interaction; not supported by PCB3/4 axis models | |
| Disconnect | disconnectFromRobot() | ||
| Set connection disconnection callback function | setConnectionHandler(handler) | handler - Callback function | |
| Query Robot Basic Info | robotInfo() | Controller version, model, number of axes | |
| Robot Power On/Off and E-Stop Status | powerState() | on/off/Estop/Gstop | |
| Robot Power On/Off | setPowerState(on) | on - true power on / false power 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 system type | [X,Y,Z,Rx,Ry,Rz] |
| Get Current End/Flange Posture | cartPosture(ct) | ct - Coordinate system 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 | |
| Query Multiple States | getStateList() | Current position, IO signals, operation mode, speed override value | |
| 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 | calcIk(posture)calcIk(posture, toolset) | posture - CartesianPosition^, end relative to external reference frame toolset - Optional tool/workpiece set | Joint angles [rad] |
| Calculate Forward Kinematics | calcFk(joints)calcFk(joints, toolset) | joints - Joint angles [rad] toolset - Optional | CartesianPosition^ |
| Clear Servo Alarm | clearServoAlarm() | ||
| Query Controller Logs | queryControllerLog(count,level) | count - Query count level - Log level | Controller log list |
| Set Collision Detection (Collaborative) | enableCollisionDetection(sensitivity, behaviour, fallback_compliance) | sensitivity - Sensitivity 0.01~2.0 behaviour - stop1/stop2/suppleStop fallback_compliance - fallback distance[m] or compliance[0,1] | |
| Set Collision Detection (Industrial) | enableCollisionDetection(sensitivity, fallback) | Only stop1 (safety stop); fallback - fallback distance[m] | |
| Disable Collision Detection | disableCollisionDetection() | ||
| Frame Calibration | calibrateFrame(type, points, is_held, base_aux) | type - tool / wobj / base / rail (three-point for rail base frame) points - Joint angle list[rad] is_held - Robot held/external (tool, workpiece) base_aux - Base frame calibration auxiliary point[m] | Calibration result and deviation; if successful, controller saves, takes effect after restart |
| Get Current Soft Limit Values | getSoftLimit(limits) | limits - Soft limits per axis | Enabled/Disabled |
| Set Soft Limit | setSoftLimit(enable,limits) | enable - Enable/Disable limits - Soft limits per axis | |
| Recover State | recoverState(item) | item - Recovery option: E-stop recovery | |
| Read Rail Parameters | getRailParameter(name, value) | Overload: enable/name/baseFrame/numeric (reductionRatio, maxSpeed, encoderResolution, etc.)/softLimit and range arrays | |
| Set Rail Parameters | setRailParameter(name, value) | Overload: Frame (baseFrame), String (name), double, bool (enable), array<double> (softLimit/range), int (encoderResolution, motorSpeed) | |
| Configure NTP | configNtp(server_ip) | server_ip - NTP server IP | |
| Manual Sync NTP Time | syncTimeWithServer() | ||
| Query SDK Version | sdkVersion() | Version number | |
| Receive One Robot State | updateRobotState(timeout_ms) | timeout_ms - Timeout[ms] | Data length of this frame; returns 0 on timeout |
| Read Robot State Data | getStateData(name, data) | name - See startReceiveRobotState and header file description; data - array<double>, etc., type must match | Success 0, failure -1 |
| Read Timestamp | getStateData("ts", data) | data - UInt64%, microsecond timestamp | Same as above |
| Read Elbow Angle | getStateData("psi_m", data) | data - double% | Same as above |
| Start Sending Real-time State | startReceiveRobotState(interval, fields) | interval - 1/2/4/8 ms or 1 s; fields - Field name array, total length ≤1024 bytes | Blocks until first frame or timeout |
| Stop Real-time State | stopReceiveRobotState() | ||
| Reboot Industrial Computer | rebootSystem(ec) | ||
| Shutdown Industrial Computer | shutdownSystem(ec) | Controller software can only be started after powering off and on the control cabinet | |
| Teach Pendant Hot Swap | setTeachPendantMode(enable) | enable - Use/don't use teach pendant | |
| Read DH Parameters | getRobotCfg_DHparam(get_nominal) | get_nominal - false: optimized/set; true: nominal parameters | Alpha[°], A[mm], D[mm], Theta[°] per axis |
| Calculate All Inverse Kinematics Solutions | calcAllIkSolutions(posture, confs) | posture - Flange relative to base frame; confs - Output confdata | Inverse kinematics array; not supported for xMateSR(XMS) |
| Read Mechanical Unit Parameters | getMechUnit(name, info, value) | name - u1~u6; info - Parameter name; value - bool/int/string array (overload) | |
| Read External Axis Parameters | getExtAxisInfo(name, info, value) | name - axis1~axis6; info - Parameter name; value - bool/int/double/String/string array (overload) |
Motion Control
Non-real-time motion control related interfaces.
| Description | Interface | Parameters | Return |
|---|---|---|---|
| Set Motion Control Mode | setMotionControlMode(mode) | mode - Idle / NrtCommand / NrtRLTask / RtCommand (non-real-time command, non-real-time RL, real-time) | |
| Start/Continue Motion | moveStart() | ||
| Motion Reset | moveReset() | ||
| Pause Robot Motion | stop() | ||
| Add Motion Command | moveAppend(type, cmd, cmdId)moveAppend(type, cmdList, cmdId) | type - MoveCommand::Type, consistent with batch commands cmd / cmdList - Single or 1-100 commands of the same type cmdId - Command ID for execution feedback | |
| Set Default Motion Speed | setDefaultSpeed(speed) | speed - Maximum end linear speed | |
| Set Default Zone | setDefaultZone(zone) | zone - Zone radius | |
| Set Whether to Use conf | setDefaultConfOpt(forced) | forced - Use/don't use | |
| Set Whether to Automatically Cancel Zone | setAutoIgnoreZone(enable) | enable - Auto cancel zone / don't auto cancel | |
| Set Max Cache Command Count | setMaxCacheSize(number) | number - Count | |
| Start Jog Robot | startJog(space,rate,step,index, direction) | space - Reference framerate - Rate step - Step index - XYZABC/J1-7 direction - Direction | |
| Dynamically Adjust Robot Motion Rate | adjustSpeedOnline(scale) | scale - Rate | |
| Set Callback Function for Event Reception | setEventWatcher(eventType, callback) | eventType - moveExecution / safety / rlExecution / logReporter callback - Callback (moveExecution same thread, don't block; safety separate thread) | |
| Query Event Info | queryEventInfo(eventType) | eventType - Event type | Event info |
| Execute Motion Command | executeCommand(type, cmd) | type - MoveCommand::Type cmd - 1-100 commands of the same type, starts moving immediately after calling | |
| Read Current Acceleration | getAcceleration(acc,jerk) | acc - Acceleration jerk - Jerk | |
| Set Motion Acceleration | adjustAcceleration(acc,jerk) | acc - Acceleration jerk - Jerk | |
| Enable Singularity Avoidance (Industrial Robot) | setAvoidSingularity(method, enable, limit) | method - 4-axis lock/sacrifice posture/axis space interpolation (collaborative 6-axis no axis space interpolation) enable - Enable/disable limit - For sacrifice posture: posture error[rad]; for axis space interpolation: avoidance radius[m] | |
| Query Whether Singularity Avoidance is Enabled | getAvoidSingularity(method) | method - Singularity avoidance method | Enabled/Disabled |
| Check Linear Path Reachability | checkPath(start, start_joint, target) | Supports rail; start/target are Cartesian points | Target joint angles |
| Check Multiple Linear Segments | checkPath(start_joint, targets, target_joint_calculated) | targets at least 2 points, first point is start | Returns error point index when failed |
| Check Arc Reachability | checkPath(start, start_joint, aux, target) | aux - Auxiliary point | Target joint angles |
| Check Full Circle Reachability | checkPath(start, start_joint, aux1, aux2, angle, rot_type) | angle - Full circle radians; rot_type - Rotation type | Target joint angles |
Communication Related
| Description | Interface | Parameters | Return value |
|---|---|---|---|
| Query DI Signal | getDI(board,port) | board - IO board number port - Signal port number | on |
| Set DI Signal | setDI(board,port,state) | board - IO board number port - Signal port number state - Signal value | |
| Query DO Signal | getDO(board,port) | board - IO board number port - Signal port number | on |
| Set DO Signal | setDO(board,port,state) | board - IO board number port - Signal port number state - Signal value | |
| Query AI Signal | getAI(board,port) | board - IO board number port - Signal port number | Signal value |
| Set AO Signal | setAO(board,port,value) | board - IO board number port - Signal port number value - Signal value | |
| Set Input Simulation Mode | setSimulationMode(state) | state - Enable/disable | |
| Read Register Value | readRegister(name,index,value) | name - Register name index - Register array index value - Read value | |
| Write Register Value | writeRegister(name,index,value) | name - Register name index - Register array index value - Write value | |
| Set xPanel External Power Supply 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 - Whether to enable 485 communication | |
| 485 Communication Read/Write Registers | XPRWModbusRTUReg(...) | slave_addr; fun_cmd (0x03/04/06/10); reg_addr; data_type (int32/int16/uint32/uint16); num; array<int>^% data_array; if_crc_reverse | |
| 485 Communication Read/Write Coils or Discrete Inputs | XPRWModbusRTUCoil(...) | fun_cmd 0x01/02/05/0F; array<bool>^% data_array; others same as registers | |
| 485 Communication Raw Data Transmission | XPRS485SendData(send_byte, rev_byte, send_data, recv_data) | Send/receive length 0~16 each; recv_data is output |
RL Project
The controller needs to have an RL project created, supporting query of project info and execution.
| Description | Interface | Parameters | Return value |
|---|---|---|---|
| Query RL Project List | projectsInfo() | Project names and task names | |
| Load Project | loadProject(name,tasks) | name-Project name tasks-Task list | |
| pp-to-main | ppToMain() | ||
| Start Running Project | runProject() | ||
| Pause Running Project | pauseProject() | ||
| Set Running Rate and Loop Mode | setProjectRunningOpt(rate, loop) | rate-Running rate loop-Loop/Single | |
| Set Global Tool Info | setToolInfo(tool_info) | tool_info-Tool info | |
| Set Global Workpiece Info | setWobjInfo(wobj_info) | wobj_info-Workpiece info | |
| Query Tool Info | toolsInfo() | Tool names, poses, loads, etc. | |
| Query Workpiece Info | wobjsInfo() | Workpiece names, poses, loads, etc. | |
| Import Local File to Controller | importFile(src_file_path, dest, bool overwrite) | src_file_path-Local file pathdest-Target pathoverwrite-Overwrite same name file | Imported file name |
| Delete Files in Controller | removeFiles(file_path_list) | File path list | |
| Import Local RL Project Zip to Controller | importProject(file_path, bool overwrite) | file_path-Local .zip pathoverwrite-Whether to overwrite same name file | Project name |
| Delete RL Project in Controller | removeProject(project_name, remove_all) | project_name-Project nameremove_all-Whether to delete all projects |
Collaboration Related
Includes drag teaching and path recording functions.
| Description | Interface | Parameters | Return value |
|---|---|---|---|
| Enable Drag | enableDrag(space,type, enable_drag_button) | space-Drag space type-Drag type enable_drag_button-No button drag | |
| Disable Drag | disableDrag() | ||
| Start Recording Path | startRecordPath() | Duration must be within 30 minutes; non-blocking, call stopRecordPath() to end | |
| Stop Recording Path | stopRecordPath() | ||
| Cancel Recording | 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 -Whether to 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 calibration index |
xMate Five-axis (xMateCr5Robot)
| Description | Interface | Parameters | Return value |
|---|---|---|---|
| Parallel Base Mode | enableCompletePostureLerp(enable) | enable - true enable / false disable |
Force Control Commands
| Description | Interface | Parameters | Return value |
|---|---|---|---|
| Force Control Command Class | forceControl() | ForceControl | |
| Get Current Torque Info | getEndTorque(ref_type, joint_torque_measured, external_torque_measured, cart_torque, cart_force) | ref_type - world / flange / tool Others are output: joint measured torque, joint external torque, Cartesian torque, Cartesian force | |
| Force Control Initialization | fcInit(frame_type) | world / wobj / tool / baseFrame / flange | |
| Start Force Control | fcStart() | After fcInit; commands added with moveAppend but not moveStart will execute after force control starts | |
| Stop Force Control | fcStop() | ||
| Set Impedance Control Type | setControlType(type) | 0 - Joint impedance; 1 - Cartesian impedance | |
| Set Load Used by Force Control Module | setLoad(load) | Can be called after fcStart | |
| Set Joint Impedance Stiffness | setJointStiffness(stiffness) | Takes effect after fcInit | |
| Set Cartesian Impedance Stiffness | setCartesianStiffness(stiffness) | XYZ force stiffness [N/m] + ABC torque stiffness [Nm/rad] | |
| Set Cartesian Nullspace Impedance Stiffness | setCartesianNullspaceStiffness(stiffness) | [0,4] Nm/rad | |
| Set Joint Desired Torque | setJointDesiredTorque(torque) | [-30,30] Nm | |
| Set Cartesian Desired Force/Torque | setCartesianDesiredForce(value) | XYZ force [-60,60] N; ABC torque [-10,10] Nm | |
| Set Sine Search Motion | setSineOverlay(line_dir, amplify, frequency, phase, bias) | Must first setControlType(1); 0/1/2 for X/Y/Z axis | |
| Set Lissajous Search Motion | setLissajousOverlay(plane, amplify_one, frequency_one, amplify_two, frequency_two, phase_diff) | Must first setControlType(1); plane 0/1/2 for XY/XZ/YZ | |
| Start Search Motion | startOverlay() | After fcStart | |
| Stop Search Motion | stopOverlay() | ||
| Pause Search Motion | pauseOverlay() | ||
| Restart Paused Search Motion | restartOverlay() | ||
| Set Termination Condition Related to Contact Force | setForceCondition(range, isInside, timeout) | range - Six-axis force limit[N]; isInside - true stop when exceeded, false stop when met; timeout [1,600] s | |
| Set Termination Condition Related to Contact Torque | setTorqueCondition(range, isInside, timeout) | Same as above, unit Nm | |
| Set Termination Condition Related to Contact Position | setPoseBoxCondition(supervising_frame, box, isInside, timeout) | Reference frame relative to external workpiece; box six elements [m]; isInside same meaning as force condition | |
| Activate Termination Condition and Wait | waitCondition() | ||
| Start/Stop Force Control Protection Monitoring | fcMonitor(enable) | Threshold takes effect after fcMonitor(true), restores default protection after false | |
| Force Control Axis Maximum Speed | setJointMaxVel(velocity) | [rad/s] | |
| End Relative to Base Maximum Speed | setCartesianMaxVel(velocity) | XYZ [m/s], ABC [rad/s] | |
| Force Control Axis Maximum Momentum | setJointMaxMomentum(momentum) | N·s | |
| Force Control Axis Maximum Kinetic Energy | setJointMaxEnergy(energy) | N·rad/s | |
| Cartesian Impedance Force Limit | setCartesianControlMaxWrench(max_wrench) | XYZ[N], ABC[Nm], [0,1000], valid from fcStart to fcStop | |
| Cartesian Impedance Contact Speed Limit | setCartesianControlMaxVel(max_cart_vel) | XYZ [0,3] m/s; ABC [0,10] rad/s | |
| Joint Impedance Torque Limit | setJointControlMaxTorque(max_torque) | Nm, [0,1000] | |
| Joint Impedance Speed Limit | setJointControlMaxVel(max_joint_vel) | rad/s, [0,10] | |
| Force Control Bandwidth | setFcGain(gain) | Each axis [0,60], default 20 | |
| Friction Compensation | setFriction(fric) | Each axis [0,1], default 0.9 |