方法
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: 错误码
- [in] ct 坐标系类型
- 返回: 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: 错误码(如奇异、超限位、超范围等)
- [in] confs 调用方传入的列表,成功时由接口填入与每组解对应的 confdata(
- 返回:多组关节角(弧度);仅当错误码为 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 点标定)
- 注解 各坐标系类型支持的标定方法及注意事项:
- 工具坐标系: 三点/四点/六点标定法
- 工件坐标系: 三点标定。标定结果不会相对用户坐标系做变换,即,若为外部工件, - 返回:的结果是相对于基坐标系的。
- 基坐标系: 六点标定。标定前请确保动力学约束和前馈已关闭。 若标定成功(无错误码),控制器会自动保存标定结果,重启控制器后生效。
- 导轨基坐标系: 三点标定。若标定成功(无错误码),控制器会自动保存标定结果,重启控制器后生效。
- 参数:
- [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
- 碰撞后行为是安全停止或触发暂停时,该参数含义是碰撞后回退距离,单位: 米
- 碰撞后行为是柔顺停止时,该参数含义是柔顺度,范围 [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 各轴[下限, 上限],单位:弧度。
- 当 limits 为默认值时,视为仅打开软限位不修改数值; 不为默认值时,先修改软限位再打开
- 关闭软限位时不会修改限位数值
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表示断开
- [in] handler
setTeachPendantMode()
def setTeachPendantMode(self, enable: bool, ec: dict) -> None:
设置示教器模式开关;阻塞直至切换完成(约 2 秒量级超时)。运动中等情况可能切换失败。
- 参数:
- [in] enable
True启用示教器模式,False关闭 - [out] ec: 错误码
- [in] enable
getRobotCfg_DHparam()
def getRobotCfg_DHparam(self, get_nominal: bool, ec: dict) -> list[float]:
读取 DH 参数。
- 参数:
- [in] get_nominal
True标称参数,False优化后或当前设置(一般建议False) - [out] ec: 错误码
- [in] get_nominal
- 返回:依次为各轴 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:
参数: 参数名 数据类型 开关 enable bool 基坐标系 baseFrame Frame 导轨名称 name str 编码器分辨率 encoderResolution int 减速比 reductionRatio double 电机最大转速(rpm) motorSpeed int 软限位(m), [下限,上限] softLimit list[float]运动范围(m), [下限,上限] range list[float]最大速度(m/s) maxSpeed double 最大加速度(m/s^2) maxAcc double 最大加加速度(m/s^3) maxJerk double
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:设置了不支持的状态数据;或机器人无法开始发送数据;或总长度超过 1024RealtimeStateException:已经开始发送数据;或超时后仍未收到第一帧数据
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:关节角度,单位 radtcpPose_m:末端位姿,相对基坐标系,行优先齐次变换矩阵tcpPoseAbc_m:末端位姿[X, Y, Z, Rx, Ry, Rz]elbow_m:臂角,单位 radkeypads:末端按键状态exJointPos_m:外部轴位置,关节 rad、导轨 mexJointVel_m:外部轴速度,关节 rad/s、导轨 m/sexMotor_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: 错误码
- [in] mode:
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 错误码
- [in] speed 该接口不对参数进行范围限制。末端线速度的实际有效范围分别是 5-4000(协作), 5-7000(工业)。 关节速度百分比划分为 5 个的范围:
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: 错误码
- [in] zone: 该接口不对参数进行范围限制。转弯区半径大小实际有效范围是 0-200。 转弯百分比划分 4 个范围:
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: 错误码
- [in] enable
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: 处理事件的回调函数。说明:
- 对于Event::moveExecution, 回调函数在同一个线程执行, 请避免函数中有执行时间较长的操作;
- Event::safety 则每次独立线程回调, 没有执行时间的限制
- [out] ec: 错误码
- [in] eventType: 事件类型(含
setNoneEventWatcher()
def setNoneEventWatcher(self, eventType: Event, ec: dict) -> None:
取消指定 eventType 上已注册的回调。
- 参数:
- [in] eventType: 与
setEventWatcher一致 - [out] ec: 错误码
- [in] eventType: 与
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 参考坐标系。
- 工具/工件坐标系使用原则同
setToolset(); - 工业六轴机型和 xMateCR/SR 六 轴 机 型 支 持 两 种 奇 异 规 避 方 式
Jog:Space::singularityAvoidMode, Space::baseParallelMode - CR5 轴机型支持平行基座模式
Jog:Space::baseParallelMode
- 工具/工件坐标系使用原则同
- [in] rate: 速率, 范围 0.01 - 1
- [in] step: 步长。单位: 笛卡尔空间-毫米 | 轴空间-度。步长大于 0 即可,不设置上限, 如果机器人机器人无法继续 jog 会自行停止运动。
- [in] index 根据不同的 space,该参数含义如下:
- 世界坐标系,基坐标系,法兰坐标系,工具工件坐标系: a) 6 轴机型: 0~5 分别对应 X, Y, Z, Rx, Ry, Rz。>5 代表外部轴(若有) b) 7 轴机型 6 代表肘关节, >6 代表外部轴(若有)
- 轴空间: 关节序号,从 0 开始计数
- 奇异规避模式,平行基座模式:
a) 6 轴机型:0
5 分别对应 X, Y, Z, J4(4 轴), Ry, J6(6 轴); b) 5 轴机型:04 分别对应 X, Y, Z, Ry, J5(5 轴)
- [in] direction 根据不同的 space 和 index,该参数含义如下:
- 奇异规避模式 J4: true - ±180° | false - 0°;
- 平行基座模式 J4 & Ry: true - ±180° | false - 0°
- 其它,true - 正向 | false - 负向
- [out] ec 错误码
- [in] space jog 参考坐标系。
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。
- [in] fixed_name 例如与
setAvoidSingularity()
def setAvoidSingularity(self, method: AvoidSingularityMethod, enable: bool, limit: float, ec: dict) -> None:
xMateRobot:打开/关闭奇异点规避。只适用于部分机型:
- 四轴锁定:工业六轴,xMateCR 和 xMateSR 六轴
- 牺牲姿态:所有六轴
- 轴空间插补:工业六轴
- 参数:
- [in] method: 奇异规避方式
- [in] enable: true - 打开 | false - 关闭。四轴锁定打开前须保证 4 轴处于零位
- [in] limit:
- 牺牲姿态:允许的姿态误差,范围 (0, PI*2],单位弧度
- 轴空间插补:规避半径,范围 [0.005, 10],单位米
- 四轴锁定:无参数
- [out] ec: 错误码
def setAvoidSingularity(self, method: AvoidSingularityMethod, enable: bool, threshold: float, ec: dict) -> None:
StandardRobot:三种规避方式都支持。
- 参数:
- [in] method: 奇异规避方式
- [in] enable: true - 打开 | false - 关闭
- [in] threshold:
- 牺牲姿态:允许的姿态误差,范围 (0, PI*2],单位弧度
- 轴空间插补:规避半径,范围 [0.005, 10],单位米
- 四轴锁定:无参数
- [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 错误码
- [in] baud 波特率,见
- 说明: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 错误码
- [in] arbitration_baud
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 错误码
- [in] send_byte 发送字节长度;须与
- 说明:最大字节数随 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 错误码
- [in] data_type
- 说明:
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
- 经典 CAN +
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"]为错误信息。读取结果前先检查错误码,再按实际返回的组数和帧数访问
- [in] param -
- 返回值为
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 文件路径的列表, 单个文件路径如下:
-
- 删除某工程某任务下的 .mod 文件: project/[工程名]/[任务名]/[mod 文件名]
-
- 删除某工程某任务: project/[工程名]/[任务名]
-
- [out] ec 参数格式错误或网络错误。工程或任务或文件不存在不返回错误码
- [in] file_path_list 文件路径的列表, 单个文件路径如下:
setToolInfo()
def setToolInfo(self, tool_info: WorkToolInfo, ec: dict) -> None:
设置全局工具信息,或新建/设置 RL 工程中工具的位姿信息和负载信息
- 注解:
- 全局工具共 16 个,名称固定为
g_tool_0~g_tool_15 - 名称不是全局工具的,都视为 RL 工程工具:须先加载工程;不存在则新建,存在则修改。还须同步修改工程的工具配置文件,否则 RL 指令可能无法解析,设置后的数据也不会保存。不建议用本接口设置工程工具
- 暂不支持设置工具包络
- 全局工具共 16 个,名称固定为
- 参数:
- [in] tool_info 工具信息
- [out] ec 全局工具一般不会设置失败。工程中工具可能会设置失败,比如给控制器推送了工程的工具配置文件但是没有重新加载工程,工具配置不一致的情况下会返回错误码
setWobjInfo()
def setWobjInfo(self, wobj_info: WorkToolInfo, ec: dict) -> None:
设置全局工件信息,或新建/设置 RL 工程中工件的位姿信息和负载信息
- 注解:
- 全局工件共 16 个,名称固定为
g_wobj_0~g_wobj_15 - 名称不是全局工件的,都视为 RL 工程工件:须先加载工程;不存在则新建,存在则修改。还须同步修改工程的工件配置文件,否则 RL 指令可能无法解析,设置后的数据也不会保存
- 暂不支持设置用户坐标系。全局工件默认
g_user_0,工程工件默认userframe0
- 全局工件共 16 个,名称固定为
- 参数:
- [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 错误码
- [in] ref_type 力矩相对的参考系:
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 错误码
- [in] range 各方向上的力限制
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 错误码
- [in] range 各方向上的力矩限制
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 是否在周期内读取状态数据
- [in] callback 回调。随
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:机器人奇异
- -1、-2、-3:无解,
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²。