跳到主要内容

方法

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

connectToRobot() [1/2]​

def connectToRobot(self, ec: dict) -> None:

建立与机器人的连接。机器人地址为创建robot 实例时传入的

  • 参数:[out] ec: 错误码

connectToRobot() [1/2]​

def connectToRobot(self, remoteIP: str, localIP: str = '') -> None:

连接到机器人

  • 参数:
    • remoteIP 机器人 IP 地址
    • localIP 本机地址。实时模式下收发交互数据用,可不设置;PCB3 /4 轴机型不支持

disconnectFromRobot()​

def disconnectFromRobot(self, ec: dict) -> None:

断开与机器人连接。断开前会停止机器人运动,请注意安全

  • 参数: [out] ec: 错误码

robotInfo()​

def robotInfo(self, ec: dict) -> Info:

查询机器人基本信息

  • 参数: [out] ec: 错误码
  • 返回: 机器人基本信息(控制器版本,机型,轴数)

powerState()​

def powerState(self, ec: dict) -> PowerState:

机器人上下电以及急停状态

  • 参数: [out] ec: 错误码
  • 返回:
    • on - 上电
    • off - 下电
    • estop - 急停
    • gstop - 安全门打开

setPowerState()​

def setPowerState(self, on: bool, ec: dict) -> None:

机器人上下电。注:只有无外接使能开关或示教器的机器人才能手动模式上电。

  • 参数:
    • [in] on: true-上电|false-下电
    • [out] ec: 错误码

operateMode()​

def operateMode(self, ec: dict) -> OperateMode:

查询机器人当前操作模式

  • 参数: [out] ec: 错误码
  • 返回: 手动|自动

setOperateMode()​

def setOperateMode(self, mode: OperateMode, ec: dict) -> None:

切换手自动模式

  • 参数:
    • [in] mode: manual - 手动/ automatic - 自动
    • [out] ec: 错误码

operationState()​

def operationState(self, ec: dict) -> OperationState:

查询机器人当前运行状态(空闲,运动中,拖动开启等)

  • 参数: [out] ec: 错误码
  • 返回: 运行状态枚举类

posture()​

def posture(self, ct: CoordinateType, ec: dict) -> [list[float]]:

获取机器人法兰或末端的当前位姿

  • 参数:
    • [in] ct 坐标系类型
      • flangeInBase:法兰相对于基坐标系;
      • endInRef :末端相对于外部参考坐标系。例如,当设置了手持工具及外部工件后,该坐标系类型 - 返回:的是工具相对于工件坐标系的坐标。
    • [out] ec: 错误码
  • 返回: double 数组,[X , Y , Z , Rx , Ry , Rz ],其中平移量单位为米旋转量单位为弧度

cartPosture()​

def cartPosture(self, ct: CoordinateType, ec: dict) -> CartesianPosition:

获取机器人法兰或末端的当前位姿

  • 参数: :
    • [in] ct 坐标系类型
    • [out] ec: 错误码
  • 返回:当前笛卡尔位置

jointPos()​

def jointPos(self, ec: dict) -> list[float]:

机器人当前轴角度。本体单位 rad。外部轴、导轨、附加轴单位 rad 或 m。

  • 参数: [out] ec: 错误码
  • 返回: 关节角度值,和外部轴值

jointVel()​

def jointVel(self, ec: dict) -> list[float]:

机器人当前关节速度。本体单位 rad/s。外部轴、导轨、附加轴单位 rad/s 或 m/s。

  • 参数: [out] ec: 错误码
  • 返回: 关节速度

jointTorque()​

def jointTorque(self, ec: dict) -> list[float]:

关节力传感器数值,单位: Nm

  • 参数: [out] ec: 错误码
  • 返回: 力矩值

baseFrame()​

def baseFrame(self, ec: dict) -> list[float]:

用户定义的基坐标系, 相对于世界坐标系

  • 参数: [out] ec: 错误码
  • 返回: double 数组, [X, Y, Z, Rx, Ry, Rz],其中平移量单位为米旋转量单位为弧度

setBaseFrame()​

def setBaseFrame(self, frame: Frame, ec: dict) -> None:

设置基坐标系, 设置后仅保存数值,重启控制器后生效

  • 参数:
    • [in] frame 坐标系,默认使用自定义安装方式
    • [out] ec: 错误码

toolset()​

def toolset(self, ec: dict) -> Toolset:

查询当前工具工件组信息

注解 此工具工件组仅为 SDK 运动控制使用, 不与 RL 工程相关

  • 参数: [out] ec: 错误码
  • 返回: 见 Toolset 数据结构

setToolset() [1/2]​

def setToolset(self, toolset: Toolset, ec: dict) -> None:

设置工具工件组信息

注解 此工具工件组仅为SDK运动控制使用, 不与RL工程相关。设置后RobotAssist右上角会显示“toolx", "wobjx", 状态监控显示的末端坐标也会变化。除此接口外, 如果通过 RobotAssist 更改默认工具工件(右上角的选项), 该工具工件组也会相应更改.

  • 参数:
    • [in] toolset 工具工件组信息
    • [out] ec: 错误码

setToolset() [2/2]​

def setToolset(self, toolName: str, wobjName: str, ec: dict) -> Toolset:

使用已创建的工具和工件,设置工具工件组信息

注解 设置前提: 已加载一个 RL 工程,且创建了工具和工件。否则,只能设置为默认的工具工件,即"tool0"和"wobj0"。一组工具工件无法同时为手持或外部;如果有冲突,以工具的位置为准,例如,工具工件同时为手持,不会返回错误,但是工件的坐标系变成了外部

  • 参数:
    • [in] toolName 工具名称
    • [in] wobjName 工件名称
    • [out] ec: 错误码
  • 返回:设置后的工具工件组。设置失败时返回 Toolset 的默认值 0

model()​

def model(self):

获取与当前机器人轴数、机型匹配的运动学模型实例(xCoreSDK_python.model 包中的 Model_0_* 为工业、Model_1_* 为协作)。CMake 选项 XMATE_MODEL 打开时(编译宏 XMATEMODEL_LIB_SUPPORTED),协作机型的 model() 改为返回 xmateModel_1_5 / xmateModel_1_6 / xmateModel_1_7。该类继承逆解和正解,并带有下文「8 模型库」中的接口。该选项默认关闭。

  • 返回:模型对象,具体类型由机型决定。

calcIk()​

先 m = robot.model(),再在 m 上调用。模型类重载示例:

def calcIk(self, posture: CartesianPosition, ec: dict) -> list[float]: ...
def calcIk(self, posture: CartesianPosition, toolset: Toolset, ec: dict) -> list[float]: ...

根据位姿计算逆解(单解)。

  • 参数:
    • [in] posture 机器人末端位姿,相对于外部参考坐标系
    • [in] toolset 可选,给定工具工件坐标系下的逆解
    • [out] ec: 错误码
  • 返回:轴角度,单位弧度;列表长度等于机器人轴数。

calcFk()​

def calcFk(self, joints: list[float], ec: dict) -> CartesianPosition:
def calcFk(self, joints: list[float], toolset: Toolset, ec: dict) -> CartesianPosition:

在 robot.model() 返回的实例上调用。根据轴角度计算正解。

  • 参数:
    • [in] joints 关节角度,单位弧度,长度等于轴数
    • [in] toolset 可选
    • [out] ec: 错误码
  • 返回:末端相对于外部参考坐标系的位姿。

calcAllIkSolutions()​

在 robot.model() 返回的实例上调用。

def calcAllIkSolutions(self, posture: CartesianPosition, confs: list, ec: dict) -> list[list[float]]:

计算笛卡尔位姿的全部逆解;posture 为法兰相对基坐标系,其它坐标系需自行转换。不支持 xMateSR(XMS)。

  • 参数:
    • [in] confs 调用方传入的列表,成功时由接口填入与每组解对应的 confdata(list[list[int]])
    • [out] ec: 错误码(如奇异、超限位、超范围等)
  • 返回:多组关节角(弧度);仅当错误码为 0 时有效。

calibrateFrame ()​

def calibrateFrame(self, type: FrameType, points: list[list[float]], is_held: bool, ec: dict, base_aux: typing.Annotated[list[float], pybind11_stubgen.typing_ext.FixedSize(3)] = [0.0, 0.0, 0.0]) -> FrameCalibrationResult:

坐标系标定 (N 点标定)

  • 注解 各坐标系类型支持的标定方法及注意事项:
    1. 工具坐标系: 三点/四点/六点标定法
    2. 工件坐标系: 三点标定。标定结果不会相对用户坐标系做变换,即,若为外部工件, - 返回:的结果是相对于基坐标系的。
    3. 基坐标系: 六点标定。标定前请确保动力学约束和前馈已关闭。 若标定成功(无错误码),控制器会自动保存标定结果,重启控制器后生效。
    4. 导轨基坐标系: 三点标定。若标定成功(无错误码),控制器会自动保存标定结果,重启控制器后生效。
  • 参数:
    • [in] points 轴角度列表,列表长度为 N。例如,使用三点法标定工具坐标系,应传入 3 组轴角度。轴角度的单位是弧度。
    • [in] is_held true - 机器人手持 | false - 外部。仅影响工具/工件的标定
    • [in] base_aux 基坐标系标定时用到的辅助点, 单位[米]
    • [out] ec: 错误码
  • 返回: 标定结果,当错误码没有被置位时,标定结果有效

clearServoAlarm()​

def clearServoAlarm(self, ec: dict) -> None:

清除伺服报警

  • 参数:[out] ec: 错误码,当有伺服报警且清除失败的情况下错误码置为-1

enableCollisionDetection()(协作机型)​

def enableCollisionDetection(self, sensitivity: list[float], behaviour: StopLevel, fallback_compliance: float, ec: dict) -> None:

设置碰撞检测相关参数, 打开碰撞检测功能(协作机器人;sensitivity 长度与轴数一致)。

  • 参数:
    • [in] sensitivity 碰撞检测灵敏度,范围 0.01-2.0
    • [in] behaviour 碰撞后机器人行为, 支持 stop1(安全停止, stop0 和 stop1 处理方式相同)和 stop2(触发暂停), suppleStop(柔顺停止)
    • [in] fallback_compliance
      1. 碰撞后行为是安全停止或触发暂停时,该参数含义是碰撞后回退距离,单位: 米
      2. 碰撞后行为是柔顺停止时,该参数含义是柔顺度,范围 [0.0, 1.0]
    • [out] ec: 错误码

enableCollisionDetection()(工业六轴 StandardRobot)​

def enableCollisionDetection(self, sensitivity: list[float], fallback: float, ec: dict) -> None:

工业机型仅支持 stop1(安全停止);无 behaviour 参数。sensitivity 为长度 6 的数组。

disableCollisionDetection()​

def disableCollisionDetection(self, ec: dict) -> None:

关闭碰撞检测功能

  • 参数: [out] ec: 错误码

getSoftLimit()​

def getSoftLimit(self, limits: PyTypeVectorArrayDouble2, ec: dict) -> bool:

获取当前软限位数值

  • 参数:
    • [out] limits 各轴软限位 [下限, 上限],单位: 弧度
    • [out] ec: 错误码
  • 返回: true - 已打开 | false - 已关闭

setSoftLimit()​

def setSoftLimit(self, enable: bool, ec: dict, limits: list[list[float]]) -> None:

设置软限位。

  • 参数:
    • [in] enabletrue - 打开 | false - 关闭。
    • [out] ec: 错误码
    • [in] limits 各轴[下限, 上限],单位:弧度。
      1. 当 limits 为默认值时,视为仅打开软限位不修改数值; 不为默认值时,先修改软限位再打开
      2. 关闭软限位时不会修改限位数值

queryControllerLog()​

def queryControllerLog(self, count: int, level: set[LogInfoLevel], ec: dict, offset: int = 0) -> list[LogInfo]:

查询控制器最新的日志

  • 参数:
    • [in] count 查询个数,上限是 10 条
    • [in] level 指定日志等级,空集合代表不指定
    • [in] offset 偏移条数;0 表示从最新一条起查,10 表示从第 11 条起查
    • [out] ec: 错误码
  • 返回: 日志信息

recoverState()​

def recoverState(self, item: int, ec: dict) -> None:

根据选项恢复机器人状态

  • 参数:
    • [in] item 恢复选项,1:急停恢复
    • [out] ec: 错误码

rebootSystem()​

def rebootSystem(self, ec: dict) -> None:

重启工控机。在自动模式、上电状态、运动和非空闲状态下不允许重启。

  • 参数:[out] ec: 错误码

shutdownSystem()​

def shutdownSystem(self, ec: dict) -> None:

关闭工控机。在自动模式、上电状态、运动和非空闲状态下不允许关闭。控制柜断电后重新上电才能重新启动控制器软件。

  • 参数:[out] ec: 错误码

setConnectionHandler()​

def setConnectionHandler(self, handler: Callable[[bool], None]) -> None:

设置与控制器连接状态变化的回调。

  • 参数:
    • [in] handler True 表示已连接,False 表示断开

setTeachPendantMode()​

def setTeachPendantMode(self, enable: bool, ec: dict) -> None:

设置示教器模式开关;阻塞直至切换完成(约 2 秒量级超时)。运动中等情况可能切换失败。

  • 参数:
    • [in] enable True 启用示教器模式,False 关闭
    • [out] ec: 错误码

getRobotCfg_DHparam()​

def getRobotCfg_DHparam(self, get_nominal: bool, ec: dict) -> list[float]:

读取 DH 参数。

  • 参数:
    • [in] get_nominal True 标称参数,False 优化后或当前设置(一般建议 False)
    • [out] ec: 错误码
  • 返回:依次为各轴 Alpha[°]、A[mm]、D[mm]、Theta[°] 串联的一维列表;仅当错误码为 0 时有效。

getExtAxisInfo()​

def getExtAxisInfo(self, name: str, info: str, value: PyTypeInt | PyTypeBool | PyTypeDouble | PyString, ec: dict) -> None:

读取附加轴信息。name 为 axis1~axis6;info 为字段名(如 ext_data_number、zero_value、max_speed、driver_name 等,详见类型桩)。

  • 参数:[out] value 由调用方传入的输出容器,类型需与所查字段一致。

getMechUnit()​

def getMechUnit(self, name: str, info: str, value: PyTypeBool | PyTypeVectorString | PyTypeInt | PyString, ec: dict) -> None:

读取机械单元参数。name 为 u1~u6。info 与 value 类型对应:

  • activation、enable:bool,机械单元是否激活、是否启用
  • axes_info:轴名称列表,顺序与设置顺序相同
  • fixed_name:机械单元固定名称;unit_name:自定义机械单元名(str)
  • mech_link_type:int,0 基座轴,1 变位机,2 伺服焊枪,3 法兰附加轴
  • 参数:[out] value 输出容器,类型与 info 匹配。

setRailParameter()​

def setRailParameter(self, name: str, value: list[float], ec: dict) -> None:

设置导轨参数

  • 模板参数: 参数类型
  • 参数:
    • [in] name: 参数名,见 value 说明
    • [in] value:
      参数:参数名数据类型
      开关enablebool
      基坐标系baseFrameFrame
      导轨名称namestr
      编码器分辨率encoderResolutionint
      减速比reductionRatiodouble
      电机最大转速(rpm)motorSpeedint
      软限位(m), [下限,上限]softLimitlist[float]
      运动范围(m), [下限,上限]rangelist[float]
      最大速度(m/s)maxSpeeddouble
      最大加速度(m/s^2)maxAccdouble
      最大加加速度(m/s^3)maxJerkdouble

getRailParameter()​

def getRailParameter(self, name: str, value: PyTypeDouble, ec: dict) -> None:

读取导轨参数

  • 模板参数: 参数类型
  • 参数:
    • [in] name 参数名,见 setRailParameter()
    • [out] value 参数数值,见 setRailParameter()
    • [out] ec: 错误码,参数名不存在或数据类型不匹配返回错误码

configNtp()​

def configNtp(self, server_ip: str, ec: dict) -> None:

配置 NTP。非标配功能,需要额外安装

  • 参数:
    • [in] server_ip NTP 服务端 IP
    • [out] ec: 错误码, NTP 未正确安装,或 IP 地址格式错误

syncTimeWithServer()​

def syncTimeWithServer(self, ec: dict) -> None:

手动同步一次时间,远端 IP 是通过 configNtp 配置的。耗时几秒钟,阻塞等待同步完成,接口预设的超时时间是 12 秒

  • 参数: [out] ec: 错误码。NTP 服务未正确安装,或无法和服务端同步

sdkVersion()​

def sdkVersion() -> str:

查询 xCore-SDK 版本

  • 返回: 版本号

startReceiveRobotState()​

def startReceiveRobotState(self, interval: datetime.timedelta, fields: list[str]) -> None:

让机器人控制器开始发送实时状态数据。阻塞等待收到第一帧消息,超时时间为 3 秒。

  • 参数:
    • [in] interval 控制器发送状态数据的间隔。允许 1ms、2ms、4ms、8ms、1s
    • [in] fields 接收的状态数据名,最大总长度 1024 字节
  • 异常:
    • RealtimeControlException:设置了不支持的状态数据;或机器人无法开始发送数据;或总长度超过 1024
    • RealtimeStateException:已经开始发送数据;或超时后仍未收到第一帧数据

updateRobotState()​

def updateRobotState(self, timeout: datetime.timedelta) -> int:

在实时模式下接收一帧机器人状态数据;周期调用前应先调用本函数。建议按控制器配置的发送频率调用。timeout 使用 datetime.timedelta(例如 from datetime import timedelta)。

  • 参数:
    • [in] timeout 等待超时
  • 返回:收到的数据长度;超时未收到则为 0
  • 异常:解析失败等会抛出 RealtimeControlException

getStateData()​

def getStateData(self, fieldName: str, data: PyTypeUInt8 | PyTypeUInt64 | PyTypeDouble | PyTypeVectorDouble | PyTypeVectorBool, ...) -> int:

从最近一帧状态中读取字段。fieldName 使用 RtSupportedFields 中实际暴露的常量:

  • jointPos_m:关节角度,单位 rad
  • tcpPose_m:末端位姿,相对基坐标系,行优先齐次变换矩阵
  • tcpPoseAbc_m:末端位姿 [X, Y, Z, Rx, Ry, Rz]
  • elbow_m:臂角,单位 rad
  • keypads:末端按键状态
  • exJointPos_m:外部轴位置,关节 rad、导轨 m
  • exJointVel_m:外部轴速度,关节 rad/s、导轨 m/s
  • exMotor_m:外部轴电机位置

向量类型需传入长度参数(见类型桩重载)。

  • 返回:操作结果状态码(见实现约定)

stopReceiveRobotState()​

def stopReceiveRobotState(self) -> None:

停止接收实时状态并让控制器停止发送,便于重新配置订阅字段。

2 运动控制(非实时模式)​

setMotionControlMode()​

def setMotionControlMode(self, mode: MotionControlMode, ec: dict) -> None:

设置运动控制模式

  • 注: 在调用各运动控制接口之前, 须设置对应的控制模式。
  • 参数:
    • [in] mode:MotionControlMode.Idle、NrtCommandMode、NrtRLTask、RtCommandMode
    • [out] ec: 错误码

moveReset()​

def moveReset(self, ec: dict) -> None:

运动重置, 清空已发送的运动指令, 清除执行信息

  • 注解: Robot 类在初始化时会调用一次运动重置。RL 程序和 SDK 运动指令切换控制,需要先运动重置。
  • 参数: [out] ec 错误码

stop()​

def stop(self, ec: dict) -> None:

暂停机器人运动; 暂停后可调用 moveStart()继续运动。若需要完全停止,不再执行已添加的指令,可调用moveReset()

  • 注解: 目前支持 stop2 停止类型, 规划停止不断电, 参见 StopLevel。 调用此接口后, 暂停后可调用 moveStart() 继续运动。若需要完全停止,不再执行已添加的指令,可调用 moveReset()
  • 参数: [out] ec: 错误码

pause()​

def pause(self, ec: dict) -> None:

暂停机器人运动,语义与 stop() 相同。

  • 参数:[out] ec: 错误码

moveStart()​

def moveStart(self, ec: dict) -> None:

开始/继续运动

  • 参数: [out] ec: 错误码

moveAppend() [1/2]​

def moveAppend(self, cmds: list[MoveJCommand], cmdID: PyString, ec: dict) -> None:
def moveAppend(self, cmds: list[MoveAbsJCommand], cmdID: PyString, ec: dict) -> None:
def moveAppend(self, cmds: list[MoveLCommand], cmdID: PyString, ec: dict) -> None:
def moveAppend(self, cmds: list[MoveCCommand], cmdID: PyString, ec: dict) -> None:
def moveAppend(self, cmds: list[MoveCFCommand], cmdID: PyString, ec: dict) -> None:
def moveAppend(self, cmds: list[MoveSPCommand], cmdID: PyString, ec: dict) -> None:

添加单条或多条运动指令, 添加后调用 moveStart()开始运动

  • 参数
    • [in] cmds 指令列表, 允许的个数为 1-100, 须为同类型的指令
    • [out] cmdID 本条指令的 ID, 可用于查询指令执行信息
    • [out] ec 错误码, 仅反馈指令发送前的错误, 包括: 1) 网络连接问题; 2) 指令个数不符;

moveAppend() [2/2]​

def moveAppend(self, cmd: MoveAbsJCommand, cmdID: PyString, ec: dict) -> None:
def moveAppend(self, cmd: MoveLCommand, cmdID: PyString, ec: dict) -> None:
def moveAppend(self, cmd: MoveJCommand, cmdID: PyString, ec: dict) -> None:
def moveAppend(self, cmd: MoveCFCommand, cmdID: PyString, ec: dict) -> None:
def moveAppend(self, cmd: MoveCCommand, cmdID: PyString, ec: dict) -> None:
def moveAppend(self, cmd: MoveSPCommand, cmdID: PyString, ec: dict) -> None:
def moveAppend(self, cmd: MoveWaitCommand, cmdID: PyString, ec: dict) -> None:

添加单条运动指令, 添加后调用 moveStart()开始运动

  • 参数:
    • [in] cmd 单条指令
    • [out] cmdID 本条指令的 ID, 可用于查询指令执行信息
    • [out] ec 错误码, 仅反馈指令发送前的错误, 包括: 1) 网络连接问题; 2) 指令个数不符;

executeCommand()​

def executeCommand(self, cmds: list[MoveAbsJCommand], ec: dict) -> None:
def executeCommand(self, cmds: list[MoveLCommand], ec: dict) -> None:
def executeCommand(self, cmds: list[MoveJCommand], ec: dict) -> None:
def executeCommand(self, cmds: list[MoveCCommand], ec: dict) -> None:
def executeCommand(self, cmds: list[MoveCFCommand], ec: dict) -> None:
def executeCommand(self, cmds: list[MoveSPCommand], ec: dict) -> None:

执行单条或多条运动指令,调用后机器人立刻开始运动

  • 参数:
    • [in] cmds 指令列表, 允许的个数为 1-1000
    • [out] ec 错误码, 仅反馈执行前的错误, 包括: 1) 网络连接问题; 2) 指令个数不符; 3) 机器人当前状态下无法运动,例如没有上电

setDefaultSpeed()​

def setDefaultSpeed(self, speed: int, ec: dict) -> None:

设定默认运动速度,初始值为 100

  • 注解: 该数值表示末端最大线速度(单位 mm/s), 自动计算对应关节速度
  • 参数:
    • [in] speed 该接口不对参数进行范围限制。末端线速度的实际有效范围分别是 5-4000(协作), 5-7000(工业)。 关节速度百分比划分为 5 个的范围:
      • < 100 : 10% ;
      • 100 ~ 200 : 30% ;
      • 200 ~ 500 : 50% ;
      • 500 ~ 800 : 80% ;
      • 800 : 100%

    • 空间旋转速度为 200°/s
    • [out] ec 错误码

setDefaultZone()​

def setDefaultZone(self, zone: int, ec: dict) -> None:

设定默认转弯区

  • 注解: 该数值表示运动最大转弯区半径(单位:mm), 自动计算转弯百分比. 若不设置, 则为 0 (fine, 无转弯区)
  • 参数:
    • [in] zone: 该接口不对参数进行范围限制。转弯区半径大小实际有效范围是 0-200。 转弯百分比划分 4 个范围:
      • < 1 : 0 (fine) ;
      • 1 ~ 20 : 10% ;
      • 20 ~ 60 : 30% ;
      • 60 : 100%

    • [out] ec: 错误码

setDefaultConfOpt()​

def setDefaultConfOpt(self, forced: bool, ec: dict) -> None:

设置是否使用轴配置数据(confData)计算逆解。初始值为 false

  • 参数:
    • [in] forcedtrue -使用运动指令的 confData 计算笛卡尔点位逆解, 如计算失败则返回错误; false - 不使用,逆解时会选取机械臂当前轴角度的最近解
    • [out] ec 错误码

setMaxCacheSize()​

def setMaxCacheSize(self, number: int, ec: dict) -> None:

设置最大缓存指令个数,指发送到控制器待规划的路径点个数,允许的范围 [1, 1000],初始值为 300。

  • 注解: 如果轨迹多为短轨迹,可以调大这个数值,避免因指令发送不及时导致机器人停止运动(停止后如果有未执行的指令,可 moveStart() 继续;

  • 参数:

    • [in] number: 个数
    • [out] ec 错误码

setAutoIgnoreZone()​

def setAutoIgnoreZone(self, enable: bool, ec: dict) -> None:

设置是否在规划时自动取消转弯区;初始为 true。

  • 参数:
    • [in] enable true 自动取消转弯区,false 不自动取消
    • [out] ec: 错误码

adjustSpeedOnline()​

def adjustSpeedOnline(self, scale: float, ec: dict) -> None:

动态调整机器人运动速率,非实时模式时生效。

  • 参数:
    • [in] scale: 运动指令的速度的比例,范围 0.01 - 1。当设置 scale 为 1 时,机器人将以路径原本速度运动。
    • [out] ec: 错误码

getAcceleration()​

def getAcceleration(self, acc: PyTypeDouble, jerk: PyTypeDouble, ec: dict) -> None:

读取当前加/减速度和加加速度

  • 参数:
    • [out] acc: 系统预设加速度的百分比
    • [out] jerk: 系统预设的加加速度的百分比
    • [out] ec: 错误码

adjustAcceleration()​

def adjustAcceleration(self, acc: float, jerk: float, ec: dict) -> None:

调节运动加/减速度和加加速度。如果在机器人运动中调用,当前正在执行的指令不生效,下一条指令生效

  • 参数:
    • [in] acc: 系统预设加速度的百分比,范围[0.2, 1.5], 超出范围不会报错,自动改为上限或下限值
    • [in] jerk: 系统预设的加加速度的百分比,范围[0.1, 2], 超出范围不会报错,自动改为上限或下限值
    • [out] ec: 错误码

setEventWatcher()​

def setEventWatcher(self, eventType: Event, callback: typing.Callable[[dict], None], ec: dict) -> None:

设置接收事件的回调函数

  • 参数:
    • [in] eventType: 事件类型(含 moveExecution、safety、rlExecution、logReporter)
    • [in] callback: 处理事件的回调函数。说明:
      1. 对于Event::moveExecution, 回调函数在同一个线程执行, 请避免函数中有执行时间较长的操作;
      2. Event::safety 则每次独立线程回调, 没有执行时间的限制
    • [out] ec: 错误码

setNoneEventWatcher()​

def setNoneEventWatcher(self, eventType: Event, ec: dict) -> None:

取消指定 eventType 上已注册的回调。

  • 参数:
    • [in] eventType: 与 setEventWatcher 一致
    • [out] ec: 错误码

queryEventInfo()​

def queryEventInfo(self, eventType: Event, ec: dict) -> dict:

查询事件信息。与 setEventWatcher()回调时的提供的信息相同,区别是这个接口是主动查询的方式

  • 参数:
    • [in] eventType: 事件类型
    • [out] ec: 错误码
  • 返回: 事件信息。字段见类型附录 EventInfoKey

startJog()​

def startJog(self, space: JogOptSpace, rate: float, step: float, index: int, direction: bool, ec: dict) -> None:

开始 jog 机器人,需要切换到手动操作模式。

  • 注解: 调用此接口并且机器人开始运动后,无论机器人是否已经自行停止,都必须调用 stop()来结束 jog 操作,否则机器人会一直处于 jog 的运行状态。
  • 参数:
    • [in] space jog 参考坐标系。
      1. 工具/工件坐标系使用原则同 setToolset();
      2. 工业六轴机型和 xMateCR/SR 六 轴 机 型 支 持 两 种 奇 异 规 避 方 式 Jog:Space::singularityAvoidMode, Space::baseParallelMode
      3. CR5 轴机型支持平行基座模式 Jog:Space::baseParallelMode
    • [in] rate: 速率, 范围 0.01 - 1
    • [in] step: 步长。单位: 笛卡尔空间-毫米 | 轴空间-度。步长大于 0 即可,不设置上限, 如果机器人机器人无法继续 jog 会自行停止运动。
    • [in] index 根据不同的 space,该参数含义如下:
      1. 世界坐标系,基坐标系,法兰坐标系,工具工件坐标系: a) 6 轴机型: 0~5 分别对应 X, Y, Z, Rx, Ry, Rz。>5 代表外部轴(若有) b) 7 轴机型 6 代表肘关节, >6 代表外部轴(若有)
      2. 轴空间: 关节序号,从 0 开始计数
      3. 奇异规避模式,平行基座模式: a) 6 轴机型:05 分别对应 X, Y, Z, J4(4 轴), Ry, J6(6 轴); b) 5 轴机型:04 分别对应 X, Y, Z, Ry, J5(5 轴)
    • [in] direction 根据不同的 space 和 index,该参数含义如下:
      1. 奇异规避模式 J4: true - ±180° | false - 0°;
      2. 平行基座模式 J4 & Ry: true - ±180° | false - 0°
      3. 其它,true - 正向 | false - 负向
    • [out] ec 错误码

startJogWithExt()​

def startJogWithExt(self, space: JogOptSpace, rate: float, step: float, index: int, direction: bool, fixed_name: str, ec: dict, is_ext: bool = True) -> None:

在 startJog 基础上指定机械单元或外部轴:fixed_name 与 index、is_ext 组合使用。其余参数含义同 startJog()。

  • 参数:
    • [in] fixed_name 例如与 index 配合:fixed_name 为任意字符且 is_ext 为 false、index 为 0 时 Jog 本体第一轴;fixed_name 为 u1 且 index 为 0 时 Jog 机械单元 u1 的第一轴。
    • [in] is_ext 是否为外部轴 Jog,默认 true。

setAvoidSingularity()​

def setAvoidSingularity(self, method: AvoidSingularityMethod, enable: bool, limit: float, ec: dict) -> None:

xMateRobot:打开/关闭奇异点规避。只适用于部分机型:

  1. 四轴锁定:工业六轴,xMateCR 和 xMateSR 六轴
  2. 牺牲姿态:所有六轴
  3. 轴空间插补:工业六轴
  • 参数:
    • [in] method: 奇异规避方式
    • [in] enable: true - 打开 | false - 关闭。四轴锁定打开前须保证 4 轴处于零位
    • [in] limit:
      1. 牺牲姿态:允许的姿态误差,范围 (0, PI*2],单位弧度
      2. 轴空间插补:规避半径,范围 [0.005, 10],单位米
      3. 四轴锁定:无参数
    • [out] ec: 错误码
def setAvoidSingularity(self, method: AvoidSingularityMethod, enable: bool, threshold: float, ec: dict) -> None:

StandardRobot:三种规避方式都支持。

  • 参数:
    • [in] method: 奇异规避方式
    • [in] enable: true - 打开 | false - 关闭
    • [in] threshold:
      1. 牺牲姿态:允许的姿态误差,范围 (0, PI*2],单位弧度
      2. 轴空间插补:规避半径,范围 [0.005, 10],单位米
      3. 四轴锁定:无参数
    • [out] ec: 错误码

getAvoidSingularity()​

def getAvoidSingularity(self, method: AvoidSingularityMethod, ec: dict) -> bool:

查询是否处于规避奇异点的状态

  • 参数:
    • [in] method: 奇异规避的方式
    • [out] ec: 错误码
  • 返回: true - 已打开 | false – 已关闭

checkPath() [1/3]​

def checkPath(self, start: CartesianPosition, start_joint: list[float], target: CartesianPosition, ec: dict) -> list[float]:

检验笛卡尔轨迹是否可达,直线轨迹。支持导轨,返回的目标轴角为轴数+外部轴数

  • 参数:
    • [in] start: 起始点
    • [in] start_joint: 起始轴角 [弧度]
    • [in] target: 目标点
    • [out] ec: 错误码
  • 返回: 计算出的目标轴角,仅当无错误码时有效

checkPath() [2/3]​

def checkPath(self, start_joint: list[float], points: list[CartesianPosition], target_joint_calculated: list, ec: dict) -> int:

校验多个直线轨迹

  • 参数:
    • [in] start_joint: 起始轴角,单位[弧度]
    • [in] points: 笛卡尔点位,至少需要 2 个点,第一个点是起始点
    • [out] target_joint_calculated: 若校验通过。返回计算出的目标轴角
    • [out] ec: 校验失败的原因
  • 返回: 若校验失败,返回 points 中出错目标点的下标。其它情况返回 0

checkPath() [3/3]​

def checkPath(self, start: CartesianPosition, start_joint: list[float], aux: CartesianPosition, target: CartesianPosition, ec: dict, angle: float = 0.0, rot_type: MoveCFCommandRotType = ...) -> list[float]:

检验笛卡尔轨迹是否可达,包括圆弧,全圆。支持导轨,返回的目标轴角为轴数+外部轴数

  • 参数:
    • [in] start: 起始点
    • [in] start_joint: 起始轴角 [弧度]
    • [in] aux: 辅助点
    • [in] target: 目标点
    • [out] ec: 错误码
    • [in] angle: 全圆执行角度,不等于零时代表校验全圆轨迹
    • [in] rot_type: 全圆旋转类型,默认 constPose(固定位姿)
  • 返回: 计算出的目标轴角,仅当无错误码时有效

3 通信相关​

getDI()​

def getDI(self, board: int, port: int, ec: dict) -> bool:

查询数字量输入信号值。

  • 参数:
    • [in] board:IO 板序号。
    • [in] port:信号端口号。
    • [out] ec:错误码。
  • 返回:true - 开,false - 关。

getDO()​

def getDO(self, board: int, port: int, ec: dict) -> bool:

查询数字输出量信号值。

  • 参数:
    • [in] board:IO 板序号。
    • [in] port:信号端口号。
    • [out] ec:错误码。
  • 返回:true - 开,false - 关。

setDI()​

def setDI(self, board: int, port: int, state: bool, ec: dict) -> None:

设置数字量输入信号值,仅当输入仿真模式打开时可以设置(见 setSimulationMode())。

  • 参数:
    • [in] board:IO 板序号。
    • [in] port:信号端口号。
    • [in] state:true - 开,false - 关。
    • [out] ec:错误码。

setDO()​

def setDO(self, board: int, port: int, state: bool, ec: dict) -> None:

设置数字量输出信号值。

  • 参数:
    • [in] board:IO 板序号。
    • [in] port:信号端口号。
    • [in] state:true - 开,false - 关。
    • [out] ec:错误码。

getAI()​

def getAI(self, board: int, port: int, ec: dict) -> float:

读取模拟量输入信号值

  • 参数:
    • [in] board IO 板序号
    • [in] port 信号端口号
    • [out] ec 错误码
  • 返回:信号值

setAO()​

def setAO(self, board: int, port: int, value: float, ec: dict) -> None:

设置模拟量输出信号

  • 参数:
    • [in] board IO 板序号
    • [in] port 信号端口号
    • [in] value 输出值
    • [out] ec 错误码

readRegister()​

def readRegister(self, name: str, index: int, value: PyTypeBool | PyTypeInt | PyTypeFloat | PyTypeVectorBool | PyTypeVectorInt | PyTypeVectorFloat, ec: dict) -> None:

读取寄存器值。可读取单个寄存器,寄存器数组,或按索引读取寄存器数组。 如果要读取整个寄存器数组,value 传入对应类型的 list,index 值被忽略。

  • 参数:
    • [in] name 寄存器名称
    • [in] index 按索引读取寄存器数组中元素,从 0 开始。下列两种情况会报错:1)索引超出数组长度;2)寄存器不是数组但 index 大于 0
    • [out] value 输出容器,类型须与寄存器数据类型一致,可为 bool / int / float 及对应向量类型
    • [out] ec 错误码

writeRegister()​

def writeRegister(self, name: str, index: int, value: bool, ec: dict) -> None:

写寄存器值。可写入单个寄存器,寄存器数组,或按索引写入寄存器数组中某一元素。如果要写入整个寄存器数组,value 传入对应类型的 list,index 值被忽略。

  • 参数:
    • [in] name 寄存器名称
    • [in] index 数组索引,从 0 开始。下列两种情况会报错:1)索引超出数组长度;2)寄存器不是数组但 index 大于 0
    • [in] value 写入的数值,允许的类型有 bool/int/float,和 list[bool/int/float]
    • [out] ec 错误码

setxPanelVout()​

def setxPanelVout(self, opt: int, ec: dict) -> None:

设置 xPanel 对外供电模式。注:仅部分机型支持 xPanel 功能,不支持的机型会返回错误码

  • 参数:
    • [in] opt模式
    • [out] ec 错误码

setSimulationMode()​

def setSimulationMode(self, state: bool, ec: dict) -> None:

设置输入仿真模式

  • 参数:
    • [in] state true - 打开 | false - 关闭
    • [out] ec 错误码

getKeypadState()​

def getKeypadState(self, ec: dict) -> KeyPadState:

获取末端按键状态,不支持的机型会返回错误码

  • 参数:
    • [out] ec 错误码
  • 返回:末端按键的状态。末端按键编号见《xCore 机器人控制系统使用手册》末端把手的图示。

setxPanelRS485()​

def setxPanelRS485(self, opt: int, if_rs485: bool, ec: dict) -> None:

配置末端供电模式,并切换是否启用末端 485 通信,CR/SR 等使用 485 功能前需调用,AR机型默认输出24v并开启RS485通信。

  • 参数:
    • [in] opt 对外供电模式,0:不输出,1:保留,2:12V,3:24V
    • [in] if_rs485 是否打开末端 485 通信
    • [out] ec 错误码

xPanelRS485Init()​

def xPanelRS485Init(self, baud: xPanelCommOptRs485Baud, check_bit: xPanelCommOptCheckBit, stop_bit: xPanelCommOptStopBit, ec: dict) -> None:

初始化 xPanel RS485 通信参数(波特率、校验位、停止位),注意AR机型设置完毕后需要重启生效。

  • 参数:
    • [in] baud 波特率,见 xPanelCommOptRs485Baud
    • [in] check_bit none / odd / even
    • [in] stop_bit stopbit1 / stopbit2
    • [out] ec 错误码
  • 说明:AR 机型与其他机型支持的波特率集合不同:
    • AR:4800、9600、19200、38400、57600、115200、2500000
    • 其他:9600、19200、38400、57600、115200、230400、460800、1000000、2000000
    • 不支持的波特率会返回参数超限错误

setxPanelRS485Overtime()​

def setxPanelRS485Overtime(self, overtime_ms: int, ec: dict) -> None:

设置 xPanel RS485 通信超时时间。

  • 参数:
    • [in] overtime_ms 超时时间(ms),范围 50~10000
    • [out] ec 错误码

xPanelCANInit()​

def xPanelCANInit(self, arbitration_baud: xPanelCommOptCanArbitrationBaud, data_baud: xPanelCommOptCanDataBaud, ec: dict) -> None:

初始化 xPanel CAN 通信波特率参数,目前仅支持AR机型使用,设置完毕后需要重启生效。

  • 参数:
    • [in] arbitration_baud b1M / b500k / b250k / b125k
    • [in] data_baud b5M / b4M / b2M / b1M
    • [out] ec 错误码

XPRWModbusRTUReg()​

def XPRWModbusRTUReg(self, slave_addr: int, fun_cmd: int, reg_addr: int, data_type: str, num: int, data_array: PyTypeVectorInt, if_crc_reverse: bool, ec: dict) -> None:

通过 xPanel 末端读写 Modbus RTU 寄存器。

  • 参数:
    • [in] slave_addr 从站地址 0~65535
    • [in] fun_cmd 0x03 / 0x04 / 0x06 / 0x10
    • [in] reg_addr 寄存器地址 0~65535
    • [in] data_type int16 / uint16 / int32 / uint32
    • [in] num 一次连续操作个数。功能码 0x06 时无效。取值范围:
      • CR/ER/SR:末端固件版本 < 301 时,16 位为 [1,3],32 位为 1;末端固件版本 ≥ 301 时,16 位为 [1,59],32 位为 [1,29]
      • AR:16 位为 [1,27],32 位为[1,13]
    • [in/out] data_array 读写缓冲(PyTypeVectorInt)。功能码 0x06 时仅使用 [0];其余须与 num 匹配
    • [in] if_crc_reverse 是否反转 CRC 高低位,默认 False
    • [out] ec 错误码

XPRWModbusRTUCoil()​

def XPRWModbusRTUCoil(self, slave_addr: int, fun_cmd: int, coil_addr: int, num: int, data_array: PyTypeVectorBool, if_crc_reverse: bool, ec: dict) -> None:

通过 xPanel 末端读写 Modbus 线圈或离散输入。

  • 参数:
    • [in] slave_addr 从站地址 0~65535
    • [in] fun_cmd 0x01 / 0x02 / 0x05 / 0x0F
    • [in] coil_addr 线圈或离散输入地址 0~65535
    • [in] num 连续读写个数。功能码 0x05 时无效。取值范围:
      • CR/ER/SR:末端固件版本 < 301 时为 [1,48];末端固件版本 ≥ 301 时为 [1,944]
      • AR:[1,432]
    • [in/out] data_array 布尔缓冲(PyTypeVectorBool)。功能码 0x05 时仅使用 [0]
    • [in] if_crc_reverse 是否反转 CRC 高低位,默认 False
    • [out] ec 错误码

XPRS485SendData()​

def XPRS485SendData(self, send_byte: int, rev_byte: int, send_data: list[int], rev_data: PyTypeVectorInt, ec: dict) -> None:

通过 xPanel 末端直接收发 RTU 协议裸数据(非 Modbus 封装)。

  • 参数:
    • [in] send_byte 发送字节长度;须与 send_data 长度一致
    • [in] rev_byte 期望接收字节长度;调用前 rev_data 长度须与其一致
    • [in] send_data 发送数据
    • [out] rev_data 接收数据
    • [out] ec 错误码
  • 说明:最大字节数随 xPanel 类型变化(CR/ER/SR系列301及以上末端固件版本支持128字节,此前版本支持16字节,非定制版本AR系列支持64字节)

CANReceiveData()​

def CANReceiveData(self, timeout_ms: int, data_type: str, recv_frame: CANFrame, ec: dict) -> None:

通过 xPanel 末端接收 CAN 协议裸数据。

  • 参数:
    • [in] timeout_ms 接收超时时间(ms)
    • [in] data_type int16 / uint16 / uint8
    • [out] recv_frame 接收帧(CANFrame,data 为 list[int],由 data_type 解释)
    • [out] ec 错误码
  • 说明:超时未收到数据时返回失败;frame_format 见 CANFormat,frame_type 见 CANType

CANSendData()​

def CANSendData(self, data_type: str, send_frames: list[CANFrame], ec: dict) -> None:

通过 xPanel 末端发送 CAN 协议裸数据(可一次发送多帧)。

  • 参数:
    • [in] data_type int16 / uint16 / uint8
    • [in] send_frames 待发送帧列表;每帧 data 长度须等于 frame_valid_length
    • [out] ec 错误码
  • 说明:frame_valid_length 合法范围与帧类型、data_type 相关:
    • 经典 CAN + uint8:[1,8];
    • 经典 CAN + int16/uint16:[1,4]
    • CANFD / CANFD 加速 + uint8:[1,8],或 12/16/20/24/32/48/64
    • CANFD / CANFD 加速 + int16/uint16:[1,4],或 6/8/10/12/16/24/32

CANRwData()​

def CANRwData(self, param: CANRwParam, ec: dict) -> list[list[list[int]]]:

BaseCobot 通过 xPanel 末端按序执行多组操作。每组先发送一帧 CAN 数据,随后期望接收一帧或多帧 CAN 数据。

  • 参数
    • [in] param - CANRwParam,param.rw_frames[i].send_data 为第 i 组要发送的原始字节,param.rw_frames[i].rev_frames_per 为该组期望接收的帧数。param.interval_ms 指定组间隔(ms)
    • [out] ec - 传入字典,ec["ec"] 为错误码,ec["message"] 为错误信息。读取结果前先检查错误码,再按实际返回的组数和帧数访问
  • 返回值为 list[list[list[int]]],按组保存实际收到的帧。recv_frames[i][j] 是第 i 组的第 j 帧,内容为原始字节列表

4 RL 工程​

projectsInfo()​

def projectsInfo(self, ec: dict) -> list[RLProjectInfo]:

查询工控机中 RL 工程名称及任务

  • 参数:
    • [out] ec 错误码
  • 返回:工程信息列表,若没有创建工程则返回空列表

loadProject()​

def loadProject(self, name: str, tasks: list[str], ec: dict) -> None:

加载工程

  • 参数:
    • [in] name 工程名称
    • [in] tasks 要运行的任务。该参数必须指定,不能为空,否则无法执行工程。
    • [out] ec 错误码

ppToMain()​

def ppToMain(self, ec: dict) -> None:

程序指针跳转到 main。调用后,等待控制器解析完工程后返回,阻塞时间视工程大小而定,超时时间设定为 10 秒。

  • 参数:
    • [out] ec 错误码。错误码能提供的信息有限,不能反馈如 RL 语法错误、变量不存在等错误。可通过 queryControllerLog()查询错误日志。

runProject()​

def runProject(self, ec: dict) -> None:

开始运行当前加载的工程

  • 参数:
    • [out] ec 错误码

pauseProject()​

def pauseProject(self, ec: dict) -> None:

暂停运行工程

  • 参数:
    • [out] ec 错误码

setProjectRunningOpt()​

def setProjectRunningOpt(self, rate: float, loop: bool, ec: dict) -> None:

更改工程的运行速度和循环模式

  • 参数:
    • [in] rate 运行速率,范围 0.01 - 1
    • [in] loop true - 循环执行 | false - 单次执行
    • [out] ec 错误码

toolsInfo()​

def toolsInfo(self, ec: dict) -> list[WorkToolInfo]:

查询当前加载工程的工具信息

  • 参数:
    • [out] ec 错误码
  • 返回: 工具信息列表, 若未加载任何工程或没有创建工具, 则返回默认工具 tool0 的信息

wobjsInfo()​

def wobjsInfo(self, ec: dict) -> list[WorkToolInfo]:

查询当前加载工程的工件信息

  • 参数:
    • [out] ec 错误码
  • 返回: 工件信息列表, 若未加载任何工程或没有创建工件, 则返回空 list

importProject()​

def importProject(self, file_path: str, overwrite: bool, ec: dict) -> str:

将本地的 RL 工程压缩包导入控制器。阻塞等到导入完成或失败

  • 参数:
    • [in] file_path 本地 .zip 压缩包路径, 文件大小在 10M 以内
    • [in] overwrite 是否覆盖同名文件,是:覆盖;否:自动重命名
    • [out] ec 错误码
  • 返回: 工程名(比如自动重命名,返回重命名之后的)

removeProject()​

def removeProject(self, name: str, ec: dict, remove_all: bool = False) -> None:

删除控制器里的 RL 工程

  • 参数:
    • [in] name 工程名
    • [in] remove_all 是否删除所有工程,缺省值是 false
    • [out] ec 错误码

importFile()​

def importFile(self, file_path: str, dest: str, overwrite: bool, ec: dict) -> str:

导入本地文件到控制器。阻塞等到导入完成或失败

  • 参数:
    • [in] file_path 本地文件路径。文件大小在 10M 以内
    • [in] dest 目标路径
      • 传输单个 RL 工程.mod 文件: project/[工程名]/[任务名]/[mod文件名]
      • 传输 RL 工程.json/.xml/sys 格式的配置文件: project/[工程名]/[文件名]。注意: 配置文件名称不可更改,比如任务文件名必须是"task.xml"
    • [in] overwrite 覆盖同名文件: true - 覆盖 | false - 自动重命名。仅.mod 文件支持自动重命名
    • [out] ec 本地文件不存在; 文件格式错误; 传输失败; 目标路径不符合要求等
  • 返回:导入成功后文件名

removeFiles()​

def removeFiles(self, file_path_list: list[str], ec: dict) -> None:

删除控制器中文件。注: 工程.xml, .json 等配置文件不能删除,只能替换

  • 参数:
    • [in] file_path_list 文件路径的列表, 单个文件路径如下:
        1. 删除某工程某任务下的 .mod 文件: project/[工程名]/[任务名]/[mod 文件名]
        1. 删除某工程某任务: project/[工程名]/[任务名]
    • [out] ec 参数格式错误或网络错误。工程或任务或文件不存在不返回错误码

setToolInfo()​

def setToolInfo(self, tool_info: WorkToolInfo, ec: dict) -> None:

设置全局工具信息,或新建/设置 RL 工程中工具的位姿信息和负载信息

  • 注解:
    1. 全局工具共 16 个,名称固定为 g_tool_0~g_tool_15
    2. 名称不是全局工具的,都视为 RL 工程工具:须先加载工程;不存在则新建,存在则修改。还须同步修改工程的工具配置文件,否则 RL 指令可能无法解析,设置后的数据也不会保存。不建议用本接口设置工程工具
    3. 暂不支持设置工具包络
  • 参数:
    • [in] tool_info 工具信息
    • [out] ec 全局工具一般不会设置失败。工程中工具可能会设置失败,比如给控制器推送了工程的工具配置文件但是没有重新加载工程,工具配置不一致的情况下会返回错误码

setWobjInfo()​

def setWobjInfo(self, wobj_info: WorkToolInfo, ec: dict) -> None:

设置全局工件信息,或新建/设置 RL 工程中工件的位姿信息和负载信息

  • 注解:
    1. 全局工件共 16 个,名称固定为 g_wobj_0~g_wobj_15
    2. 名称不是全局工件的,都视为 RL 工程工件:须先加载工程;不存在则新建,存在则修改。还须同步修改工程的工件配置文件,否则 RL 指令可能无法解析,设置后的数据也不会保存
    3. 暂不支持设置用户坐标系。全局工件默认 g_user_0,工程工件默认 userframe0
  • 参数:
    • [in] wobj_info 工件信息
    • [out] ec 同理设置工具接口,全局工件一般不会设置失败。工程中工件可能会设置失败

5 协作相关​

enableDrag()​

def enableDrag(self, space: int, type: int, ec: dict, enable_drag_button: bool) -> None:

打开拖动

  • 参数:
    • [in] space 拖动空间。0 轴空间,1 笛卡尔空间。轴空间拖动仅支持自由拖拽类型
    • [in] type 拖动类型。0 仅平移,1 仅旋转,2 自由拖拽
    • [out] ec 错误码
    • [in] enable_drag_button true - 打开拖动功能之后可以直接拖动机器人,不需要按住末端按键

disableDrag()​

def disableDrag(self, ec: dict) -> None:

关闭拖动

  • 参数:
    • [out] ec 错误码

setRtNetworkTolerance()​

def setRtNetworkTolerance(self, percent: int, ec: dict) -> None:

设置实时运动指令网络延迟阈值(RobotAssist–RCI「包丢失阈值」),取值 0~100。须在切换到 RtCommandMode 之前调用,否则不生效。

  • 参数:
    • [in] percent 允许丢包/延迟阈值百分比
    • [out] ec: 错误码

startRecordPath()​

def startRecordPath(self, duration: int, ec: dict) -> None:

开始录制路径

  • 参数:
    • [in] duration 路径的时长,单位:秒,范围 1~1800.此时长只做范围检查用,到时后控制器不会停止录制,需要调用 stopRecordPath()来停止
    • [out] ec 错误码

stopRecordPath()​

def stopRecordPath(self, ec: dict) -> None:

停止录制路径, 若录制成功(无错误码)则路径数据保存在缓存中

  • 参数:
    • [out] ec 错误码

cancelRecordPath()​

def cancelRecordPath(self, ec: dict) -> None:

取消录制, 缓存的路径数据将被删除

  • 参数:
    • [out] ec 错误码

saveRecordPath()​

def saveRecordPath(self, name: str, ec: dict, saveAs: str = '') -> None:

保存录制好的路径

  • 参数:
    • [in] name 路径名称
    • [out] ec 错误码
    • [in] saveAs 重命名, 可选参数。 如果已录制好一条路径但没有保存,则用该名字保存路径。如果没有未保存的路径,则将已保存的名为"name"的路径重命名为"saveAs"

replayPath()​

def replayPath(self, name: str, rate: float, ec: dict) -> None:

运动指令-路径回放 和其它运动指令类似, 调用 replayPath 之后, 需调用 moveStart 才会开始运动。

  • 参数:
    • [in] name 要回放的路径名称
    • [in] rate 回放速率, 应小于 3.0, 1 为路径原始速率。注意当速率大于 1 时,可能产生驱动器无法跟随错误
    • [out] ec 错误码

removePath()​

def removePath(self, name: str, ec: dict, removeAll: bool = False) -> None:

删除已保存的路径

  • 参数:
    • [in] name 要删除的路径名称
    • [out] ec 错误码。若路径不存在,错误码不会被置位
    • [in] removeAll 是否删除所有路径, 可选参数, 默认为否
  • 返回:无

queryPathLists()​

def queryPathLists(self, ec: dict) -> list[str]:

查询已保存的所有路径名称

  • 参数:
    • [out] ec 错误码
  • 返回:名称列表, 若没有路径则返回空列表

calibrateForceSensor()​

def calibrateForceSensor(self, all_axes: bool, axis_index: int, ec: dict) -> None:

力传感器标定(约 100ms,非阻塞等待完成)。标定前需通过 setToolset() 设置正确负载。

  • 参数
    • [in] all_axes true - 标定所有轴 | false - 单轴标定
    • [in] axis_index 轴下标, 范围[0, DoF), 仅当单轴标定时生效
    • [out] ec 错误码

enableCompletePostureLerp()​

def enableCompletePostureLerp(self, enable: bool, ec: dict) -> None:

是否使能平行基座模式。仅 xMateCr5Robot。

  • 参数:
    • [in] enable true 开启,false 关闭
    • [out] ec 错误码

6 力控指令​

forceControl()​

def forceControl(self) -> ...:

力控指令类

  • 返回: ForceControl_T

getEndTorque()​

def getEndTorque(self, ref_type: FrameType, joint_torque_measured: PyTypeVectorDouble, external_torque_measured: PyTypeVectorDouble, cart_torque: PyTypeVectorDouble, cart_force: PyTypeVectorDouble, ec: dict) -> None:

获取当前力矩信息

  • 参数:
    • [in] ref_type 力矩相对的参考系:
      • FrameType::world - 末端相对世界坐标系的力矩信息;
      • FrameType::flange - 末端相对于法兰盘的力矩信息;
      • FrameType::tool - 末端相对于 TCP 点的力矩信息。
    • [out] joint_torque_measured 各轴测量力
    • [out] external_torque_measured 各轴外部力
    • [out] cart_torque 笛卡尔空间力矩 [X, Y, Z],单位 Nm
    • [out] cart_force 笛卡尔空间力 [X, Y, Z],单位 N
    • [out] ec 错误码

fcInit()​

def fcInit(self, frame_type: FrameType, ec: dict) -> None:

力控初始化

  • 参数:
    • [in] frame_type 力控坐标系,支持 world/wobj/tool/base/flange。工具工件坐标系使用 setToolset() 设置的坐标系
    • [out] ec 错误码

fcStart()​

def fcStart(self, ec: dict) -> None:

开始力控,fcInit()之后调用。如需在力控模式下执行运动指令,fcStart()之后可执行。注意,如果在 fcStart()之前通过 moveAppend()下发了运动指令但未开始运动,fcStart 之后就会执行这些运动指令。

  • 参数:[out] ec 错误码

fcStop()​

def fcStop(self, ec: dict) -> None:

停止力控

  • 参数 [out] ec 错误码

setControlType()​

def setControlType(self, type: int, ec: dict) -> None:

设置阻抗控制类型

  • 参数:
    • [in] type 0 - 关节阻抗 | 1 - 笛卡尔阻抗
    • [out] ec 错误码

setLoad()​

def setLoad(self, load: Load, ec: dict) -> None:

设置力控模块使用的负载信息,fcStart()之后可调用。

  • 参数:
    • [in] load 负载
    • [out] ec 错误码

setJointStiffness()​

def setJointStiffness(self, stiffness: list[float], ec: dict) -> None:

设置关节阻抗刚度。fcInit()之后调用生效,各机型的最大刚度不同,请参考《xCore 控制系统手册》 SetJntCtrlStiffVec 指令的说明

  • 参数:
    • [in] stiffness 各轴刚度
    • [out] ec 错误码

setCartesianStiffness()​

def setCartesianStiffness(self, stiffness: list[float], ec: dict) -> None:

设置笛卡尔阻抗刚度。fcInit()之后调用生效,各机型的最大刚度不同,请参考《xCore 控制系统手册》 SetCartCtrlStiffVec 指令的说明

  • 参数:
    • [in] stiffness 依次为:X Y Z 方向阻抗力刚度[N/m], X Y Z 方向阻抗力矩刚度[Nm/rad]
    • [out] ec 错误码

setCartesianNullspaceStiffness()​

def setCartesianNullspaceStiffness(self, stiffness: float, ec: dict) -> None:

设置笛卡尔零空间阻抗刚度。fcInit()之后调用生效

  • 参数:
    • [in] stiffness 范围[0,4],大于 4 会默认设置为 4, 单位 Nm/rad
    • [out] ec 错误码

setJointDesiredTorque()​

def setJointDesiredTorque(self, torque: list[float], ec: dict) -> None:

设置关节期望力矩。fcStart()之后可调用

  • 参数:
    • [in] torque 力矩值, 范围[-30,30], 单位 Nm
    • [out] ec 错误码

setCartesianDesiredForce()​

def setCartesianDesiredForce(self, value: list[float], ec: dict) -> None:

设置笛卡尔期望力/力矩。fcStart()之后可调用

  • 参数:
    • [in] value 依次为 X Y Z 方向笛卡尔期望力,范围[-60,60],单位 N;X Y Z 方向笛卡尔期望力矩,范围[-10,10],单位 Nm
    • [out] ec 错误码

setSineOverlay()​

def setSineOverlay(self, line_dir: int, amplify: float, frequency: float, phase: float, bias: float, ec: dict) -> None:

设置绕单轴旋转的正弦搜索运动。 设置阻抗控制类型为笛卡尔阻抗(即 setControlType(1))之后,startOverlay()之前调用生效。 各机型的搜索运动幅值上限和搜索运动频率上限不同,请参考《xCore 控制系统手册》 SetSineOverlay 指令的说明。

  • 参数:
    • [in] line_dir 搜索运动参考轴: 0 - X | 1 - Y | 2 - Z
    • [in] amplify 搜索运动幅值, 单位 Nm
    • [in] frequency 搜索运动频率, 单位 Hz
    • [in] phase 搜索运动相位, 范围[0, PI], 单位弧度
    • [in] bias 搜索运动偏置, 范围[0, 10], 单位 Nm
    • [out] ec 错误码

setLissajousOverlay()​

def setLissajousOverlay(self, plane: int, amplify_one: float, frequency_one: float, amplify_two: float, frequency_two: float, phase_diff: float, ec: dict) -> None:

设置平面内的莉萨如搜索运动 设置阻抗控制类型为笛卡尔阻抗(即 setControlType(1))之后, startOverlay()之前调用生效。

  • 参数:
    • [in] plane 搜索运动参考平面: 0 - XY | 1 - XZ | 2 - YZ
    • [in] amplify_one 搜索运动一方向幅值, 范围[0, 20], 单位 Nm
    • [in] frequency_one 搜索运动一方向频率, 范围[0, 5], 单位 Hz
    • [in] amplify_two 搜索运动二方向幅值, 范围[0, 20]单位 Nm
    • [in] frequency_two 搜索运动二方向频率, 范围[0, 5], 单位 Hz
    • [in] phase_diff 搜索运动两个方向相位偏差, 范围[0, PI], 单位弧度
    • [out] ec 错误码

startOverlay()​

def startOverlay(self, ec: dict) -> None:

开启搜索运动。fcStart()之后调用生效 搜索运动为前序设置的 setSineOverlay()或 setLissajousOverlay()的叠加

  • 参数:
    • [out] ec 错误码

stopOverlay()​

def stopOverlay(self, ec: dict) -> None:

停止搜索运动

  • 参数:
    • [out] ec 错误码

pauseOverlay()​

def pauseOverlay(self, ec: dict) -> None:

暂停搜索运动。startOverlay()之后调用生效

  • 参数:
    • [out] ec 错误码

restartOverlay()​

def restartOverlay(self, ec: dict) -> None:

重新开启暂停的搜索运动。pauseOverlay()之后调用生效。

  • 参数:
    • [out] ec 错误码

setForceCondition()​

def setForceCondition(self, range: list[float], isInside: bool, timeout: float, ec: dict) -> None:

设置与接触力有关的终止条件

  • 参数:
    • [in] range 各方向上的力限制 { X_min, X_max, Y_min, Y_max, Z_min, Z_max },单位 N。设置下限时,负值表示负方向上的最大值;设置上限时,负值表示负方向上的最小值。
    • [in] isInside true - 超出限制条件时停止等待;false - 符合限制条件时停止等待
    • [in] timeout 超时时间,范围[1, 600],单位秒
    • [out] ec 错误码

setTorqueCondition()​

def setTorqueCondition(self, range: list[float], isInside: bool, timeout: float, ec: dict) -> None:

设置与接触力矩有关的终止条件

  • 参数:
    • [in] range 各方向上的力矩限制 { X_min, X_max, Y_min, Y_max, Z_min, Z_max },单位 Nm。设置下限时,负值表示负方向上的最大值;设置上限时,负值表示负方向上的最小值。
    • [in] isInside true - 超出限制条件时停止等待;false - 符合限制条件时停止等待
    • [in] timeout 超时时间, 范围[1, 600], 单位秒
    • [out] ec 错误码

setPoseBoxCondition()​

def setPoseBoxCondition(self, supervising_frame: Frame, box: list[float], isInside: bool, timeout: float, ec: dict) -> None:

设置与接触位置有关的终止条件

  • 参数:
    • [in] supervising_frame 长方体所在的参考坐标系,相对于外部工件坐标系(通过 setToolset()设置的 Toolset::ref)
    • [in] box 定义一个长方体 { X_start, X_end, Y_start, Y_end, Z_start, Z_end },单位米
    • [in] isInside true - 超出限制条件时停止等待;false - 符合限制条件时停止等待
    • [in] timeout 超时时间,范围[1, 600],单位秒
    • [out] ec 错误码

waitCondition()​

def waitCondition(self, ec: dict) -> None:

激活前序设置的终止条件并等待,直到满足这些条件或者超时

  • 参数:
    • [out] ec 错误码

fcMonitor()​

def fcMonitor(self, enable: bool, ec: dict) -> None:

启动/关闭力控模块保护监控 设置监控参数后,不立即生效,调用 fcMonitor(true)后开始生效,并且一直保持,直到调用 fcMonitor(false)后结束。结束后保护阈值恢复成默认值,即仍然会有保护效果,关闭监控后不再是用户设置的参数。

  • 参数:
    • [in] enable true - 打开 | false - 关闭
    • [out] ec 错误码

setJointMaxVel()​

def setJointMaxVel(self, velocity: list[float], ec: dict) -> None:

设置力控模式下的轴最大速度

  • 参数:
    • [in] velocity 轴速度 [rad/s],范围 >=0
    • [out] ec 错误码

setJointMaxMomentum()​

def setJointMaxMomentum(self, momentum: list[float], ec: dict) -> None:

设置力控模式下轴最大动量 计算方式:F*t,可以理解为冲量,F为力矩传感器读数,t为控制周期,如果超过30个周期都超过动量阈值则触发保护

  • 参数:
    • [in] momentum 动量[N·s],范围 >=0
    • [out] ec 错误码

setJointMaxEnergy()​

def setJointMaxEnergy(self, energy: list[float], ec: dict) -> None:

设置力控模式下轴最大动能 计算方式:F*v,可以理解为功率,F为力矩传感器读数,v为关节速度,如果超过30个周期都超过动能阈值则触发保护

  • 参数:
    • [in] energy 动能[N·rad/s],范围 >=0
    • [out] ec 错误码

setCartesianMaxVel()​

def setCartesianMaxVel(self, velocity: list[float], ec: dict) -> None:

设置力控模式下,机械臂末端相对基坐标系的最大速度

  • 参数:
    • [in] velocity 依次为:X Y Z [m/s], A B C [rad/s], 范围 >=0
    • [out] ec 错误码

reset()​

def reset(self) -> None:

绑定没有说明字符串。实现会删除当前力控对象并置空。

setFcGain()​

def setFcGain(self, gain: list[float], ec: dict) -> None:

设置各轴力控带宽。fcStart() 开始生效,fcStop 后失效。

  • 参数:
    • [in] gain 各轴带宽,范围 [0, 60],各轴默认 20,无单位
    • [out] ec 错误码

setFriction()​

def setFriction(self, fric: list[float], ec: dict) -> None:

设置各轴摩擦力补偿系数。fcStart() 开始生效,fcStop 后失效。

  • 参数:
    • [in] fric 补偿系数,范围 [0, 1],各轴默认 0.9,无单位
    • [out] ec 错误码

setJointControlMaxVel()​

def setJointControlMaxVel(self, max_joint_vel: list[float], ec: dict) -> None:

阻抗速度限幅,关节。fcStart() 开始生效,fcStop 后失效。以加期望力下压直到接触为例,一般用期望力实现,此接口对该接触过程限速。

  • 参数:
    • [in] max_joint_vel 关节速度最大值,单位 rad/s,范围 [0, 10.0],默认最大值
    • [out] ec 错误码

setJointControlMaxTorque()​

def setJointControlMaxTorque(self, max_torque: list[float], ec: dict) -> None:

阻抗力限幅,关节。fcStart() 开始生效,fcStop 后失效。阻抗下运动时限制末端出力,并作为末端力监控。

  • 参数:
    • [in] max_torque 力限幅,单位 Nm,范围 [0, 1000],默认最大值
    • [out] ec 错误码

setCartesianControlMaxVel()​

def setCartesianControlMaxVel(self, max_cart_vel: list[float], ec: dict) -> None:

阻抗速度限幅,笛卡尔。fcStart() 开始生效,fcStop 后失效。用途同关节限速。

  • 参数:
    • [in] max_cart_vel XYZ 范围 [0, 3.0] m/s,ABC 范围 [0, 10.0] rad/s,默认最大值
    • [out] ec 错误码

setCartesianControlMaxWrench()​

def setCartesianControlMaxWrench(self, max_wrench: list[float], ec: dict) -> None:

阻抗力限幅,笛卡尔。fcStart() 开始生效,fcStop 后失效。用途同关节力限幅。

  • 参数:
    • [in] max_wrench 依次为 XYZ [N]、ABC [Nm],范围 [0, 1000],默认最大值
    • [out] ec 错误码

7 实时控制​

协作机型调用 getRtMotionController() 得到对象。类在 xCoreSDK_python.motioncontrolRT,名为 PyRTmotioncontrol5 / PyRTmotioncontrol6 / PyRTmotioncontrol7。绑定说明里的类名写作 RtMotionControlCobot。工业机型没有这个接口。接收状态用机器人上的 startReceiveRobotState(),见第 1 节。

getRtMotionController()​

def getRtMotionController(self):

创建实时运动控制实例,通过它做实时模式操作。仅协作机型。

  • 注解:除非再次调用本接口,客户端不会主动析构返回的对象。disconnectFromRobot()、离开实时模式之后再做实时控制会抛异常。
  • 返回:控制器对象
  • 异常:
    • RealtimeControlException:网络原因导致创建失败
    • ExecutionException:没有切换到实时运动控制模式

disconnectNetwork()​

def disconnectNetwork(self) -> None:

断开与实时控制服务器的连接,关闭数据接收和指令发送端口。不会断开和机器人的连接。机器人正在运动时,断开后立即停止运动。

reconnectNetwork()​

def reconnectNetwork(self, ec: dict) -> None:

重新连接到实时控制服务器。

  • 参数: [out] ec 错误码

setControlLoop()​

def setControlLoop(self, callback, priority: int = 0, useStateDataInLoop: bool = False) -> None:

三个重载,回调分别对应 JointPosition、CartesianPosition、Torque。绑定没有给这三个重载挂说明。参数与下面三个函数相同。

setControlLoopCar() / setControlLoopJoi() / setControlLoopTor()​

def setControlLoopCar(self, callback, priority: int = 0, useStateDataInLoop: bool = False) -> None:

开始执行回调函数。setControlLoopJoi、setControlLoopTor 的参数相同。

  • 参数:
    • [in] callback 回调。随 RtControllerMode 不同,返回关节角度、笛卡尔位姿或力矩
    • [in] priority 任务优先级,0 为不指定。仅实时操作系统生效;设置失败时向控制台打印错误
    • [in] useStateDataInLoop 是否在周期内读取状态数据

startLoop()​

def startLoop(self, blocking: bool = True) -> None:

开始执行回调函数。

  • 参数: [in] blocking 为 true 时阻塞调用线程。非阻塞时须调用 stopLoop(),否则无法开始下一次循环。

stopLoop()​

def stopLoop(self) -> None:

停止周期性调度任务。

startMove()​

def startMove(self, rtMode: RtControllerMode) -> None:

指定控制模式,机器人准备开始运动。每段回调执行前先调用。调用后不会立刻运动,发出运动命令后才开始。

  • 注解:调用前先设好滤波、阻抗等参数。startMove 之后再执行下电等指令可能失败。停止应调用 stopMove。
  • 参数: [in] rtMode 控制模式
  • 异常:
    • RealtimeStateException:已经开始运动后又调用
    • RealtimeParameterException:控制模式不支持
    • RealtimeControlException:控制器无法切换到该模式,多见于切到力控

stopMove()​

def stopMove(self) -> None:

机器人停止运动,停止接收客户端运动指令。

sendCommand()​

def sendCommand(self, cmd: JointPosition | CartesianPosition | Torque) -> None:

直接发送关节位置、笛卡尔位姿或力矩,不经过调度周期。运动开始后持续调用。控制器周期 1ms,发送间隔也要控制在 1ms:过长判为丢包,过短会造成伺服报错。直接发送时不需要 setControlLoop()、startLoop()、stopLoop()。报错通过 updateRobotState() 抛出;须先 startReceiveRobotState(),建议间隔 1ms,避免报错被覆盖。

  • 参数: [in] cmd 随控制模式选择上述三种命令之一
  • 异常:
    • ArgumentException:指令有非法值
    • RealtimeStateException:未开始运动
    • RealtimeControlException:发送网络异常,或命令类型与控制模式不符,或控制器执行已发送命令时出错

MoveJ() / MoveL() / MoveC()​

def MoveJ(self, speed: float, start: list[float], target: list[float]) -> None:
def MoveL(self, speed: float, start: CartesianPosition, target: CartesianPosition) -> None:
def MoveC(self, speed: float, start: CartesianPosition, aux: CartesianPosition, target: CartesianPosition) -> None:

上位机规划,到达目标前阻塞;运动出错则结束阻塞并返回。已不建议使用,请改用非实时指令 MoveAbsJCommand、MoveLCommand、MoveCCommand。

  • MoveJ:speed 速度比例;start 须为当前关节角,否则可能下电;target 目标关节角。
  • MoveL:speed 范围 0–1;start 须为当前位姿。设置了 TCP 时,start 和 target 是工具相对基坐标系。
  • MoveC:aux 为辅助点。设置了 TCP 时,三个位姿都是 TCP 相对基坐标系。点位无法构成圆弧时抛 RealtimeParameterException;运动中出错抛 RealtimeMotionException。

setServoJoint()​

def setServoJoint(self, ServoJ_T: float, ServoJ_Lookahead: float, ServoJ_Kp: float, ec: dict) -> None:

在实时模式 sendCommand 下发关节位置时打开 servoJ,并设置调用周期、增益和前瞻时间。

  • 参数:
    • [in] ServoJ_T 调用周期,单位 s
    • [in] ServoJ_Lookahead 前瞻时间,限制下发关节位置后的运动速度,单位 s
    • [in] ServoJ_Kp 控制增益
    • [out] ec 错误码

stopServoJoint()​

def stopServoJoint(self) -> None:

关闭 servoJ。用过 setServoJoint 后需要关闭。

hasMotionError()​

def hasMotionError(self) -> bool:

实时模式运动是否发生了运动错误。true 表示有报错。

automaticErrorRecovery()​

def automaticErrorRecovery(self, ec: dict) -> None:

错误发生后自动恢复机器人。

  • 参数: [out] ec 错误码

setFilterLimit()​

def setFilterLimit(self, limit_rate: bool, cutoff_frequency: float) -> bool:

设置限幅滤波参数。

  • 参数:
    • [in] limit_rate true 为开启限幅
    • [in] cutoff_frequency 截止频率,0~1000 Hz,建议 10~100 Hz
  • 返回: true 表示设定成功

setCartesianLimit()​

def setCartesianLimit(self, lengths: list[float], frame: list[float], ec: dict) -> None:

设置笛卡尔空间运动区域,超出后运动停止。这是非力控虚拟墙。末端或 TCP 超出安全区域时,电机同样下电。

  • 参数:
    • [in] lengths 安全区域长方体的长宽高,对应 XYZ,单位米
    • [in] frame 长方体中心相对基坐标系的齐次矩阵
    • [out] ec 错误码

setEndEffectorFrame()​

def setEndEffectorFrame(self, frame: list[float], ec: dict) -> None:

设置末端执行器相对法兰的位姿。控制器会保存,机器人重启后恢复默认。

  • 参数:
    • [in] frame 齐次矩阵,单位 rad、m
    • [out] ec 错误码

setLoad()(实时控制)​

def setLoad(self, load: Load, ec: dict) -> None:

设置工具和负载的质量、质心和惯性矩阵。控制器会保存,机器人重启后恢复默认。与力控、模型库里的 setLoad 不是同一个函数。

  • 参数:
    • [in] load 负载
    • [out] ec 错误码

setJointImpedance()​

def setJointImpedance(self, factor: list[float], ec: dict) -> None:

设置轴空间阻抗系数,轴空间阻抗运动时生效。单位 Nm/rad。

  • 参数: [out] ec 错误码

setCartesianImpedance()​

def setCartesianImpedance(self, factor: list[float], ec: dict) -> None:

设置笛卡尔阻抗系数,笛卡尔阻抗运动时生效。顺序 [X, Y, Z, Rx, Ry, Rz],最大 {3000, 3000, 3000, 300, 300, 300},单位 N/m、Nm/rad。

  • 参数: [out] ec 错误码

setCartesianImpedanceDesiredTorque()​

def setCartesianImpedanceDesiredTorque(self, torque: list[float], ec: dict) -> None:

设置末端期望力,笛卡尔阻抗运动时生效。允许范围 {±60, ±60, ±60, ±30, ±30, ±30},单位 N、N·m。

  • 参数: [out] ec 错误码

setFilterFrequency()​

def setFilterFrequency(self, jointFrequency: float, cartesianFrequency: float, torqueFrequency: float, ec: dict) -> None:

设置控制器滤波截止频率,用来平滑指令。允许 1~1000 Hz,建议 10~100 Hz。

  • 参数:
    • [in] jointFrequency 关节位置,Hz
    • [in] cartesianFrequency 笛卡尔位置,Hz
    • [in] torqueFrequency 关节力矩,Hz
    • [out] ec 错误码

setTorqueFilterCutOffFrequency()​

def setTorqueFilterCutOffFrequency(self, frequency: float, ec: dict) -> None:

设置滤波参数。frequency 允许 1~1000 Hz。

  • 参数: [out] ec 错误码

setFcCoor()​

def setFcCoor(self, frame: list[float], type: FrameType, ec: dict) -> None:

设置力控坐标系。

  • 参数:
    • [in] frame 力控坐标系相对法兰的齐次变换矩阵
    • [in] type 力控任务坐标系:FrameType.world、FrameType.tool,或 FrameType.path(跟踪轨迹变化)
    • [out] ec 错误码

setCollisionBehaviour()​

def setCollisionBehaviour(self, torqueThresholds: list[float], ec: dict) -> None:

设置碰撞检测阈值。只在位置控制时生效,力控时不生效。检测到碰撞后控制器下电,电机抱闸。

  • 参数:
    • [in] torqueThresholds 关节碰撞检测阈值,单位 N
    • [out] ec 错误码

8 模型库​

xCoreSDK_python.model 里始终有 Model_0_3 / Model_0_4 / Model_0_6 和 Model_1_5 / Model_1_6 / Model_1_7,上面的接口是已有的 calcIk、calcFk、calcAllIkSolutions。

打开 CMake 选项 XMATE_MODEL(默认关闭,宏 XMATEMODEL_LIB_SUPPORTED)后,还会生成 xmateModel_1_5 / xmateModel_1_6 / xmateModel_1_7。类说明:支持 xMateER 系列、XMC7/12/18/20、XMS3/4。协作机型的 model() 此时返回这个类。它继承逆解和正解。下面的函数只在这个类上。

model_doc.h 里还有 calcIk_SearchElbow、getJointPosSearchPsi、getTorque、getTorqueWithFriction,model_bind.cpp 没有 .def,这里不列。

setLoad()(模型库)​

def setLoad(self, mass: float, cog: list[float], inertia: list[float]) -> None:

设置负载,只参与计算,不传给控制器。设置后动力学结果随之改变。

  • 参数:
    • [in] mass 质量
    • [in] cog 质心,单位 m
    • [in] inertia 惯量

setTcpCoor()​

def setTcpCoor(self, f_t_ee: list[float], ee_t_k: list[float]) -> None:

设置 TCP,只参与计算,不传给控制器。设置后正逆解的结果和输入随之改变。

  • 参数:
    • [in] f_t_ee 末端执行器相对法兰的位姿
    • [in] ee_t_k 刚度坐标系相对末端执行器的位姿

getCartPose()​

def getCartPose(self, jntPos: list[float], nr: SegmentFrame = SegmentFrame.flange) -> list[float]:

获取笛卡尔空间位置。

  • 参数: [in] jntPos 关节角度;[in] nr 坐标系,缺省法兰
  • 返回: 行优先的 4×4 位姿矩阵

getCartVel()​

def getCartVel(self, jntPos: list[float], jntVel: list[float], nr: SegmentFrame = SegmentFrame.flange) -> list[float]:

获取笛卡尔空间速度。

  • 参数: [in] jntPos 关节角度;[in] jntVel 关节角速度;[in] nr 缺省法兰
  • 返回: 计算结果

getCartAcc()​

def getCartAcc(self, jntPos: list[float], jntVel: list[float], jntAcc: list[float], nr: SegmentFrame = SegmentFrame.flange) -> list[float]:

获取笛卡尔空间加速度。

  • 参数:
    • [in] jntPos 需要计算笛卡尔空间速度的关节角度
    • [in] jntVel 需要计算笛卡尔空间速度的关节角速度
    • [in] jntAcc 需要计算笛卡尔空间速度的关节角加速度
    • [in] nr 指定坐标系,缺省法兰
  • 返回: 计算结果

getJointPos()​

def getJointPos(self, cartPos: list[float], elbow: float, jntInit: list[float], jntPos: list) -> int:

逆解求关节位置。一个位姿可能有多解,选取与 jntInit 最近的解。jntPos 会被清空后写入。

  • 参数:
    • [in] cartPos 法兰笛卡尔位姿
    • [in] elbow 臂角
    • [in] jntInit 初始关节角度
    • [out] jntPos 关节角
  • 返回:
    • -1、-2、-3:无解,cartPos 超出工作空间
    • -4、-5:结果与 jntInit 相差大,等效转速超过额定转速
    • -6、-7:结果超过软限位
    • -8:机器人奇异

getJointVel()​

def getJointVel(self, cartVel: list[float], jntPos: list[float]) -> list[float]:

逆解求关节速度。cartVel 为法兰笛卡尔速度,jntPos 为此时关节角度。

getJointAcc()​

def getJointAcc(self, cartAcc: list[float], jntPos: list[float], jntVel: list[float]) -> list[float]:

逆解求关节加速度。cartAcc 为法兰笛卡尔加速度,jntPos、jntVel 为此时关节角度和角速度。

jacobian() [1/2]​

def jacobian(self, jntPos: list[float], nr: SegmentFrame = SegmentFrame.flange) -> list[float]:

指定坐标系相对基坐标系的雅可比,行优先。长度为 6×DoF。

jacobian() [2/2]​

def jacobian(self, jntPos: list[float], f_t_ee: list[float], ee_t_k: list[float], nr: SegmentFrame = SegmentFrame.flange) -> list[float]:

同上,并传入末端相对法兰、刚度坐标系相对末端的位姿。

getTorqueNoFriction()​

def getTorqueNoFriction(self, jntPos, jntVel, jntAcc, trq_full, trq_inertia, trq_coriolis, trq_gravity) -> None:

计算不含摩擦的关节力矩,单位 Nm。有负载时先 setLoad()。四个输出 list 会被清空后写入。

  • 参数: [in] jntPos、jntVel、jntAcc;[out] trq_full 总力矩,trq_inertia 惯性力,trq_coriolis 科氏力(包括离心力),trq_gravity 重力矩

9 工具函数 utility​

函数在 xCoreSDK_python.utility。

degToRad() / radToDeg()​

def degToRad(degrees: float) -> float:
def degToRad(degrees: list[float]) -> list[float]:
def radToDeg(rad: float) -> float:
def radToDeg(rad: list[float]) -> list[float]:

标量或数组的度与弧度互转。另外有定长版本:degToRad_array6、radToDeg_array6(6 元)、degToRad_array16、radToDeg_array16(16 元),参数名同为 degrees 或 rad。

transMatrixToArray()​

def transMatrixToArray(rot, trans) -> list[float]:

旋转矩阵和平移向量转为行优先数组。

transMatrixToArray_all()​

def transMatrixToArray_all(R) -> list[float]:

4×4 变换矩阵转为行优先数组。

arrayToTransMatrix()​

def arrayToTransMatrix(arr) -> tuple:

行优先数组转为 (旋转矩阵, 平移向量)。

arrayToTransMatrix_all()​

def arrayToTransMatrix_all(arr) -> ...:

行优先数组转为 4×4 变换矩阵。

postureToTransArray()​

def postureToTransArray(xyz_abc) -> list[float]:

{X, Y, Z, Rx, Ry, Rz} 转为行优先齐次变换矩阵。

transArrayToPosture()​

def transArrayToPosture(transMat) -> list[float]:

行优先齐次变换矩阵转为 {X, Y, Z, Rx, Ry, Rz}。

eulerToMatrix()​

def eulerToMatrix(euler) -> ...:

欧拉角转旋转矩阵。顺序 [z, y, x],单位弧度。

eulerToQuaternion()​

def eulerToQuaternion(rpy) -> list[float]:

欧拉角转四元数 {Q1, Q2, Q3, Q4}。顺序 [z, y, x],单位弧度。

quaternionToEuler()​

def quaternionToEuler(w, x, y, z) -> list[float]:

四元数转欧拉角,返回 [Rx, Ry, Rz]。参数对应 Q1、Q2、Q3、Q4。

toolsetCalcPos()​

def toolsetCalcPos(toolset: Toolset) -> tuple:

Toolset 转为 (外部坐标系变换矩阵, 末端坐标系变换矩阵)。

EndInRefToFlanInBase()​

def EndInRefToFlanInBase(base_in_world, tool_set, end_in_ref):

末端相对外部参考坐标,转为法兰相对基坐标系。

FlanInBaseToEndInRef()​

def FlanInBaseToEndInRef(base_in_world, tool_set, flan_in_base):

法兰相对基坐标系,转为末端相对外部参考系。

10 轨迹规划 planner​

类在 xCoreSDK_python.planner。FollowPosition_5 / FollowPosition_6 / FollowPosition_7 与 xmateModel 一样,只在打开 XMATE_MODEL 时绑定。

CartMotionGenerator​

S 速度规划的笛卡尔空间运动。

def __init__(self, speed_factor: float, s_goal: float) -> None:

按路径总长度和速度系数生成笛卡尔平滑轨迹。speed_factor 范围 [0, 1],最终速度和加速度等于最大值乘该系数。s_goal 为路径总长度,单位 m。

def setMax(self, ds_max: float, dds_max_start: float, dds_max_end: float) -> None:

ds_max 最大速度,默认 1.0 m/s。dds_max_start、dds_max_end 为起止加速度,默认 2.5 m/s²。

def getTime(self) -> float:

总运动时间,单位秒。

def calculateDesiredValues(self, t: float, delta_s_d: PyTypeDouble) -> bool:

计算时刻 t(秒)的弧长,写入 delta_s_d。返回 false 表示规划未结束,true 表示结束。

def calculateSynchronizedValues(self, s_init: float) -> None:

用初始弧长 s_init 同步当前弧长。

JointMotionGenerator​

S 速度规划的关节空间运动。目标为 7 个关节角。

def __init__(self, speed_factor: float, q_goal: list[float]) -> None:

按目标关节角和速度系数生成轴空间轨迹,可用于回零或到指定位置。speed_factor 范围 [0, 1]。q_goal 单位 rad。

def setMax(self, dq_max: list[float], ddq_max_start: list[float], ddq_max_end: list[float]) -> None:

最大速度默认 J1~J4 为 1.0 rad/s,J5~J7 为 1.25 rad/s。起止加速度默认 2.5 rad/s²。

def getTime(self) -> float:

总运动时间,单位秒。

def calculateDesiredValues(self, t: float, delta_q_d: list) -> bool:

计算时刻 t 的关节角增量。delta_q_d 会被清空后写入。返回值含义同笛卡尔规划。

def calculateSynchronizedValues(self, q_init: list[float]) -> None:

用初始关节角同步当前关节角。

FollowPosition​

点位跟随,笛卡尔位姿或轴角度,用于视觉伺服。只在 XMATE_MODEL 打开时存在。

def __init__(self) -> None:

默认构造。之后调用 init()。

def __init__(self, robot, model) -> None:
def __init__(self, robot, model, endInFlange) -> None:

robot 为机器人实例。model 为 xmateModel,由 robot.model() 取得。endInFlange 为长度 16 的末端相对法兰位姿。

def init(self, robot, model) -> None:

用机器人和 xmateModel 初始化。

def start(self, bMe_desire: list[float]) -> None:
def start(self, jnt_desire: list[float]) -> None:

开始跟随,非阻塞。笛卡尔重载随后 update() 也要传入笛卡尔位姿;轴角度重载随后 update() 也要传入轴角度。bMe_desire 是末端相对基坐标系的 TCP 位姿,长度 16。jnt_desire 是轴角度。

def update(self, bMe_desire: list[float]) -> None:
def update(self, jnt_desired: list[float]) -> None:

更新期望位姿或轴角度,须与 start() 的类型一致:笛卡尔位姿对笛卡尔位姿,轴角度对轴角度。跟随带加减速,接近目标时减速,目标不宜过密,间隔建议至少几十毫秒。轴角度单位弧度。

def stop(self) -> None:

停止跟随。

def setScale(self, scale: float) -> None:

设置速度比例,跟随过程中可改,默认 0.5。最终速度有上限,目前不能改:各轴最大速度 120、120、180、180、200、200、200 °/s,各轴最大加速度 500 °/s²。