接口说明
本章列出各版本 xCore SDK 所支持的接口和功能简述。不同开发语言的版本对接口的功能定义基本一致，但是参数、返回值和调用方法会有区别。
C#：实例化 rokae::Robot 类
根据机器人构型和轴数不同，C# 版本的 SDK 提供了下列几个可供实例化的 Robot 类，初始化时会检查所选构型和轴数是否和连接的机器人匹配：
| 类名 | 适用机型 |
|---|---|
| xMateRobot | 协作 6 轴（xMateCR7/12、xMateSR3/4、xMateER3/7 等） |
| xMateErProRobot | 协作 7 轴（xMateER3 Pro / xMateER7 Pro） |
| StandardRobot | 工业 6 轴 |
| xMateCr5Robot | 协作 5 轴（XMC17_5 / XMC25_5） |
| PCB4Robot | 工业 4 轴 |
| PCB3Robot | 工业 3 轴 |
机器人基本操作及信息查询
| 简述 | 接口 | 参数 | 返回 |
|---|---|---|---|
| 连接机器人 | connectToRobot(ec) | [out] ec - 错误码；地址为构造实例时传入 | |
| 连接机器人 | connectToRobot(remoteIP) | remoteIP - 机器人 IP | |
| 连接机器人 | connectToRobot(remoteIP, localIP) | localIP - 本机 IP，实时交互用；PCB3/4 不支持 | |
| 断开连接 | disconnectFromRobot() | ||
| 设置连接断开回调函数 | setConnectionHandler(handler) | handler - 回调函数 | |
| 查询机器人基本信息 | robotInfo() | 控制器版本，机型，轴数 | |
| 机器人上下电急停状态 | powerState() | on/off/Estop/Gstop | |
| 机器人上下电 | setPowerState(on) | on - true 上电 / false 下电 | |
| 查询当前操作模式 | 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 | |
| 查询多个状态 | getStateList() | 当前位置，IO 信号，操作模式，速度覆盖值 | |
| 查询基坐标系 | baseFrame() | [X,Y,Z,Rx,Ry,Rz] | |
| 设置基坐标系 | setBaseFrame(frame) | frame - 坐标系 | |
| 查询当前工具工件组 | toolset() | 末端坐标系，参考坐标系，负载信息 | |
| 设置工具工件组 | setToolset(toolset)setToolset(toolName,wobjName) | toolset- 工具工件组信息 toolName- 工具名字 wobjName- 工件名字 | |
| 计算逆解 | calcIk(posture)calcIk(posture, toolset) | posture - CartesianPosition^，末端相对外部参考系 toolset - 可选工具工件组 | 关节角度 [rad] |
| 计算正解 | calcFk(joints)calcFk(joints, toolset) | joints - 关节角 [rad] toolset - 可选 | CartesianPosition^ |
| 清除伺服报警 | clearServoAlarm() | ||
| 查询控制器日志 | queryControllerLog(count,level) | count - 查询个数 level -日志等级 | 控制器日志列表 |
| 设置碰撞检测（协作） | enableCollisionDetection(sensitivity, behaviour, fallback_compliance) | sensitivity - 灵敏度 0.01~2.0 behaviour - stop1/stop2/suppleStop fallback_compliance - 回退距离[m] 或柔顺度[0,1] | |
| 设置碰撞检测（工业） | enableCollisionDetection(sensitivity, fallback) | 仅 stop1（安全停止）；fallback - 回退距离[m] | |
| 关闭碰撞检测功能 | disableCollisionDetection() | ||
| 坐标系标定 | calibrateFrame(type, points, is_held, base_aux) | type - tool / wobj / base / rail（导轨基坐标系三点） points - 轴角列表[rad] is_held - 手持/外部（工具、工件） base_aux - 基坐标系标定辅助点[m] | 标定结果与偏差；成功则控制器保存，重启后生效 |
| 获取当前软限位数值 | getSoftLimit(limits) | limits - 各轴软限位 | 已打开/已关闭 |
| 设置软限位 | setSoftLimit(enable,limits) | enable - 打开/关闭 limits - 各轴软限位 | |
| 恢复状态 | recoverState(item) | item - 恢复选项 ：急停恢复 | |
| 读取导轨参数 | getRailParameter(name, value) | 重载：enable/name/baseFrame/数值类（reductionRatio、maxSpeed、encoderResolution 等）/软限位与 range 数组 | |
| 设置导轨参数 | setRailParameter(name, value) | 重载：Frame（baseFrame）、String（name）、double、bool（enable）、array<double>（softLimit/range）、int（encoderResolution、motorSpeed） | |
| 配置NTP | configNtp(server_ip) | server_ip - NTP 服务端 IP | |
| 手动同步一次 NTP 时间 | syncTimeWithServer() | ||
| 查询 SDK 版本号 | sdkVersion() | 版本号 | |
| 接收一次机器人状态 | updateRobotState(timeout_ms) | timeout_ms - 超时[ms] | 本帧数据长度；超时返回 0 |
| 读取机器人状态数据 | getStateData(name, data) | name - 见 startReceiveRobotState 与头文件说明；data - array<double> 等，类型须一致 | 成功 0，失败 -1 |
| 读取时间戳 | getStateData("ts", data) | data - UInt64%，微秒时间戳 | 同上 |
| 读取臂角 | getStateData("psi_m", data) | data - double% | 同上 |
| 开始发送实时状态 | startReceiveRobotState(interval, fields) | interval - 1/2/4/8 ms 或 1 s；fields - 字段名数组，总长度 ≤1024 字节 | 阻塞至首帧或超时 |
| 停止实时状态 | stopReceiveRobotState() | ||
| 重启工控机 | rebootSystem(ec) | ||
| 关闭工控机 | shutdownSystem(ec) | 控制柜断电后重新上电才能启动控制器软件 | |
| 示教器热插拔 | setTeachPendantMode(enable) | enable - 使用/不使用示教器 | |
| 读取 DH 参数 | getRobotCfg_DHparam(get_nominal) | get_nominal - false：优化后/设置后；true：标称参数 | 各轴 Alpha[°]、A[mm]、D[mm]、Theta[°] |
| 计算全部逆解 | calcAllIkSolutions(posture, confs) | posture - 法兰相对基坐标系；confs - 输出 confdata | 逆解数组；不支持 xMateSR(XMS) |
| 读机械单元参数 | getMechUnit(name, info, value) | name - u1~u6；info - 参数名；value - bool/int/字符串数组（重载） | |
| 读外部轴参数 | getExtAxisInfo(name, info, value) | name - axis1~axis6；info - 参数名；value - bool/int/double/String/字符串数组（重载） |
运动控制
非实时模式运动控制相关接口。
| 简述 | 接口 | 参数 | 返回 |
|---|---|---|---|
| 设置运动控制模式 | setMotionControlMode(mode) | mode - Idle / NrtCommand / NrtRLTask / RtCommand（非实时指令、非实时 RL、实时） | |
| 开始/继续运动 | moveStart() | ||
| 运动重置 | moveReset() | ||
| 暂停机器人运动 | stop() | ||
| 添加运动指令 | moveAppend(type, cmd, cmdId)moveAppend(type, cmdList, cmdId) | type - MoveCommand::Type，与同批指令一致 cmd / cmdList - 单条或 1~100 条同类型指令 cmdId - 指令 ID，用于执行信息反馈 | |
| 设置默认运动速度 | setDefaultSpeed(speed) | speed - 末端最大线速度 | |
| 设置默认转弯区 | setDefaultZone(zone) | zone - 转弯区半径 | |
| 设置是否使用 conf | setDefaultConfOpt(forced) | forced - 是/否使用 | |
| 设置运动指令是否自动取消转弯区 | setAutoIgnoreZone(enable) | enable - 是/否自动取消转弯区 | |
| 设置最大缓存指令个数 | setMaxCacheSize(number) | number - 个数 | |
| 开始 Jog 机器人 | startJog(space,rate,step,index, direction) | space - 参考坐标系rate - 速率 step - 步长 index - XYZABC/J1-7 direction - 方向 | |
| 动态调整机器人运动速率 | adjustSpeedOnline(scale) | scale - 速率 | |
| 设置接收事件的回调函数 | setEventWatcher(eventType, callback) | eventType - moveExecution / safety / rlExecution / logReporter callback - 回调（moveExecution 同线程勿阻塞；safety 独立线程） | |
| 查询事件信息 | queryEventInfo(eventType) | eventType - 事件类型 | 事件信息 |
| 执行运动指令 | executeCommand(type, cmd) | type - MoveCommand::Type cmd - 1~100 条同类型指令，调用后立即运动 | |
| 读取当前加速度 | getAcceleration(acc,jerk) | acc - 加速度 jerk - 加加速度 | |
| 设置运动加速度 | adjustAcceleration(acc,jerk) | acc - 加速度 jerk - 加加速度 | |
| 打开奇异规避功能 | setAvoidSingularity(method, enable, limit) | method - 四轴锁定/牺牲姿态/轴空间插补（协作 6 轴无轴空间插补） enable - 打开/关闭 limit - 牺牲姿态为姿态误差[rad]；轴空间插补为规避半径[m] | |
| 查询是否打开规避奇异功能 | getAvoidSingularity(method) | method - 奇异规避方式 | 已打开/已关闭 |
| 检验直线轨迹是否可达 | checkPath(start, start_joint, target) | 支持导轨；start/target 为笛卡尔点位 | 目标轴角 |
| 校验多段直线 | checkPath(start_joint, targets, target_joint_calculated) | targets 至少 2 点，首点为起点 | 失败时返回出错点下标 |
| 检验圆弧是否可达 | checkPath(start, start_joint, aux, target) | aux - 辅助点 | 目标轴角 |
| 检验全圆是否可达 | checkPath(start, start_joint, aux1, aux2, angle, rot_type) | angle - 全圆弧度；rot_type - 旋转类型 | 目标轴角 |
通信相关
| 简述 | 接口 | 参数 | 返回值 |
|---|---|---|---|
| 查询 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（0x03/04/06/10）；reg_addr；data_type（int32/int16/uint32/uint16）；num；array<int>^% data_array；if_crc_reverse | |
| 485 通信读写线圈或离散输入 | XPRWModbusRTUCoil(...) | fun_cmd 0x01/02/05/0F；array<bool>^% data_array；其余同寄存器 | |
| 485 通信裸传数据 | XPRS485SendData(send_byte, rev_byte, send_data, recv_data) | 收/发长度各 0~16；recv_data 为输出 |
RL工程
控制器中需要有已创建好的RL工程，支持查询工程信息和运行。
| 简述 | 接口 | 参数 | 返回值 |
|---|---|---|---|
| 查询RL 工程列表 | projectsInfo() | 工程名称和任务名 | |
| 加载工程 | loadProject(name,tasks) | name-工程名称 tasks-任务列表 | |
| pp-to-main | ppToMain() | ||
| 开始运行工程 | runProject() | ||
| 暂停运行工程 | pauseProject() | ||
| 设置运行速率和循环模式 | setProjectRunningOpt(rate, loop) | rate-运行速率 loop-循环/单次 | |
| 设置全局工具信息 | setToolInfo(tool_info) | tool_info-工具信息 | |
| 设置全局工件信息 | setWobjInfo(wobj_info) | wobj_info-工件信息 | |
| 查询工具信息 | toolsInfo() | 工具名称，位姿，负载等信息 | |
| 查询工件信息 | wobjsInfo() | 工件名称，位姿，负载等信息 | |
| 导入本地文件到控制器 | importFile(src_file_path, dest, bool overwrite) | src_file_path-本地文件路径dest-目标路径overwrite-覆盖同名文件 | 导入成功后文件名 |
| 删除控制器中文件 | removeFiles(file_path_list) | 文件路径的列表 | |
| 将本地的RL工程压缩包导入控制器 | importProject(file_path, bool overwrite) | file_path-本地 .zip压缩包路径overwrite-是否覆盖同名文件 | 工程名称 |
| 删除控制器里的RL工程 | removeProject(project_name, remove_all) | project_name-工程名称remove_all-是否删除所有工程 |
协作相关
包括拖动示教和路径录制相关功能。
| 简述 | 接口 | 参数 | 返回值 |
|---|---|---|---|
| 打开拖动 | enableDrag(space,type, enable_drag_button) | space-拖动空间 type-拖动类型 enable_drag_button-无需按键拖动 | |
| 关闭拖动 | disableDrag() | ||
| 开始录制路径 | startRecordPath() | 时长须在 30 分钟内；非阻塞，结束调用 stopRecordPath() | |
| 停止录制路径 | 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-单轴标定下标 |
xMate 五轴（xMateCr5Robot）
| 简述 | 接口 | 参数 | 返回值 |
|---|---|---|---|
| 平行基座模式 | enableCompletePostureLerp(enable) | enable - true 开启 / false 关闭 |
力控指令
| 简述 | 接口 | 参数 | 返回值 |
|---|---|---|---|
| 力控指令类 | forceControl() | ForceControl | |
| 获取当前力矩信息 | getEndTorque(ref_type, joint_torque_measured, external_torque_measured, cart_torque, cart_force) | ref_type - world / flange / tool 其余为输出：轴测量力矩、轴外部力矩、笛卡尔力矩、笛卡尔力 | |
| 力控初始化 | fcInit(frame_type) | world / wobj / tool / baseFrame / flange | |
| 开始力控 | fcStart() | fcInit 之后；fcStart 前 moveAppend 未 moveStart 的指令会在力控开始后执行 | |
| 停止力控 | fcStop() | ||
| 设置阻抗控制类型 | setControlType(type) | 0 - 关节阻抗；1 - 笛卡尔阻抗 | |
| 设置力控模块使用的负载 | setLoad(load) | fcStart 之后可调用 | |
| 设置关节阻抗刚度 | setJointStiffness(stiffness) | fcInit 之后生效 | |
| 设置笛卡尔阻抗刚度 | setCartesianStiffness(stiffness) | XYZ 力刚度 [N/m] + ABC 力矩刚度 [Nm/rad] | |
| 设置笛卡尔零空间阻抗刚度 | setCartesianNullspaceStiffness(stiffness) | [0,4] Nm/rad | |
| 设置关节期望力矩 | setJointDesiredTorque(torque) | [-30,30] Nm | |
| 设置笛卡尔期望力/力矩 | setCartesianDesiredForce(value) | XYZ 力 [-60,60] N；ABC 力矩 [-10,10] Nm | |
| 设置正弦搜索运动 | setSineOverlay(line_dir, amplify, frequency, phase, bias) | 须先 setControlType(1)；0/1/2 为 X/Y/Z 轴 | |
| 设置莉萨如搜索运动 | setLissajousOverlay(plane, amplify_one, frequency_one, amplify_two, frequency_two, phase_diff) | 须先 setControlType(1)；平面 0/1/2 为 XY/XZ/YZ | |
| 开启搜索运动 | startOverlay() | fcStart 之后 | |
| 停止搜索运动 | stopOverlay() | ||
| 暂停搜索运动 | pauseOverlay() | ||
| 重新开启暂停的搜索运动 | restartOverlay() | ||
| 设置与接触力有关的终止条件 | setForceCondition(range, isInside, timeout) | range - 六元力限制[N]；isInside - true 超出时停止，false 符合条件时停止；timeout [1,600] s | |
| 设置与接触力矩有关的终止条件 | setTorqueCondition(range, isInside, timeout) | 同上，单位 Nm | |
| 设置与接触位置有关的终止条件 | setPoseBoxCondition(supervising_frame, box, isInside, timeout) | 参考系相对外部工件；box 六元 [m]；isInside 含义同力条件 | |
| 激活终止条件并等待 | waitCondition() | ||
| 启动/关闭力控保护监控 | fcMonitor(enable) | 阈值在 fcMonitor(true) 后生效，false 后恢复默认保护 | |
| 力控轴最大速度 | setJointMaxVel(velocity) | [rad/s] | |
| 末端相对基座最大速度 | setCartesianMaxVel(velocity) | XYZ [m/s]，ABC [rad/s] | |
| 力控轴最大动量 | setJointMaxMomentum(momentum) | N·s | |
| 力控轴最大动能 | setJointMaxEnergy(energy) | N·rad/s | |
| 笛卡尔阻抗力限幅 | setCartesianControlMaxWrench(max_wrench) | XYZ[N]、ABC[Nm]，[0,1000]，fcStart~fcStop 有效 | |
| 笛卡尔阻抗接触限速 | setCartesianControlMaxVel(max_cart_vel) | XYZ [0,3] m/s；ABC [0,10] rad/s | |
| 关节阻抗力矩限幅 | setJointControlMaxTorque(max_torque) | Nm，[0,1000] | |
| 关节阻抗速度限幅 | setJointControlMaxVel(max_joint_vel) | rad/s，[0,10] | |
| 力控带宽 | setFcGain(gain) | 各轴 [0,60]，默认 20 | |
| 摩擦力补偿 | setFriction(fric) | 各轴 [0,1]，默认 0.9 |