接口说明
本章列出各版本 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 - 本机地址。实时模式下收发交互数据用 | |
| 断开连接 | disconnectFromRobot() | ||
| 查询机器人基本信息 | robotInfo() | 控制器版本，机型，轴数，MAC 等 | |
| 机器人上下电急停状态 | powerState() | on/off/Estop/Gstop | |
| 机器人上下电 | setPowerState(state) | state - on/off | |
| 查询当前操作模式 | operateMode () | auto/manual | |
| 切换手自动模式 | setOperateMode(mode) | mode - auto/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 | |
| 获取当前关节速度 | jointVel() | 各轴速率 rad/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)工业六轴（ StandardRobot）：enableCollisionDetection(sensitivity, fallback) | 协作：behaviour 含 stop1/stop2/柔顺等工业：仅 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) | name：axis1～axis6 或 u1～u6；info 为字段名字符串 | 写入 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 - 加加速度 | |
| 打开奇异规避功能 | setAvoidSingularity(method, enable,threshold) | method - 奇异规避方式 enable - 打开/关闭 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(Vopt,if_rs485) | Vopt - 输出电压 if_rs485 - 是否打开 485 通信 | |
| 485 通信读写寄存器 | XPRWModbusRTUReg(slave_addr,fun_cmd, reg_addr data_type,num,data_array,if_crc_reverse) | slave_addr - 从站地址 fun_cmd - 功能码 reg_addr - 寄存器地址 data_type - 数据类型 num - 数据长度 data_array - 数据数组 if_crc_reverse - 是否需要 CRC 反转 | |
| 485 通信读写线圈或离散输入 | XPRWModbusRTUCoil(slave_addr,fun_cmd, coil_addr,int num,data_array,if_crc_reverse) | slave_addr - 从站地址 fun_cmd - 功能码 coil_addr - 线圈地址 num - 数据长度 data_array - 数据数组 if_crc_reverse - 是否需要 CRC 反转 | |
| 485 通信裸传数据 | XPRS485SendData(send_byte,rev_byte,send_data,rev_data,) | send_byte - 发送数据长度 rev_byte - 接收数据长度send_data - 发送数据 rev_data - 接收数据 |
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-拖动空间 type-拖动类型 enable_drag_button-无需按键拖动 | |
| 关闭拖动 | disableDrag() | ||
| 开始录制路径 | startRecordPath(duration) | duration-录制时长 | |
| 停止录制路径 | stopRecordPath() | ||
| 取消录制 | cancelRecordPath() | ||
| 保存路径 | saveRecordPath(name,saveAs) | name-路径名称 saveAs-重命名为 | |
| 路径回放 | replayPath(name,rate) | name-路径名称 rate-回放速率 | |
| 删除保存的路径 | removePath(name,all) | name-路径名称 all -是否删除所有路径 | |
| 查询路径列表 | queryPathLists() | 路径名称列表 | |
| 力传感器标定 | calibrateForceSensor(all_axes, axis_index) | all_axes-标定所有轴 axis_index-单轴标定下标 | |
| 实时指令网络丢包阈值 | setRtNetworkTolerance(percent, ec) | percent - 0～100，对应 RobotAssist-RCI「包丢失阈值」；须在切换到 RtCommandMode 前设置 |
力控指令
| 简述 | 接口 | 参数 | 返回值 |
|---|---|---|---|
| 获取当前力矩信息 | getEndTorque(ref_type,joint, external,cart_torque, cart_force) | ref _type -力矩相对的参考系 joint-各轴测量 external-各轴外部力 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 (int plane, double amplify_one,double frequency_one,double amplify_two, double frequency_two,double phase_diff,error_code &ec) | 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-动能 |