接口说明
本章列出各版本 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 - 参数值 | |
| 配置NTP | configNtp(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 - 转弯区半径 | |
| 设置是否使用 conf | setDefaultConfOpt(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:24vif_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-65535fun_cmd - int,功能码,有效值0x03/04/06/10reg_addr - int,寄存器起始地址,0-65535data_type - string,int16/uint16/int32/uint32num - 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/0x0Fcoil_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/uint8recv_frame - CANFrame,接收帧信息与数据 | |
| 发送 CAN 裸数据 | CANSendData(data_type, send_frames, ec) | data_type - 发送CAN帧数据类型,int16/uint16/uint8send_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-main | ppToMain() | ||
| 开始运行工程 | 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 节。