跳到主要内容

接口说明

本章列出各版本 xCore SDK 所支持的接口和功能简述。不同开发语言的版本对接口的功能定义基本一致,但是参数、返回值和调用方法会有区别。

Python:实例化 rokae::Robot 类​

根据机器人构型和轴数不同,Python 版本的 SDK 提供了下列几个可供实例化的 Robot 类,初始化时会检查所选构型和轴数是否和连接的机器人匹配:

类名适用机型
xMateRobot协作6 轴
xMateErProRobot协作7 轴
StandardRobot工业6 轴
xMateCr5Robot协作CR5 轴
PCB4Robot工业4 轴
PCB3Robot工业3 轴

机器人基本操作及信息查询​

简述接口参数返回
连接机器人connectToRobot()
连接机器人connectToRobot(remoteIP,localIP)remoteIP - 机器人IP 地址
localIP - 本机地址。实时模式下收发交互数据用,可不设置;PCB3 / PCB4 不支持
断开连接disconnectFromRobot()
查询机器人基本信息robotInfo()控制器版本,机型,轴数,MAC 等
机器人上下电急停状态powerState()on/off/estop/gstop
机器人上下电setPowerState(on)on - true 上电 / false 下电
查询当前操作模式operateMode ()automatic/manual
切换手自动模式setOperateMode(mode)mode - automatic/manual
查询机器人运行状态operationState()idle/jog/rlProgram/moving等状态
获取当前末端/法兰位姿posture(ct)ct - 坐标系类型[X,Y,Z,Rx,Ry,Rz]
获取当前末端/法兰位姿cartPosture(ct)ct - 坐标系类型[X,Y,Z,Rx,Ry,Rz]及轴配
置参数
获取当前关节角度jointPos()本体 rad;外部轴、导轨、附加轴 rad 或 m
获取当前关节速度jointVel()本体 rad/s;外部轴、导轨、附加轴 rad/s 或 m/s
获取关节力矩jointTorque()各轴力矩 Nm
接收实时状态 / 按字段读取updateRobotState(timeout)
getStateData(fieldName, data, …)
实时模式下;字段名见 RtSupportedFields状态数据
停止接收实时状态stopReceiveRobotState()用于重新配置订阅字段
查询基坐标系baseFrame()[X,Y,Z,Rx,Ry,Rz]
设置基坐标系setBaseFrame(frame)frame - 坐标系
查询当前工具工件组toolset()末端坐标系,参考坐标系,负载信息
设置工具工件组setToolset(toolset)
setToolset(toolName,wobjName)
toolset- 工具工件组信息
toolName- 工具名字
wobjName- 工件名字
计算逆解robot.model().calcIk(posture)
robot.model().calcIk(posture,toolset)
posture - 末端相对于外部参考坐标系位姿
toolset- 工具工件组信息
关节角度
计算正解robot.model().calcFk(joints)
robot.model().calcFk(joints,toolset)
joints- 关节角度
toolset - 工具工件组信息
末端相对于外部参考坐标系位姿
计算全部逆解robot.model().calcAllIkSolutions(posture, confs, ec)posture - 法兰相对基坐标系
confs - 各组 confdata
多组关节角(不支持 xMateSR/XMS)
清除伺服报警clearServoAlarm()
查询控制器日志queryControllerLog(count, level[, offset])count - 查询个数
level - 日志等级
offset - 从最新条起偏移,默认 0
控制器日志列表
设置碰撞检测相关参数,打开碰撞检测功能协作:enableCollisionDetection(sensitivity,behaviour,fallback_compliance)
工业六轴(StandardRobot):enableCollisionDetection(sensitivity, fallback)
协作:behaviour 含 stop1/stop2/柔顺等;fallback_compliance 为回退距离(米)或柔顺度
工业:仅 stop1,无 behaviour;fallback 为回退距离(米)
关闭碰撞检测功能disableCollisionDetection()
坐标系标定calibrateFrame(type,points, is_held,base_aux)type - 坐标系类型
points - 标定轴角度列表
is_held - 手持/外部工具工件
base_aux - 基坐标系标定辅助点
标定结果:坐标系和偏差
获取当前软限位数值getSoftLimit(limits)limits - 各轴软限位已打开/已关闭
设置软限位setSoftLimit(enable,limits)enable - 打开/关闭
limits - 各轴软限位
恢复状态recoverState(item)item - 恢复选项 :急停恢复
重启工控机rebootSystem(ec)自动模式/上电/运动中/非空闲时不允许重启
关闭工控机shutdownSystem(ec)自动模式/上电/运动中/非空闲时不允许关闭;断电后重新上电才能启动控制器
连接状态回调setConnectionHandler(handler)handler(bool):true 已连接 / false 断开
示教器模式setTeachPendantMode(enable)阻塞至切换完成(约 2s 量级)
读取 DH 参数getRobotCfg_DHparam(get_nominal, ec)get_nominal:true 标称 / false 优化或当前设置各轴 Alpha[°]、A[mm]、D[mm]、Theta[°] 依次排列
附加轴信息 / 机械单元getExtAxisInfo(name, info, value, ec)
getMechUnit(name, info, value, ec)
getExtAxisInfo 读附加轴,name 为 axis1~axis6;getMechUnit 读机械单元,name 为 u1~u6写入 value 输出参数
设置导轨参数setRailParameter(name, value)name - 参数名
value - 参数值
读取导轨参数getRailParameter(name,value)name - 参数名
value - 参数值
配置NTPconfigNtp(server_ip)server_ip - NTP 服务端 IP
手动同步一次 NTP 时间syncTimeWithServer()
查询 SDK 版本号sdkVersion()版本号

运动控制​

非实时模式运动控制相关接口。

简述接口参数返回
设置运动控制模式setMotionControlMode(mode)mode - Idle / NrtCommandMode / NrtRLTask / RtCommandMode
开始/继续运动moveStart()
运动重置moveReset()
暂停机器人运动stop()
暂停运动(同 stop)pause(ec)
添加运动指令moveAppend(command,id)command - 一条或多条 MoveL/MoveJ/MoveAbsJ/MoveC/MoveCF/MoveSP 指令
id -指令 ID ,用于执行信息反馈
设置默认运动速度setDefaultSpeed(speed)speed - 末端最大线速度
设置默认转弯区setDefaultZone(zone)zone - 转弯区半径
设置是否使用 confsetDefaultConfOpt(forced) forced - 是/否使用
设置最大缓存指令个数setMaxCacheSize(number)number - 允许范围 [1, 1000],默认 300
开始 Jog 机器人startJog(space,rate,step,index, direction)space - 参考坐标系
rate - 速率
step - 步长
index - XYZABC/J1-7
direction - 方向
Jog(外部轴/机械单元)startJogWithExt(space, rate, step, index, direction, fixed_name, ec[, is_ext])fixed_name 与 index、is_ext 配合指定本体轴或机械单元轴
动态调整机器人运动速率adjustSpeedOnline(scale)scale - 速率
设置接收事件的回调函数setEventWatcher(eventType, callback)eventType - 事件类型
callback - 处理事件的回调函数
取消事件回调setNoneEventWatcher(eventType, ec)eventType - 与 setEventWatcher 一致
自动取消转弯区setAutoIgnoreZone(enable, ec)enable - 是否自动取消转弯区,初始为 true
查询事件信息queryEventInfo(eventType) eventType - 事件类型事件信息
执行运动指令executeCommand(command)command - 一条或多条 MoveL/MoveJ/MoveAbsJ/MoveC/MoveCF/MoveSP 指令
读取当前加速度getAcceleration(acc,jerk)acc - 加速度
jerk - 加加速度
设置运动加速度adjustAcceleration(acc,jerk)acc - 加速度
jerk - 加加速度
打开奇异规避功能xMateRobot:setAvoidSingularity(method, enable, limit)
StandardRobot:setAvoidSingularity(method, enable, threshold)
四轴锁定:工业六轴、xMateCR/SR 六轴;牺牲姿态:所有六轴;轴空间插补:工业六轴。第三参数协作名 limit,工业名 threshold
查询是否打开规避奇异功能getAvoidSingularity(method)method - 奇异规避方式已打开/已关闭
检验笛卡尔轨迹是否可达checkPath(start,start_joint, target)start - 起始点
start_joint - 起始关节角度
target - 目标点
计算出的目标轴角

通信相关​

简述接口参数返回值
查询 DI 信号值getDI(board,port)board - IO 板序号
port - 信号端口号
on
设置 DI 信号值setDI(board,port,state)board - IO 板序号
port -信号端口号
state - 信号值
查询 DO 信号值getDO(board,port)board - IO 板序号
port - 信号端口号
on
设置 DO 信号值setDO(board,port,state)board - IO 板序号
port - 信号端口号
state - 信号值
查询 AI 信号值getAI(board,port)board - IO 板序号
port - 信号端口号
信号值
设置 AO 信号setAO(board,port,value)board - IO 板序号
port - 信号端口号
value - 信号值
设置输入仿真模式setSimulationMode(state)state - 打开/关闭
读取寄存器值readRegister(name,index,value)name - 寄存器名称
index - 寄存器数组索引value-读取的数值
写入寄存器值writeRegister(name,index,value)name - 寄存器名称
index - 寄存器数组索引
value - 写入的数值
设置 xPanel 对外供电模式setxPanelVout(opt)opt - 模式
获取末端按键状态getKeypadState()末端按键的状态
末端工具 485 通信开关setxPanelRS485(opt, if_rs485, ec)opt - 对外供电模式,0:不输出,1:保留,2:12v,3:24v
if_rs485 - 是否打开 485 通信
初始化 xPanel RS485 通信参数xPanelRS485Init(baud, check_bit, stop_bit, ec)baud - 末端RS485通信波特率
check_bit - 校验位,支持无、奇校验、偶校验
stop_bit - 停止位,支持1个/2个停止位
设置 xPanel RS485 通信超时setxPanelRS485Overtime(overtime_ms, ec)overtime_ms - RS485通信超时时间(ms),范围 50~10000
初始化 xPanel CAN 波特率xPanelCANInit(arbitration_baud, data_baud, ec)arbitration_baud - 仲裁波特率
data_baud - 数据波特率
485 通信读写寄存器XPRWModbusRTUReg(slave_addr, fun_cmd, reg_addr, data_type, num, data_array, if_crc_reverse, ec)slave_addr - int,末端连接设备地址,0-65535
fun_cmd - int,功能码,有效值0x03/04/06/10
reg_addr - int,寄存器起始地址,0-65535
data_type - string,int16/uint16/int32/uint32
num - int,一次操作连续寄存器个数;功能码0x06时无效。CR/ER/SR:末端固件小于301时16位[1,3]、32位1;≥301时16位[1,59]、32位[1,29];AR:16位[1,27]、32位[1,13]
data_array - 读写缓冲(PyTypeVectorInt);功能码0x06时只用[0],功能码0x10时长度须与num一致
if_crc_reverse - bool,是否改变CRC高低位,默认false
485 通信读写线圈或离散输入XPRWModbusRTUCoil(slave_addr, fun_cmd, coil_addr, num, data_array, if_crc_reverse, ec)slave_addr - int,末端连接设备地址
fun_cmd - int,功能码,有效值0x01/0x02/0x05/0x0F
coil_addr - int,线圈或离散输入起始地址
num - int,连续读写个数;功能码0x05时无效。CR/ER/SR:末端固件小于301时[1,48];≥301时[1,944];AR:[1,432]
data_array - 布尔缓冲(PyTypeVectorBool);功能码0x05时只用[0]
if_crc_reverse - bool,是否改变CRC高低位,默认false
485 通信裸传数据XPRS485SendData(send_byte, rev_byte, send_data, rev_data, ec)send_byte - int,待发送字节数
rev_byte - int,待接收字节数
send_data - 发送数据,长度须与send_byte一致
rev_data - 接收缓冲,长度须与rev_byte一致
接收 CAN 裸数据CANReceiveData(timeout_ms, data_type, recv_frame, ec)timeout_ms - 接收超时时间
data_type - 接收数据类型,int16/uint16/uint8
recv_frame - CANFrame,接收帧信息与数据
发送 CAN 裸数据CANSendData(data_type, send_frames, ec)data_type - 发送CAN帧数据类型,int16/uint16/uint8
send_frames - list[CANFrame],待发送帧列表
按序发送并接收 CAN 帧CANRwData(param, ec)param - 类型为 CANRwParam,输入请求
ec - 类型为 dict,写入错误码和错误信息
返回值 list[list[list[int]]],按组返回实际收到的帧,每帧为原始字节

RL工程​

控制器中需要有已创建好的RL工程,支持查询工程信息和运行。

简述接口参数返回值
查询RL 工程列表projectsInfo()工程名称和任务名
加载工程loadProject(name,tasks)name-工程名称
tasks-任务列表
pp-to-mainppToMain()
开始运行工程runProject()
暂停运行工程pauseProject()
设置运行速率和循环模式setProjectRunningOpt(rate,
loop)
rate-运行速率
loop-循环/单次
查询工具信息toolsInfo()工具名称,位姿,负载等信息
查询工件信息wobjsInfo()工件名称,位姿,负载等信息
导入 RL 工程压缩包importProject(file_path, overwrite, ec)file_path - 本地 .zip 路径(≤10M)
overwrite - 是否覆盖同名
工程名(自动重命名时为重命名后名称)
删除 RL 工程removeProject(name, ec[, remove_all])name - 工程名
remove_all - 是否删除全部工程,默认 false
导入文件到控制器importFile(file_path, dest, overwrite, ec)file_path - 本地文件路径
dest - 控制器目标路径
overwrite - 是否覆盖
导入后的文件名
删除控制器文件removeFiles(file_path_list, ec)路径列表,见方法说明
设置工具信息setToolInfo(tool_info, ec)tool_info - 工具信息
设置工件信息setWobjInfo(wobj_info, ec)wobj_info - 工件信息

协作相关​

包括拖动示教和路径录制相关功能。

简述接口参数返回值
打开拖动enableDrag(space,type,
enable_drag_button)
space:0 轴空间,1 笛卡尔(轴空间仅自由拖拽)
type:0 仅平移,1 仅旋转,2 自由拖拽
enable_drag_button:true 时无需按住末端按键
关闭拖动disableDrag()
开始录制路径startRecordPath(duration)duration-录制时长
停止录制路径stopRecordPath()
取消录制cancelRecordPath()
保存路径saveRecordPath(name,saveAs)name-路径名称
saveAs-重命名为
路径回放replayPath(name,rate)name-路径名称
rate-回放速率
删除保存的路径removePath(name,removeAll)name-路径名称
removeAll -是否删除所有路径,默认 false
查询路径列表queryPathLists()路径名称列表
力传感器标定calibrateForceSensor(all_axes,
axis_index)
all_axes-标定所有轴
axis_index-单轴标定下标
实时指令网络丢包阈值setRtNetworkTolerance(percent, ec)percent - 0~100,对应 RobotAssist-RCI「包丢失阈值」;须在切换到 RtCommandMode 前设置
平行基座模式enableCompletePostureLerp(enable, ec)仅 xMateCr5Robot。enable true 开启,false 关闭

力控指令​

简述接口参数返回值
获取当前力矩信息getEndTorque(ref_type,joint_torque_measured,
external_torque_measured,cart_torque,
cart_force)
ref_type -力矩相对的参考系
joint_torque_measured-各轴测量力
external_torque_measured-各轴外部力
cart_torque-笛卡尔空间力矩
cart_force-笛卡尔空间力
力控初始化fcInit(frame_type)frame_type-力控坐标系
开始力控fcStart()
停止力控fcStop()
设置阻抗控制类型setControlType(type)type-阻抗类型
设置力控模块使用的负载setLoad(load)load-负载
设置关节阻抗刚度setJointStiffness(stiffness)stiffness-刚度
设置笛卡尔阻抗刚度setCartesianStiffness(stiffness)stiffness-刚度
设置笛卡尔零空间阻抗刚度setCartesianNullspaceStiffness(s tiffness)stiffness-刚度
设置关节期望力矩setJointDesiredTorque(torque)torque-力矩值
设置笛卡尔期望力/力矩setCartesianDesiredForce
(value)
value-期望力/力矩
设置绕单轴旋转的正弦搜索运动setSineOverlay(line_dir,
amplify,frequency,phase,bias)
line_dir-参考轴
amplify-幅值
frequency-频率
phase-相位
bias-偏置
设置平面内的莉萨如搜索运动setLissajousOverlay(plane,
amplify_one,frequency_one,
amplify_two,frequency_two,
phase_diff)
plane-参考平面
amplify_one-一方向幅值
frequency_one-一方向频率
amplify_two-二方向幅值
frequency_two-二方向频率
phase_diff-相位偏差
开启搜索运动startOverlay()
停止搜索运动stopOverlay()
暂停搜索运动pauseOverlay()
重新开启暂停的搜索运动restartOverlay()
设置与接触力有关的终止条件setForceCondition(range,
isInside,timeout)
range-力限制
isInside-超出/符合限制条件
时停止等待
timeout-超时时间
设置与接触力矩有关的终止条件setTorqueCondition (range,
isInside,timeout)
range-力矩限制
isInside-超出/符合限制条件
时停止等待
timeout-超时时间
设置与接触位置有关的终止条件setPoseBoxCondition(supervisin g_frame,box,isInside,timeout)supervising_frame-长方体所
在的参考坐标系
box-长方体
isInside-超出/符合限制条件
时停止等待
timeout-超时时间
激活设置的终止条件并等待waitCondition ()
启动/关闭力控模块保护监控fcMonitor(enable)enable-打开|关闭
设置力控模式下的轴最大速度setJointMax Vel(velocity)velocity-轴速度
设置机械臂末端相对基坐标系的最大速度setCartesianMax Vel(velocity)velocity-末端速度
设置力控模式下轴最大动量setJointMaxMomentum(momen tum)momentum-动量
设置力控模式下轴最大动能setJointMaxEnergy(energy)energy-动能
释放力控对象reset()绑定未附说明
各轴力控带宽setFcGain(gain, ec)范围 [0, 60],默认 20
摩擦力补偿setFriction(fric, ec)范围 [0, 1],默认 0.9
阻抗关节速度限幅setJointControlMaxVel(max_joint_vel, ec)rad/s,范围 [0, 10]
阻抗关节力限幅setJointControlMaxTorque(max_torque, ec)Nm,范围 [0, 1000]
阻抗笛卡尔速度限幅setCartesianControlMaxVel(max_cart_vel, ec)XYZ [0, 3] m/s,ABC [0, 10] rad/s
阻抗笛卡尔力限幅setCartesianControlMaxWrench(max_wrench, ec)XYZ N,ABC Nm,范围 [0, 1000]

实时控制​

协作机型用 getRtMotionController() 取得 motioncontrolRT.PyRTmotioncontrol5/6/7。工业机型没有该接口。状态接收在机器人对象上。

简述接口参数返回值
开始接收实时状态startReceiveRobotState(interval, fields)间隔 1ms/2ms/4ms/8ms/1s;字段总长 ≤1024 字节
创建实时控制器getRtMotionController()仅协作机型控制器对象
发送实时命令sendCommand(cmd)JointPosition / CartesianPosition / Torque
准备运动startMove(rtMode)发出命令后才开始运动
停止运动stopMove()

周期回调、阻抗、滤波、碰撞阈值和已弃用的 MoveJ / MoveL / MoveC 见方法附录第 7 节。

模型库​

model 子模块的 Model_* 提供已有的逆解和正解。打开 CMake 选项 XMATE_MODEL(默认关闭)后,协作机型 model() 返回 xmateModel_1_5/6/7,另有 setLoad(mass, cog, inertia)、setTcpCoor、getCartPose / getCartVel / getCartAcc、getJointPos / getJointVel / getJointAcc、jacobian、getTorqueNoFriction。连杆用 SegmentFrame。详见方法附录第 8 节。

utility​

xCoreSDK_python.utility:度与弧度、齐次矩阵与位姿、欧拉角与四元数、Toolset 与法兰/末端坐标转换。详见方法附录第 9 节。

planner​

xCoreSDK_python.planner:CartMotionGenerator、JointMotionGenerator(7 轴)。FollowPosition_5/6/7 与 xmateModel 一样,只在 XMATE_MODEL 打开时绑定。详见方法附录第 10 节。