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
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()`
Set Connection Handler Callback	`setConnectionHandler(handler)`	`handler`- Callback function, parameter is bool, true-connected false-disconnected
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(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.
Reboot IPC	`rebootSystem()`
Shutdown IPC	`shutdownSystem()`
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
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
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` - End posture relative to external reference frame `toolset`- Tool/workpiece set info	`Joint angles`
Calculate Forward Kinematics	`calcFk(joints)` `calcFk(joints,toolset)`	`joints`- Joint angles `toolset` - Tool/workpiece set info	End posture relative to external reference frame
Calculate All IK Solutions for Cartesian Posture	`calcAllIkSolutions(posture, confs)`	`posture`- Cartesian posture, flange relative to base frame. Other frames need conversion `confs` - Corresponding confdata, valid when error code is 0	IK result, unit radians
Clear Servo Alarm	`clearServoAlarm()`
Query Controller Logs	`queryControllerLog(count,level)`	`count` - Query count `level` - Log level `offset`- Offset, e.g., 0 means query from latest log, 10 means from 11th	Controller log list
Set Collision Detection Parameters, Enable Collision Detection	`enableCollisionDetection(sensitivity,behaviour,fallback)`	`sensitivity` - Sensitivity `behaviour`- Post-collision behavior `fallback`- Fallback distance/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
Set Rail Parameters	`setRailParameter(name, value)`	`name` - Parameter name `value` - Parameter value
Read Rail Parameters	`getRailParameter(name,value)`	`name` - Parameter name `value` - Parameter value
Read Mechanical Unit Parameters	`getMechUnit(name,info,value)`	`R` - Parameter type `name` Parameter name, u1~u6 `info` Parameter name, see value description
Read Axis Unit Parameters	`getExtAxisInfo(name,info,value)`	`R` - Parameter type `name` Parameter name, axis1~axis6 `info` Parameter name, see value description
Configure NTP	`configNtp(server_ip)`	`server_ip` - NTP server IP
Sync Time with NTP Server	`syncTimeWithServer0`
Query SDK Version	`sdkVersion()`		Version number

Motion Control

Non-real-time motion control related interfaces.

Description	Interface	Parameters	Return
Set Motion Control Mode	`setMotionControlMode(mmode)`	`mode` - NRT/RT/RL project
Start/Continue Motion	`moveStart()`
Motion Reset	`moveReset()`
Pause Robot Motion	`stop()`
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 Auto Ignore Zone	`setAutoIgnoreZone(enable)`	`enable`- Auto ignore
Set Max Cache Size	`setMaxCacheSize(number)`	`number` - Count
Start Jog Robot	`startJog(space,rate,step,index, direction)`	`space` - Reference frame `rate` - Speed `step` - Step size `index` - XYZABC/J1-7 `direction` - Direction
Start Jog Robot+External Axis	`startJogWithExt(space, step,index, direction, fixed_name, is_ext = true)`	`space` - Reference frame `rate` - Speed `step` - Step size `index` - XYZABC/J1-7 `direction` - Direction `fixed_name`- Used with index
Adjust Speed Online	`adjustSpeedOnline(scale)`	`scale` - Speed ratio
Set Event Watcher	`setEventWatcher(eventType, callback)`	`eventType` - Event type `callback` - Event callback
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` - Avoidance method `enable` - Enable/Disable `threshold` - Threshold
Query Singularity Avoidance Status	`getAvoidSingularity(method)`	`method` - 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
Teach Pendant Hot Swap	`setTeachPendantMode(enable)`	`enable` true - Use teach pendant false - Don't use teach pendant

Real-time Motion Control

Description	Interface	Parameters	Return
Reconnect RT Control Server	`reconnectNetwork()`
Disconnect	`disconnectNetwork()`
Set Control Loop	`setControlLoop(callback, priority,useStateDataInLoop)`	`callback` - Callback `priority` - Thread priority `useStateDataInLoop` - Read RT state in callback
Start Loop	`startLoop(blocking)`	`blocking` - Block or not
Stop Loop	`stopLoop ()`
Start Motion	`startMove(mode)`	`mode` - Control mode
Stop Motion	`stopMove()`
Send JointPosition/CartesianPosition/Torque Command	`sendCommand(cmd)`	`cmd- 3 motion commands based on mode: joint angle/cartesian pose/torque`
Start Receive Robot State	`startReceiveRobotState(timeout ,fields)`	`timeout` - Timeout `fields` - Data fields
Stop Receive Robot State	`stopReceiveRobotState ()`
Update Robot State	`updateRobotState(timeout)`	`timeout` - Timeout
Get Robot State Data	`getStateData(name,data)`	`name` - Data name `data` - Data value
Enable ServoJ	`setServoJoint(ServoJ_T, ServoJ_Lookahead, ServoJ_Kp, )`
Stop ServoJ	`stopServoJoint()`
Check Motion Error	`hasMotionError()`
PTP Joint Space Motion	`MoveJ(speed,start,target)`	`speed` - Speed ratio `start` - Start joint angles `target` - Target joint angles
PTP Cartesian Linear Motion	`MoveL(speed,start,target)`	`speed` - Speed ratio `start` - Start pose `target` - Target pose
3-Point Arc Motion	`MoveC(speed, start,aux,target)`	`speed` - Speed ratio `start` - Start pose `aux` - Auxiliary pose `target` - Target pose
Read DH Parameters	`getRobotCfg_DHparam(get_nominal)`	`get_nominal false` - Optimized/set params true - Read nominal params	DH params
Set Filter Limit	`setFilterLimit(limit,frequency)`	`limit` - Enable limit `frequency` - Cutoff frequency
Set Cartesian Motion Area	`setCartesianLimit(length, frame)`	`length` - Area dimensions `frame` - Area center frame
Set Joint Impedance	`setJointImpedance(factor)`	`factor` - Joint impedance factor
Set Cartesian Impedance	`setCartesianImpedance(factor)`	`factor` - Factor
Set Collision Threshold	`setCollisionBehaviour(threshol d)`	`threshold` - Joint thresholds
Set End Effector Pose	`setEndEffectorFrame(frame)`	`frame` - End pose relative to flange
Set Load	`setLoad(load)`	`load` - Load info
Set Filter Frequency	`setFilterFrequency(joint,cart, torque)`	`joint` - Joint position cutoff `cart` - Cartesian position cutoff `torque` - Joint torque cutoff
Set Cartesian Impedance Desired Torque	`setCartesianImpedanceDesiredTorque(torque)`	`torque` - End desired torque
Set Torque Filter Cutoff	`setTorqueFilterCutoffFrequenc y(frequency)`	`frequency` - Frequency
Set Force Control Frame	`setFcCoor(frame,type)`	`frame` - Frame `type` - FC task frame type
Auto Error Recovery	`automaticErrorRecovery()`
Set Network Tolerance	`setNetworkTolerance(percent)`	`percent` - Threshold percentage
Switch to RCI Client	`useGen1RciClient(use)`	`use` - Switch or not

Path Planning Related

Description	Class
S-curve Cartesian Motion	`CartMotionGenerator`
S-curve Joint Space Motion	`JointMotionGenerator`
Position Following	`FollowPosition`

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
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	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	`projectInfo()`		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 Local RL Project	`importProject(file_path,overwrite)`	`file_path` - Local .zip path, max 10M `overwrite`- Overwrite same name	Project name
Delete RL Project	`removeProject(project_name,remove_all)`	`project_name`- Project name `remove_all`- Delete all, default false
Import Local File	`importFile( src_file_path, dest, overwrite)`	src_file_path Local file path, max 10M dest Target path overwrite Overwrite	Imported file name
Delete Controller File	`removeFiles(file_path_list)`	file_path_list File path list
Set Global Tool Info	`setToolInfo(tool_info)`	tool_info Tool info
Set Global Workpiece Info	`setWobjInfo(wobj_info)`	wobj_info Workpiece info

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	cancelRecordPathO
Save Path	saveRecordPath(name,saveAs)	name-Path name saveAs-Rename as
Replay Path	replayPath(name,rate)	name-Path name rate-Replay rate
Delete Saved Path	removePath(name,all)	name-Path name all -Delete all
Query Path List	queryPathLists()		Path name list
Calibrate Force Sensor	calibrateForceSensor(all_axes, axis_index)	all_axes-Calibrate all axes axis_index-Single axis index

Force Control Commands

Description	Interface	Parameters
Get Current Torque Info	getEndTorque(ref_type,joint, external,cart_torque, cart_force)	ref _type -Reference frame joint-Joint measurements external-External forces cart_torque-Cartesian torque cart_force-Cartesian force
FC Init	fcInit(frame_type)	frame_type-FC frame
Start FC	fcStart()
Stop FC	fcStop0
Set Control Type	setControlType(type)	type-Impedance type
Set FC Load	setLoad(load)	load-Load
Set Joint Stiffness	setJointStiffness(stiffness)	stiffness-Stiffness
Set Cartesian Stiffness	setCartesianStiffness(stiffness)	stiffness-Stiffness
Set Cartesian Nullspace Stiffness	setCartesianNullspaceStiffness(s tiffness)	stiffness-Stiffness
Set Joint Desired Torque	setJointDesiredTorque(torque)	torque-Torque value
Set Cartesian Desired Force/Torque	setCartesianDesiredForce (value)	value-Desired force/torque
Set Sine Overlay	setSineOverlay(line_dir, amplify,frequency,phase,bias)	line_dir-Reference axis amplify-Amplitude frequency-Frequency phase-Phase bias-Bias
Set Lissajous Overlay	setLissajousOverlay (int plane, double amplify_one,double frequency_one,double amplify_two, double frequency_two,double 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 diff
Start Overlay	startOverlay()
Stop Overlay	stopOverlayO
Pause Overlay	pauseOverlay()
Restart Overlay	restartOverlay()
Set Force Condition	setForceCondition(range, isInside,timeout)	range-Force limit isInside-Inside/outside limit timeout-Timeout
Set Torque Condition	setTorqueCondition (range, isInside,timeout)	range-Torque limit isInside-Inside/outside limit timeout-Timeout
Set Pose Box Condition	setPoseBoxCondition(supervisin g_frame,box,isInside,timeout)	supervising_frame-Frame box-Box isInside-Inside/outside timeout-Timeout
Wait Condition	waitCondition ()
FC Monitor	fcMonitor(enable)	enable-Enable/Disable
Set Joint Max Vel	setJointMax Vel(velocity)	velocity-Joint velocity
Set Cartesian Max Vel	setCartesianMax Vel(velocity)	velocity-End velocity
Set Joint Max Momentum	setJointMaxMomentum(momen tum)	momentum-Momentum
Set Joint Max Energy	setJointMaxEnergy(energy)	energy-Energy

C++: Instantiate rokae::Robot Class​

Robot Basic Operations and Information Query​

Motion Control​

Real-time Motion Control​

Communication Related​

RL Project​

Collaboration Related​

Force Control Commands​