Skip to main content

Methods

1 Robot Basic Operation and Information Query​

connectToRobot() [1/2]​

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

Establish connection with the robot. The robot address is passed when creating the robot instance

  • Parameter: [out] ec: Error code

connectToRobot() [1/2]​

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

Connect to robot

  • Parameters:
    • remoteIP Robot IP address
    • localIP Local address. Used for real-time mode data transmission, can be left unset; not supported for PCB3 /4 axis models

disconnectFromRobot()​

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

Disconnect from the robot. The robot motion will be stopped before disconnection, please pay attention to safety

  • Parameter: [out] ec: Error code

robotInfo()​

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

Query robot basic information

  • Parameter: [out] ec: Error code
  • Return: Robot basic information (controller version, model, number of axes)

powerState()​

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

Robot power on/off and E-stop state

  • Parameter: [out] ec: Error code
  • Return:
    • on - Power on
    • off - Power off
    • estop - Emergency stop
    • gstop - Safety door open

setPowerState()​

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

Robot power on/off. Note: Only robots without external enable switch or teach pendant can be powered on in manual mode.

  • Parameters:
    • [in] on: true- Power on | false- Power off
    • [out] ec: Error code

operateMode()​

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

Query current robot operation mode

  • Parameter: [out] ec: Error code
  • Return: Manual | Automatic

setOperateMode()​

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

Switch manual/automatic mode

  • Parameters:
    • [in] mode: manual - Manual / automatic - Automatic
    • [out] ec: Error code

operationState()​

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

Query current robot running status (idle, moving, drag enabled, etc.)

  • Parameter: [out] ec: Error code
  • Return: Operation state enum

posture()​

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

Get current posture of robot flange or end

  • Parameters:
    • [in] ct Coordinate system type
      • flangeInBase: Flange relative to base frame;
      • endInRef: End relative to external reference frame. For example, when handheld tool and external workpiece are set, this coordinate system type returns the coordinates of the tool relative to the workpiece coordinate system.
    • [out] ec: Error code
  • Return: double array, [X, Y, Z, Rx, Ry, Rz], where translation unit is meter and rotation unit is radian

cartPosture()​

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

Get current posture of robot flange or end

  • Parameters:
    • [in] ct Coordinate system type
    • [out] ec: Error code
  • Return: Current Cartesian position

jointPos()​

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

Current axis angles. Body unit is rad. External axes, rails, and additional axes use rad or m.

  • Parameter: [out] ec: Error code
  • Return: Joint angle values and external axis values

jointVel()​

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

Current joint velocity. Body unit is rad/s. External axes, rails, and additional axes use rad/s or m/s.

  • Parameter: [out] ec: Error code
  • Return: Joint velocity

jointTorque()​

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

Joint force sensor values, unit: Nm

  • Parameter: [out] ec: Error code
  • Return: Torque values

baseFrame()​

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

User-defined base coordinate system, relative to world coordinate system

  • Parameter: [out] ec: Error code
  • Return: double array, [X, Y, Z, Rx, Ry, Rz], where translation unit is meter and rotation unit is radian

setBaseFrame()​

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

Set base coordinate system, only save values after setting, takes effect after restarting controller

  • Parameters:
    • [in] frame Coordinate system, default uses custom installation method
    • [out] ec: Error code

toolset()​

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

Query current tool workpiece set information

Note: This tool workpiece set is only used for SDK motion control, not related to RL projects

  • Parameter: [out] ec: Error code
  • Return: See Toolset data structure

setToolset() [1/2]​

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

Set tool workpiece set information

Note: This tool workpiece set is only used for SDK motion control, not related to RL projects. After setting, "toolx", "wobjx" will be displayed in the upper right corner of RobotAssist, and the end coordinates displayed in status monitoring will also change. In addition to this interface, if the default tool workpiece is changed through RobotAssist (the option in the upper right corner), this tool workpiece set will also be changed accordingly.

  • Parameters:
    • [in] toolset Tool workpiece set information
    • [out] ec: Error code

setToolset() [2/2]​

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

Use created tool and workpiece to set tool workpiece set information

Note: Setting premise: A RL project has been loaded, and tools and workpieces have been created. Otherwise, only the default tool workpiece can be set, namely "tool0" and "wobj0". A set of tool workpiece cannot be handheld or external at the same time; if there is a conflict, the tool's position shall prevail, for example, if the tool workpiece is handheld at the same time, no error will be returned, but the workpiece's coordinate system becomes external

  • Parameters:
    • [in] toolName Tool name
    • [in] wobjName Workpiece name
    • [out] ec: Error code
  • Return: The tool workpiece set after setting. On failure, returns the default Toolset value 0

model()​

def model(self):

Get the kinematics model that matches the connected robot's axis count and type. In xCoreSDK_python.model, Model_0_* is industrial and Model_1_* is collaborative. When the CMake option XMATE_MODEL is on (macro XMATEMODEL_LIB_SUPPORTED), collaborative model() returns xmateModel_1_5 / xmateModel_1_6 / xmateModel_1_7. That class inherits inverse and forward kinematics and adds the calls in section 8. The option is off by default.

  • Return: Model object. The concrete type depends on the robot.

calcIk() [1/2]​

def calcIk(self, posture: CartesianPosition, ec: dict) -> typing.Annotated[list[float], pybind11_stubgen.typing_ext.FixedSize(3)]:

Call this on the object returned by robot.model(). Calculate one inverse-kinematics solution from a pose.

  • Parameters:
    • [in] posture Robot end posture, relative to external reference frame
    • [out] ec: Error code
  • Return: Axis angles, unit: radian

calcIk() [2/2]​

def calcIk(self, posture: CartesianPosition, toolset: Toolset, ec: dict) -> typing.Annotated[list[float], pybind11_stubgen.typing_ext.FixedSize(3)]:

Calculate inverse kinematics in given tool workpiece coordinate system based on posture

  • Parameters:
    • [in] posture Robot end posture, relative to external reference frame
    • [in] toolset Tool workpiece set information
    • [out] ec: Error code
  • Return: Axis angles, unit: radian

calcFk() [1/2]​

def calcFk(self, joints: typing.Annotated[list[float], pybind11_stubgen.typing_ext.FixedSize(3)], ec: dict) -> CartesianPosition:

Call this on the object returned by robot.model(). Calculate forward kinematics from axis angles.

  • Parameters:
    • [in] joints Axis angles, unit: radian
    • [out] ec: Error code
  • Return: Robot end posture, relative to external reference frame

calcFk() [2/2]​

def calcFk(self, joints: typing.Annotated[list[float], pybind11_stubgen.typing_ext.FixedSize(3)], toolset: Toolset, ec: dict) -> CartesianPosition:

Calculate forward kinematics in given tool workpiece coordinate system based on axis angles

  • Parameters:
    • [in] joints Axis angles, unit: radian
    • [in] toolset Tool workpiece set information
    • [out] ec: Error code
  • Return: Robot end posture, relative to external reference frame

calcAllIkSolutions()​

Call this on the object returned by robot.model().

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

All inverse-kinematics solutions of a Cartesian pose. posture is the flange in the base frame. Convert other frames yourself. Not supported on xMateSR (XMS).

  • Parameters:
    • [in] confs List supplied by the caller. On success the call fills one confdata (list[list[int]]) for each solution
    • [out] ec Error code, including singularity, over-limit, and out-of-range
  • Return: Joint-angle solutions in radians. Valid only when the error code is 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:

Coordinate system calibration (N-point calibration)

  • Note Calibration methods and precautions for each coordinate system type:
    1. Tool coordinate system: Three-point/four-point/six-point calibration method
    2. Workpiece coordinate system: Three-point calibration. The calibration result will not be transformed relative to the user coordinate system, that is, if it is an external workpiece, the returned result is relative to the base coordinate system.
    3. Base coordinate system: Six-point calibration. Please ensure that dynamic constraints and feedforward are turned off before calibration. If calibration is successful (no error code), the controller will automatically save the calibration result, which takes effect after restarting the controller.
    4. Rail base coordinate system: Three-point calibration. If calibration is successful (no error code), the controller will automatically save the calibration result, which takes effect after restarting the controller.
  • Parameters:
    • [in] points Axis angle list, the length of the list is N. For example, using three-point method to calibrate tool coordinate system, 3 sets of axis angles should be passed in. The unit of axis angles is radian.
    • [in] is_held true - Robot handheld | false - External. Only affects tool/workpiece calibration
    • [in] base_aux Auxiliary point used for base coordinate system calibration, unit [meter]
    • [out] ec: Error code
  • Return: Calibration result, when no error code is set, the calibration result is valid

clearServoAlarm()​

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

Clear servo alarm

  • Parameter: [out] ec: Error code, error code is set to -1 when there is a servo alarm and clearing fails

enableCollisionDetection()​

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

Set collision detection parameters and turn the function on. Collaborative robots. The length of sensitivity matches the axis count.

  • Parameters:
    • [in] sensitivity Collision detection sensitivity, range 0.01-2.0
    • [in] behaviour Post-collision robot behavior, supports stop1 (safe stop, stop0 and stop1 have the same processing method) and stop2 (trigger pause), suppleStop (compliant stop)
    • [in] fallback_compliance
      1. When the post-collision behavior is safe stop or trigger pause, this parameter means the fallback distance after collision, unit: meter
      2. When the post-collision behavior is compliant stop, this parameter means compliance, range [0.0, 1.0]
    • [out] ec: Error code

enableCollisionDetection() (industrial six-axis StandardRobot)​

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

Industrial models support only stop1 (safe stop). There is no behaviour parameter. sensitivity is an array of length 6.

disableCollisionDetection()​

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

Turn off collision detection function

  • Parameter: [out] ec: Error code

getSoftLimit()​

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

Get current soft limit values

  • Parameters:
    • [out] limits Soft limit for each axis [lower limit, upper limit], unit: radian
    • [out] ec: Error code
  • Return: true - Enabled | false - Disabled

setSoftLimit()​

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

Set soft limit.

  • Parameters:
    • [in] enable true - Enable | false - Disable.
    • [out] ec: Error code
    • [in] limits Each axis [lower limit, upper limit], unit: radian.
      1. When limits is the default value, it is considered to only turn on soft limit without modifying the value; when it is not the default value, modify the soft limit first and then turn it on
      2. When turning off soft limit, the limit value will not be modified

queryControllerLog()​

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

Query the latest logs of the controller

  • Parameters:
    • [in] count Number of queries, maximum is 10
    • [in] level Specify log level, empty set means no specification
    • [in] offset Number of entries to skip. 0 starts at the newest entry. 10 starts at the 11th
    • [out] ec: Error code
  • Return: Log information

recoverState()​

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

Recover robot state according to option

  • Parameters:
    • [in] item Recovery option, 1: Emergency stop recovery
    • [out] ec: Error code

setRailParameter()​

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

Set rail parameters

  • Template parameters: Parameter type
  • Parameters:
    • [in] name: Parameter name, see value description
    • [in] value:
      ParameterParameter nameData type
      Switchenablebool
      Base coordinate systembaseFrameFrame
      Rail namenamestr
      Encoder resolutionencoderResolutionint
      Reduction ratioreductionRatiodouble
      Motor maximum speed(rpm)motorSpeedint
      Soft limit(m), [lower limit, upper limit]softLimitlist[float]
      Motion range(m), [lower limit, upper limit]rangelist[float]
      Maximum speed(m/s)maxSpeeddouble
      Maximum acceleration(m/s^2)maxAccdouble
      Maximum jerk(m/s^3)maxJerkdouble

getRailParameter()​

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

Read rail parameters

  • Template parameters: Parameter type
  • Parameters:
    • [in] name Parameter name, see setRailParameter()
    • [out] value Parameter value, see setRailParameter()
    • [out] ec: Error code, error code returned if parameter name does not exist or data type does not match

rebootSystem()​

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

Reboot the industrial PC. Reboot is not allowed in automatic mode, while powered on, while moving, or while not idle.

  • Parameter: [out] ec Error code

shutdownSystem()​

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

Shut down the industrial PC. Shutdown is not allowed in automatic mode, while powered on, while moving, or while not idle. After the cabinet is powered off, power it on again to start the controller software.

  • Parameter: [out] ec Error code

setConnectionHandler()​

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

Set the callback for controller connection-state changes.

  • Parameters:
    • [in] handler True means connected, False means disconnected

setTeachPendantMode()​

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

Turn teach-pendant mode on or off. Blocks until the switch finishes (timeout on the order of 2 seconds). The switch can fail while the robot is moving.

  • Parameters:
    • [in] enable True enables teach-pendant mode, False turns it off
    • [out] ec Error code

getRobotCfg_DHparam()​

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

Read DH parameters.

  • Parameters:
    • [in] get_nominal True for nominal parameters, False for optimized or current settings (False is usually preferred)
    • [out] ec Error code
  • Return: One list of Alpha[°], A[mm], D[mm], Theta[°] for each axis in that order. Valid only when the error code is 0.

getExtAxisInfo()​

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

Read additional-axis information. name is axis1 to axis6. info is a field name such as ext_data_number, zero_value, max_speed, or driver_name.

  • Parameter: [out] value Output container supplied by the caller. Its type must match the field.

getMechUnit()​

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

Read mechanical unit parameters. name is u1 to u6. info and the type of value:

  • activation, enable: bool, whether the unit is activated and enabled
  • axes_info: axis name list, in the configured order
  • fixed_name: fixed unit name; unit_name: custom unit name (str)
  • mech_link_type: int, 0 base axis, 1 positioner, 2 servo welding gun, 3 flange additional axis
  • Parameter: [out] value Output container; its type must match info.

configNtp()​

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

Configure NTP. Non-standard function, needs additional installation

  • Parameters:
    • [in] server_ip NTP server IP
    • [out] ec: Error code, NTP not installed correctly, or IP address format error

syncTimeWithServer()​

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

Manually sync time once, the remote IP is configured through configNtp. It takes a few seconds, blocks waiting for sync completion, the interface preset timeout is 12 seconds

  • Parameter: [out] ec: Error code. NTP service not installed correctly, or cannot sync with server

sdkVersion()​

def sdkVersion() -> str:

Query xCore-SDK version

  • Return: Version number

startReceiveRobotState()​

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

Ask the controller to start sending real-time state. Blocks until the first frame arrives. The timeout is 3 seconds.

  • Parameters:
    • [in] interval Send interval. Allowed values: 1ms, 2ms, 4ms, 8ms, 1s
    • [in] fields State field names to receive. Total size at most 1024 bytes
  • Raises:
    • RealtimeControlException: unsupported field, the robot cannot start sending, or the total size exceeds 1024 bytes
    • RealtimeStateException: sending has already started, or no first frame arrived before timeout

updateRobotState()​

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

Receive one robot-state frame in real-time mode. Call this before reading fields in a cycle. Call it at the send rate configured on the controller. timeout is a datetime.timedelta.

  • Parameters:
    • [in] timeout Wait timeout
  • Return: Length of the received data. 0 if nothing arrived before timeout
  • Raises: RealtimeControlException when parsing fails

getStateData()​

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

Read a field from the latest state frame. fieldName uses the exposed RtSupportedFields constants:

  • jointPos_m: joint positions, unit rad
  • tcpPose_m: end pose relative to the base frame, row-major homogeneous matrix
  • tcpPoseAbc_m: end pose [X, Y, Z, Rx, Ry, Rz]
  • elbow_m: elbow angle, unit rad
  • keypads: end button state
  • exJointPos_m: external axis position, joints in rad, rail in m
  • exJointVel_m: external axis velocity, joints in rad/s, rail in m/s
  • exMotor_m: external axis motor position

Vector fields need a length argument (see the type-stub overloads).

  • Return: Status code of the read (see the implementation)

stopReceiveRobotState()​

def stopReceiveRobotState(self) -> None:

Stop receiving real-time state and tell the controller to stop sending, so the subscribed fields can be configured again.

2 Motion Control (Non-real-time Mode)​

setMotionControlMode()​

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

Set motion control mode

  • Note: Before calling each motion control interface, the corresponding control mode must be set.
  • Parameters:
    • [in] mode: Mode
    • [out] ec: Error code

moveReset()​

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

Motion reset, clear sent motion commands, clear execution information

  • Note: Robot class calls motion reset once during initialization. When switching control between RL program and SDK motion commands, motion reset is needed.
  • Parameter: [out] ec Error code

stop()​

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

Pause robot motion; can call moveStart() to continue motion after pausing. If you need to completely stop and no longer execute added commands, you can call moveReset()

  • Note: Currently supports stop2 stop type, planned stop without power off, see StopLevel. After calling this interface, after pausing, you can call moveStart() to continue motion. If you need to completely stop and no longer execute added commands, you can call moveReset()
  • Parameter: [out] ec: Error code

pause()​

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

Pause robot motion. Same behavior as stop().

  • Parameter: [out] ec Error code

moveStart()​

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

Start/continue motion

  • Parameter: [out] ec: Error code

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:

Add single or multiple motion commands, call moveStart() to start motion after adding

  • Parameters
    • [in] cmds Command list, allowed number is 1-100, must be the same type of command
    • [out] cmdID ID of this command, can be used to query command execution information
    • [out] ec Error code, only feedbacks errors before command sending, including: 1) Network connection problem; 2) Command number does not match;

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:

Add single motion command, call moveStart() to start motion after adding

  • Parameters:
    • [in] cmd A single command
    • [out] cmdID ID of this command, can be used to query command execution information
    • [out] ec Error code, only feedbacks errors before command sending, including: 1) Network connection problem; 2) Command number does not match;

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:

Execute single or multiple motion commands, robot starts motion immediately after calling

  • Parameters:
    • [in] cmds Command list, allowed number is 1-1000
    • [out] ec Error code, only feedbacks errors before execution, including: 1) Network connection problem; 2) Command number does not match; 3) Robot cannot move in current state, such as not powered on

setDefaultSpeed()​

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

Set default motion speed, initial value is 100

  • Note: This value represents the maximum end linear speed (unit mm/s), automatically calculates corresponding joint speed
  • Parameters:
    • [in] speed This interface does not limit the parameter range. The actual effective range of end linear speed is 5-4000 (collaborative), 5-7000 (industrial). Joint speed percentage is divided into 5 ranges:
      • < 100 : 10% ;
      • 100 ~ 200 : 30% ;
      • 200 ~ 500 : 50% ;
      • 500 ~ 800 : 80% ;
      • 800 : 100%

    • Spatial rotation speed is 200°/s
    • [out] ec Error code

setDefaultZone()​

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

Set default zone

  • Note: This value represents the maximum zone radius (unit: mm), automatically calculates zone percentage. If not set, it is 0 (fine, no zone)
  • Parameters:
    • [in] zone: This interface does not limit the parameter range. The actual effective range of zone radius is 0-200. Zone percentage is divided into 4 ranges:
      • < 1 : 0 (fine) ;
      • 1 ~ 20 : 10% ;
      • 20 ~ 60 : 30% ;
      • 60 : 100%

    • [out] ec: Error code

setDefaultConfOpt()​

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

Set whether to use axis configuration data (confData) to calculate inverse kinematics. Initial value is false

  • Parameters:
    • [in] forced true - Use confData of motion command to calculate Cartesian point inverse kinematics, return error if calculation fails; false - Do not use, select the nearest solution to the current axis angle of the manipulator when inverse kinematics
    • [out] ec Error code

setMaxCacheSize()​

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

Set the maximum number of cached commands, meaning waypoints sent to the controller and waiting to be planned. Allowed range [1, 1000]. The initial value is 300.

  • Note: If the trajectory is mostly short trajectory, you can increase this value to avoid robot stopping motion due to command sending not being timely (after stopping, if there are unexecuted commands, you can moveStart() to continue;

  • Parameters:

    • [in] number: Count
    • [out] ec Error code

setAutoIgnoreZone()​

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

Set whether planning automatically cancels the zone. The initial value is true.

  • Parameters:
    • [in] enable true cancels the zone automatically, false does not
    • [out] ec Error code

adjustSpeedOnline()​

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

Dynamically adjust robot motion rate, takes effect in non-real-time mode.

  • Parameters:
    • [in] scale: Motion command speed ratio, range 0.01 - 1. When scale is set to 1, the robot will move at the original path speed.
    • [out] ec: Error code

getAcceleration()​

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

Read current acceleration/deceleration and jerk

  • Parameters:
    • [out] acc: Percentage of system preset acceleration
    • [out] jerk: Percentage of system preset jerk
    • [out] ec: Error code

adjustAcceleration()​

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

Adjust motion acceleration/deceleration and jerk. If called during robot motion, the current executing command does not take effect, the next command takes effect

  • Parameters:
    • [in] acc: Percentage of system preset acceleration, range [0.2, 1.5], no error will be reported if out of range, automatically changed to upper or lower limit value
    • [in] jerk: Percentage of system preset jerk, range [0.1, 2], no error will be reported if out of range, automatically changed to upper or lower limit value
    • [out] ec: Error code

setEventWatcher()​

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

Set callback function for receiving events

  • Parameters:
    • [in] eventType: Event type (moveExecution, safety, rlExecution, logReporter)
    • [in] callback: Callback function for handling events. Note:
      1. For Event::moveExecution, the callback function is executed in the same thread, please avoid operations with long execution time in the function;
      2. Event::safety is callback in an independent thread each time, no execution time limit
    • [out] ec: Error code

setNoneEventWatcher()​

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

Remove the callback registered for eventType.

  • Parameters:
    • [in] eventType Same values as setEventWatcher
    • [out] ec Error code

queryEventInfo()​

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

Query event information. Same as the information provided when setEventWatcher() callback, the difference is that this interface is an active query method

  • Parameters:
    • [in] eventType: Event type
    • [out] ec: Error code
  • Return: Event information. Field names are in EventInfoKey in the type appendix

startJog()​

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

Start jog robot, need to switch to manual operation mode.

  • Note: After calling this interface and the robot starts moving, regardless of whether the robot has stopped by itself, you must call stop() to end the jog operation, otherwise the robot will always be in jog running state.
  • Parameters:
    • [in] space jog reference coordinate system.
      1. Tool/workpiece coordinate system usage principle is the same as setToolset();
      2. Industrial six-axis models and xMateCR/SR six-axis models support two singularity avoidance methods Jog:Space::singularityAvoidMode, Space::baseParallelMode
      3. CR5 axis models support parallel base mode Jog:Space::baseParallelMode
    • [in] rate: Rate, range 0.01 - 1
    • [in] step: Step size. Unit: Cartesian space - millimeter | axis space - degree. Step size greater than 0 is acceptable, no upper limit is set, if the robot cannot continue jogging, it will stop moving by itself.
    • [in] index According to different space, this parameter meaning is as follows:
      1. World coordinate system, base coordinate system, flange coordinate system, tool workpiece coordinate system: a) 6-axis models: 0~5 correspond to X, Y, Z, Rx, Ry, Rz respectively. >5 represents external axis (if any) b) 7-axis models 6 represents elbow joint, >6 represents external axis (if any)
      2. Axis space: Joint number, counted from 0
      3. Singularity avoidance mode, parallel base mode: a) 6-axis models: 05 correspond to X, Y, Z, J4(4 axis), Ry, J6(6 axis); b) 5-axis models: 04 correspond to X, Y, Z, Ry, J5(5 axis)
    • [in] direction According to different space and index, this parameter meaning is as follows:
      1. Singularity avoidance mode J4: true - ±180° | false - 0°;
      2. Parallel base mode J4 & Ry: true - ±180° | false - 0°
      3. Others, true - Positive direction | false - Negative direction
    • [out] ec Error code

startJogWithExt()​

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

Jog a mechanical unit or an external axis on top of startJog. fixed_name is used together with index and is_ext. The other parameters mean the same as startJog().

  • Parameters:
    • [in] fixed_name With index: any character, is_ext false, and index 0 jogs the robot's first axis. u1 and index 0 jog the first axis of mechanical unit u1.
    • [in] is_ext Whether this is an external-axis jog. Default true.

setAvoidSingularity()​

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

xMateRobot: turn singularity avoidance on or off. Only some models apply:

  1. Lock axis 4: industrial 6-axis, and xMateCR / xMateSR 6-axis
  2. Sacrifice orientation: all 6-axis models
  3. Joint-space interpolation: industrial 6-axis
  • Parameters:
    • [in] method: Avoidance method
    • [in] enable: true - on | false - off. Before enabling lock-axis-4, axis 4 must be at zero
    • [in] limit:
      1. Sacrifice orientation: allowed orientation error, range (0, PI*2], unit radian
      2. Joint-space interpolation: avoidance radius, range [0.005, 10], unit meter
      3. Lock axis 4: this parameter is unused
    • [out] ec: Error code
def setAvoidSingularity(self, method: AvoidSingularityMethod, enable: bool, threshold: float, ec: dict) -> None:

StandardRobot: all three avoidance methods are supported.

  • Parameters:
    • [in] method: Avoidance method
    • [in] enable: true - on | false - off
    • [in] threshold:
      1. Sacrifice orientation: allowed orientation error, range (0, PI*2], unit radian
      2. Joint-space interpolation: avoidance radius, range [0.005, 10], unit meter
      3. Lock axis 4: this parameter is unused
    • [out] ec: Error code

getAvoidSingularity()​

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

Query whether in singularity avoidance state

  • Parameters:
    • [in] method: Singularity avoidance method
    • [out] ec: Error code
  • Return: true - Enabled | false – Disabled

checkPath() [1/3]​

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

Check if Cartesian trajectory is reachable, straight line trajectory. Supports rail, returned target axis angle is axis count + external axis count

  • Parameters:
    • [in] start: Start point
    • [in] start_joint: Start axis angle [radian]
    • [in] target: Target point
    • [out] ec: Error code
  • Return: Calculated target axis angle, only valid when no error code

checkPath() [2/3]​

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

Check multiple straight line trajectories

  • Parameters:
    • [in] start_joint: Start axis angle, unit [radian]
    • [in] points: Cartesian points, at least 2 points, the first point is the start point
    • [out] target_joint_calculated: If check passed. Return calculated target axis angle
    • [out] ec: Reason for check failure
  • Return: If check failed, return the index of the error target point in points. Return 0 in other cases

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]:

Check if Cartesian trajectory is reachable, including arc, full circle. Supports rail, returned target axis angle is axis count + external axis count

  • Parameters:
    • [in] start: Start point
    • [in] start_joint: Start axis angle [radian]
    • [in] aux: Auxiliary point
    • [in] target: Target point
    • [out] ec: Error code
    • [in] angle: Full circle execution angle, not equal to zero means check full circle trajectory
    • [in] rot_type: Full circle rotation type
  • Return: Calculated target axis angle, only valid when no error code

getDI()​

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

Query digital input signal value.

  • Parameters:
    • [in] board:IO board number.
    • [in] port:Signal port number.
    • [out] ec:Error code.
  • Return:true - On, false - Off.

getDO()​

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

Query digital output signal value.

  • Parameters:
    • [in] board:IO board number.
    • [in] port:Signal port number.
    • [out] ec:Error code.
  • Return:true - On, false - Off.

setDI()​

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

Set digital input signal value, can only be set when input simulation mode is enabled (see setSimulationMode()).

  • Parameters:
    • [in] board:IO board number.
    • [in] port:Signal port number.
    • [in] state:true - On, false - Off.
    • [out] ec:Error code.

setDO()​

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

Set digital output signal value.

  • Parameters:
    • [in] board:IO board number.
    • [in] port:Signal port number.
    • [in] state:true - On, false - Off.
    • [out] ec:Error code.

getAI()​

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

Read analog input signal value

  • Parameters:
    • [in] board IO board number
    • [in] port Signal port number
    • [out] ec Error code
  • Return:Signal value

setAO()​

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

Set analog output signal

  • Parameters:
    • [in] board IO board number
    • [in] port Signal port number
    • [in] value Output value
    • [out] ec Error code

readRegister()​

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

Read register value. Can read single register, register array, or read register array by index. If you want to read the entire register array, pass list of corresponding type to value, index value is ignored.

  • Parameters:
    • [in] name Register name
    • [in] index Read element in register array by index, starting from 0. The following two cases will report errors: 1) Index exceeds array length; 2) Register is not array but index > 0
    • [out] value Register value, allowed types are bool/int/float
    • [out] ec Error code

writeRegister()​

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

Write register value. Can write single register, register array, or write a certain element in register array by index. If you want to write the entire register array, pass list of corresponding type to value, index value is ignored.

  • Parameters:
    • [in] name Register name
    • [in] index Array index, starting from 0. The following two cases will report errors: 1) Index exceeds array length; 2) Register is not array but index > 0
    • [in] value Written value, allowed types are bool/int/float, and list[bool/int/float]
    • [out] ec Error code

setxPanelVout()​

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

Set xPanel external power supply mode. Note: Only some models support xPanel function, models that do not support will return error code

  • Parameters:
    • [in] opt Mode
    • [out] ec Error code

setSimulationMode()​

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

Set input simulation mode

  • Parameters:
    • [in] state true - Enable | false - Disable
    • [out] ec Error code

getKeypadState()​

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

Get end keypad state, models that do not support will return error code

  • Parameters:
    • [out] ec Error code
  • Return: End keypad state. End keypad number see the illustration of end handle in "xCore Robot Control System User Manual".

setxPanelRS485()​

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

Configure end-effector supply mode and enable/disable RS485. Required before using 485 on CR/SR. AR models default to 24V output with RS485 enabled.

  • Parameters:
    • [in] opt Supply mode: 0 off, 1 reserve, 2 12V, 3 24V
    • [in] if_rs485 Whether to enable RS485
    • [out] ec Error code

xPanelRS485Init()​

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

Initialize xPanel RS485 parameters (baud rate, parity, stop bits). For AR models, a reboot is required after configuration for the settings to take effect.

  • Parameters:
    • [in] baud Baud rate, see xPanelCommOptRs485Baud
    • [in] check_bit none / odd / even
    • [in] stop_bit stopbit1 / stopbit2
    • [out] ec Error code
  • Notes: Supported baud sets differ between AR and other models:
    • AR: 4800, 9600, 19200, 38400, 57600, 115200, 2500000
    • Others: 9600, 19200, 38400, 57600, 115200, 230400, 460800, 1000000, 2000000
    • Unsupported baud rates return a parameter-exceeds-limit error

setxPanelRS485Overtime()​

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

Set xPanel RS485 communication timeout.

  • Parameters:
    • [in] overtime_ms Timeout (ms), range 50~10000
    • [out] ec Error code

xPanelCANInit()​

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

Initialize xPanel CAN baud rates. Currently supported on AR models only; a reboot is required after configuration for the settings to take effect.

  • Parameters:
    • [in] arbitration_baud b1M / b500k / b250k / b125k
    • [in] data_baud b5M / b4M / b2M / b1M
    • [out] ec Error code

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:

Read/write Modbus RTU registers via xPanel.

  • Parameters:
    • [in] slave_addr Slave address 0~65535
    • [in] fun_cmd 0x03 / 0x04 / 0x06 / 0x10
    • [in] reg_addr Register address 0~65535
    • [in] data_type int16 / uint16 / int32 / uint32
    • [in] num Consecutive count. Ignored for 0x06. Valid ranges:
      • CR/ER/SR: end firmware < 301 → 16-bit [1,3], 32-bit 1; end firmware ≥ 301 → 16-bit [1,59], 32-bit [1,29]
      • AR: 16-bit [1,27], 32-bit [1,13]
    • [in/out] data_array Buffer (PyTypeVectorInt). For 0x06 only [0] is used; otherwise size must match num
    • [in] if_crc_reverse Reverse CRC byte order; default False
    • [out] ec Error code

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:

Read/write Modbus coils or discrete inputs via xPanel.

  • Parameters:
    • [in] slave_addr Slave address 0~65535
    • [in] fun_cmd 0x01 / 0x02 / 0x05 / 0x0F
    • [in] coil_addr Coil/discrete-input address 0~65535
    • [in] num Consecutive count. Ignored for 0x05. Valid ranges:
      • CR/ER/SR: end firmware < 301 → [1,48]; end firmware ≥ 301 → [1,944]
      • AR: [1,432]
    • [in/out] data_array Boolean buffer (PyTypeVectorBool). For 0x05 only [0] is used
    • [in] if_crc_reverse Reverse CRC byte order; default False
    • [out] ec Error code

XPRS485SendData()​

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

Send/receive raw RTU bytes via xPanel (not Modbus-framed).

  • Parameters:
    • [in] send_byte Send length; must equal len(send_data)
    • [in] rev_byte Expected receive length; rev_data length must match before the call
    • [in] send_data Bytes to send
    • [out] rev_data Received bytes
    • [out] ec Error code
  • Notes: Max byte count depends on xPanel type (CR/ER/SR series with end firmware 301+ support 128 bytes; earlier versions support 16 bytes; non-customized AR series supports 64 bytes)

CANReceiveData()​

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

Receive raw CAN frames via xPanel.

  • Parameters:
    • [in] timeout_ms Receive timeout (ms)
    • [in] data_type int16 / uint16 / uint8
    • [out] recv_frame Received frame (CANFrame; data is list[int], interpreted by data_type)
    • [out] ec Error code
  • Notes: Timeout with no data returns failure; see CANFormat for frame_format and CANType for frame_type

CANSendData()​

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

Send raw CAN frames via xPanel (multiple frames allowed).

  • Parameters:
    • [in] data_type int16 / uint16 / uint8
    • [in] send_frames Frames to send; each data length must equal frame_valid_length
    • [out] ec Error code
  • Notes: Valid frame_valid_length depends on frame type and data_type:
    • Classic CAN + uint8: [1,8];
    • Classic CAN + int16/uint16: [1,4]
    • CANFD / CANFD accelerated + uint8: [1,8], or 12/16/20/24/32/48/64
    • CANFD / CANFD accelerated + int16/uint16: [1,4], or 6/8/10/12/16/24/32

CANRwData()​

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

BaseCobot processes CAN send/receive groups in order through the xPanel end-effector interface. For each group, it sends one CAN frame and then expects one or more CAN frames.

  • Parameters
    • [in] param - CANRwParam. param.rw_frames[i].send_data holds the raw bytes to send for group i. param.rw_frames[i].rev_frames_per sets the expected receive count for that group. param.interval_ms sets the interval between groups in ms
    • [out] ec - Pass a dictionary. The method writes the error code to ec["ec"] and the error message to ec["message"]. Check the error code before reading the result, then use the actual group and frame counts to index it
  • Returns list[list[list[int]]], with the received frames grouped by send/receive operation. recv_frames[i][j] contains the raw bytes of frame j from group i

4 RL Project​

projectsInfo()​

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

Query RL project names and tasks in industrial computer

  • Parameters:
    • [out] ec Error code
  • Return:Project information list, return empty list if no project created

loadProject()​

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

Load project

  • Parameters:
    • [in] name Project name
    • [in] tasks Tasks to run. This parameter must be specified and cannot be empty, otherwise the project cannot be executed.
    • [out] ec Error code

ppToMain()​

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

Program pointer jumps to main. After calling, wait for the controller to parse the project and return, blocking time depends on project size, timeout time is set to 10 seconds.

  • Parameters:
    • [out] ec Error code. Error code can provide limited information, cannot feedback errors such as RL syntax error, variable does not exist, etc. Can query error log through queryControllerLog().

runProject()​

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

Start running currently loaded project

  • Parameters:
    • [out] ec Error code

pauseProject()​

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

Pause running project

  • Parameters:
    • [out] ec Error code

setProjectRunningOpt()​

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

Change project running speed and loop mode

  • Parameters:
    • [in] rate Running rate, range 0.01 - 1
    • [in] loop true - Loop execution | false - Single execution
    • [out] ec Error code

toolsInfo()​

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

Query tool information of currently loaded project

  • Parameters:
    • [out] ec Error code
  • Return:Tool information list, if no project loaded or no tool created, return default tool tool0 information

wobjsInfo()​

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

Query workpiece information of currently loaded project

  • Parameters:
    • [out] ec Error code
  • Return:Workpiece information list, if no project loaded or no workpiece created, return empty list

importProject()​

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

Import local RL project compressed package into controller. Block until import completed or failed

  • Parameters:
    • [in] file_path Local .zip compressed package path, file size within 10M
    • [in] overwrite Whether to overwrite files with the same name, yes: overwrite; no: automatically rename
    • [out] ec Error code
  • Return:Project name (e.g. automatically renamed, return after renaming)

removeProject()​

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

Delete RL project in controller

  • Parameters:
    • [in] name Project name
    • [in] remove_all Whether to delete all projects, default value is false
    • [out] ec Error code

importFile()​

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

Import local file into controller. Block until import completed or failed

  • Parameters:
    • [in] file_path Local file path. File size within 10M
    • [in] dest Target path
      • Transfer single RL project .mod file: project/[project name]/[task name]/[mod file name]
      • Transfer RL project .json/.xml/sys format configuration file: project/[project name]/[file name]. Note: Configuration file name cannot be changed, such as task file name must be "task.xml"
    • [in] overwrite Overwrite files with the same name: true - Overwrite | false - Automatically rename. Only .mod files support automatic renaming
    • [out] ec Local file does not exist; file format error; transfer failed; target path does not meet requirements, etc.
  • Return:File name after successful import

removeFiles()​

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

Delete files in controller. Note: Project .xml, .json and other configuration files cannot be deleted, only replaced

  • Parameters:
    • [in] file_path_list List of file paths, single file path as follows:
        1. Delete .mod file under a project task: project/[project name]/[task name]/[mod file name]
        1. Delete a project task: project/[project name]/[task name]
    • [out] ec Parameter format error or network error. No error code returned if project or task or file does not exist

setToolInfo()​

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

Set global tool information, or create/set pose information and load information of tools in RL project

  • Note:
    1. There are 16 global tools, named g_tool_0 to g_tool_15
    2. Any other name is an RL project tool: load the project first; create the tool if it does not exist, otherwise modify it. The project tool configuration file must be updated as well, otherwise RL commands may fail to resolve the tool and the data will not be saved. Prefer global tools
    3. Tool envelope is not supported
  • Parameters:
    • [in] tool_info Tool information
    • [out] ec Global tools generally won't set failed. Tools in project may set failed, such as pushing project tool configuration file to controller but not reloading project, error code will be returned when tool configuration is inconsistent

setWobjInfo()​

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

Set global workpiece information, or create/set pose information and load information of workpieces in RL project

  • Note:
    1. There are 16 global workpieces, named g_wobj_0 to g_wobj_15
    2. Any other name is an RL project workpiece: load the project first; create it if it does not exist, otherwise modify it. The project workpiece configuration file must be updated as well, otherwise RL commands may fail to resolve it and the data will not be saved
    3. User frames cannot be set here. Global workpieces default to g_user_0; project workpieces default to userframe0
  • Parameters:
    • [in] wobj_info Workpiece information
    • [out] ec Similarly to setToolInfo, global workpieces generally won't set failed. Workpieces in project may set failed

enableDrag()​

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

Enable drag

  • Parameters:
    • [in] space Drag space. 0 joint space, 1 Cartesian space. Joint-space drag supports free drag only
    • [in] type Drag type. 0 translation only, 1 rotation only, 2 free drag
    • [out] ec Error code
    • [in] enable_drag_button true - After enabling drag function, can directly drag robot without pressing end button

disableDrag()​

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

Disable drag

  • Parameters:
    • [out] ec Error code

setRtNetworkTolerance()​

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

Set real-time motion command network delay threshold (RobotAssist–RCI "Packet Loss Threshold"), range 0~100. Must be called before switching to RtCommandMode, otherwise it will not take effect.

  • Parameters:
    • [in] percent Allowable packet loss/delay threshold percentage
    • [out] ec: Error code

startRecordPath()​

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

Start recording path

  • Parameters:
    • [in] duration Path duration, unit: second, range 1~1800. This duration is only used for range check, the controller will not stop recording after timeout, need to call stopRecordPath() to stop
    • [out] ec Error code

stopRecordPath()​

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

Stop recording path, if recording successful (no error code) then path data is saved in cache

  • Parameters:
    • [out] ec Error code

cancelRecordPath()​

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

Cancel recording, cached path data will be deleted

  • Parameters:
    • [out] ec Error code

saveRecordPath()​

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

Save recorded path

  • Parameters:
    • [in] name Path name
    • [out] ec Error code
    • [in] saveAs Rename, optional parameter. If a path has been recorded but not saved, save the path with this name. If there is no unsaved path, rename the saved path named "name" to "saveAs"

replayPath()​

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

Motion command - Path replay Similar to other motion commands, after calling replayPath, need to call moveStart to start motion.

  • Parameters:
    • [in] name Path name to replay
    • [in] rate Replay rate, should be less than 3.0, 1 is original path rate. Note that when rate is greater than 1, drive cannot follow error may occur
    • [out] ec Error code

removePath()​

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

Delete saved path

  • Parameters:
    • [in] name Path name to delete
    • [out] ec Error code. If path does not exist, error code will not be set
    • [in] removeAll Whether to delete all paths, optional parameter, default no
  • Return:None

queryPathLists()​

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

Query all saved path names

  • Parameters:
    • [out] ec Error code
  • Return:Name list, return empty list if no path

calibrateForceSensor()​

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

Force sensor calibration (about 100ms, non-blocking wait for completion). Need to set correct load through setToolset() before calibration.

  • Parameters
    • [in] all_axes true - Calibrate all axes | false - Single axis calibration
    • [in] axis_index Axis index, range [0, DoF), only effective when single axis calibration
    • [out] ec Error code

enableCompletePostureLerp()​

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

Enable or disable parallel-base mode. xMateCr5Robot only.

  • Parameters:
    • [in] enable true to enable, false to disable
    • [out] ec Error code

6 Force Control Commands​

forceControl()​

def forceControl(self) -> ...:

Force control command class

  • Return: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:

Get current torque information

  • Parameters:
    • [in] ref_type Torque relative reference frame:
      • FrameType::world - End relative to world coordinate system torque information;
      • FrameType::flange - End relative to flange plate torque information;
      • FrameType::tool - End relative to TCP point torque information.
    • [out] joint_torque_measured Each axis measured force
    • [out] external_torque_measured Each axis external force
    • [out] cart_torque Cartesian space torque [X, Y, Z], unit Nm
    • [out] cart_force Cartesian space force [X, Y, Z], unit N
    • [out] ec Error code

fcInit()​

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

Force control initialization

  • Parameters:
    • [in] frame_type Force control coordinate system, supports world/wobj/tool/base/flange. Tool workpiece coordinate system uses coordinate system set by setToolset()
    • [out] ec Error code

fcStart()​

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

Start force control, call after fcInit(). If need to execute motion commands in force control mode, can execute after fcStart(). Note that if motion commands are sent through moveAppend() before fcStart() but not started, these motion commands will be executed after fcStart.

  • Parameter:[out] ec Error code

fcStop()​

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

Stop force control

  • Parameter [out] ec Error code

setControlType()​

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

Set impedance control type

  • Parameters:
    • [in] type 0 - Joint impedance | 1 - Cartesian impedance
    • [out] ec Error code

setLoad()​

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

Set load information used by force control module, can be called after fcStart().

  • Parameters:
    • [in] load Load
    • [out] ec Error code

setJointStiffness()​

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

Set joint impedance stiffness. Takes effect after calling after fcInit(), maximum stiffness of different models is different, please refer to the description of SetJntCtrlStiffVec command in "xCore Control System Manual"

  • Parameters:
    • [in] stiffness Each axis stiffness
    • [out] ec Error code

setCartesianStiffness()​

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

Set Cartesian impedance stiffness. Takes effect after calling after fcInit(), maximum stiffness of different models is different, please refer to the description of SetCartCtrlStiffVec command in "xCore Control System Manual"

  • Parameters:
    • [in] stiffness In order: X Y Z direction impedance force stiffness [N/m], X Y Z direction impedance torque stiffness [Nm/rad]
    • [out] ec Error code

setCartesianNullspaceStiffness()​

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

Set Cartesian nullspace impedance stiffness. Takes effect after calling after fcInit()

  • Parameters:
    • [in] stiffness Range [0,4], greater than 4 will be default set to 4, unit Nm/rad
    • [out] ec Error code

setJointDesiredTorque()​

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

Set joint desired torque. Can be called after fcStart()

  • Parameters:
    • [in] torque Torque value, range [-30,30], unit Nm
    • [out] ec Error code

setCartesianDesiredForce()​

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

Set Cartesian desired force/torque. Can be called after fcStart()

  • Parameters:
    • [in] value In order: X Y Z direction Cartesian desired force, range [-60,60], unit N; X Y Z direction Cartesian desired torque, range [-10,10], unit Nm
    • [out] ec Error code

setSineOverlay()​

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

Set sine search motion rotating around single axis. Set impedance control type to Cartesian impedance (i.e. setControlType(1)) after, before startOverlay() call takes effect. Maximum search motion amplitude and maximum search motion frequency of different models are different, please refer to the description of SetSineOverlay command in "xCore Control System Manual".

  • Parameters:
    • [in] line_dir Search motion reference axis: 0 - X | 1 - Y | 2 - Z
    • [in] amplify Search motion amplitude, unit Nm
    • [in] frequency Search motion frequency, unit Hz
    • [in] phase Search motion phase, range [0, PI], unit radian
    • [in] bias Search motion bias, range [0, 10], unit Nm
    • [out] ec Error code

setLissajousOverlay()​

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

Set Lissajous search motion in plane Set impedance control type to Cartesian impedance (i.e. setControlType(1)) after, before startOverlay() call takes effect.

  • Parameters:
    • [in] plane Search motion reference plane: 0 - XY | 1 - XZ | 2 - YZ
    • [in] amplify_one Search motion one direction amplitude, range [0, 20], unit Nm
    • [in] frequency_one Search motion one direction frequency, range [0, 5], unit Hz
    • [in] amplify_two Search motion two direction amplitude, range [0, 20] unit Nm
    • [in] frequency_two Search motion two direction frequency, range [0, 5], unit Hz
    • [in] phase_diff Search motion two direction phase difference, range [0, PI], unit radian
    • [out] ec Error code

startOverlay()​

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

Start search motion. Takes effect after calling after fcStart() Search motion is the superposition of previously set setSineOverlay() or setLissajousOverlay()

  • Parameters:
    • [out] ec Error code

stopOverlay()​

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

Stop search motion

  • Parameters:
    • [out] ec Error code

pauseOverlay()​

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

Pause search motion. Takes effect after calling after startOverlay()

  • Parameters:
    • [out] ec Error code

restartOverlay()​

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

Restart paused search motion. Takes effect after calling after pauseOverlay().

  • Parameters:
    • [out] ec Error code

setForceCondition()​

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

Set termination conditions related to contact force

  • Parameters:
    • [in] range Force limit in each direction { X_min, X_max, Y_min, Y_max, Z_min, Z_max }, unit N. When setting lower limit, negative value represents maximum value in negative direction; when setting upper limit, negative value represents minimum value in negative direction.
    • [in] isInside true - Stop waiting when exceeding limit condition; false - Stop waiting when meeting limit condition
    • [in] timeout Timeout time, range [1, 600], unit second
    • [out] ec Error code

setTorqueCondition()​

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

Set termination conditions related to contact torque

  • Parameters:
    • [in] range Torque limit in each direction { X_min, X_max, Y_min, Y_max, Z_min, Z_max }, unit Nm. When setting lower limit, negative value represents maximum value in negative direction; when setting upper limit, negative value represents minimum value in negative direction.
    • [in] isInside true - Stop waiting when exceeding limit condition; false - Stop waiting when meeting limit condition
    • [in] timeout Timeout time, range [1, 600], unit second
    • [out] ec Error code

setPoseBoxCondition()​

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

Set termination conditions related to contact position

  • Parameters:
    • [in] supervising_frame Reference coordinate system where the cuboid is located, relative to external workpiece coordinate system (Toolset::ref set by setToolset())
    • [in] box Define a cuboid { X_start, X_end, Y_start, Y_end, Z_start, Z_end }, unit meter
    • [in] isInside true - Stop waiting when exceeding limit condition; false - Stop waiting when meeting limit condition
    • [in] timeout Timeout time, range [1, 600], unit second
    • [out] ec Error code

waitCondition()​

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

Activate previously set termination conditions and wait until these conditions are met or timeout

  • Parameters:
    • [out] ec Error code

fcMonitor()​

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

Start/stop force control module protection monitoring After setting monitoring parameters, it does not take effect immediately, it takes effect after calling fcMonitor(true), and remains until calling fcMonitor(false) to end. After ending, the protection threshold returns to the default value, that is, there will still be protection effect, after closing monitoring, it is no longer the user-set parameters.

  • Parameters:
    • [in] enable true - Enable | false - Disable
    • [out] ec Error code

setJointMaxVel()​

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

Set maximum joint velocity in force control mode

  • Parameters:
    • [in] velocity Joint velocity [rad/s], range >=0
    • [out] ec Error code

setJointMaxMomentum()​

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

Set maximum joint momentum in force control mode Calculation method: F*t, can be understood as impulse, F is torque sensor reading, t is control cycle, if it exceeds the momentum threshold for 30 consecutive cycles, protection will be triggered

  • Parameters:
    • [in] momentum Momentum [N·s], range >=0
    • [out] ec Error code

setJointMaxEnergy()​

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

Set maximum joint energy in force control mode Calculation method: F*v, can be understood as power, F is torque sensor reading, v is joint velocity, if it exceeds the energy threshold for 30 consecutive cycles, protection will be triggered

  • Parameters:
    • [in] energy Energy [N·rad/s], range >=0
    • [out] ec Error code

setCartesianMaxVel()​

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

Set maximum velocity of manipulator end relative to base coordinate system in force control mode

  • Parameters:
    • [in] velocity In order: X Y Z [m/s], A B C [rad/s], range >=0
    • [out] ec Error code

reset()​

def reset(self) -> None:

The bind attaches no docstring. The implementation deletes the current force-control object and sets it to null.

setFcGain()​

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

Set per-axis force-control bandwidth. Takes effect after fcStart() and expires after fcStop.

  • Parameters:
    • [in] gain Bandwidth of each axis, range [0, 60], default 20 per axis, dimensionless
    • [out] ec Error code

setFriction()​

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

Set per-axis friction compensation. Takes effect after fcStart() and expires after fcStop.

  • Parameters:
    • [in] fric Compensation factor, range [0, 1], default 0.9 per axis, dimensionless
    • [out] ec Error code

setJointControlMaxVel()​

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

Impedance velocity limit, joint space. Takes effect after fcStart() and expires after fcStop. For pressing with a desired force until contact, this call limits the speed of that contact.

  • Parameters:
    • [in] max_joint_vel Maximum joint velocity, rad/s, range [0, 10.0], default is the maximum
    • [out] ec Error code

setJointControlMaxTorque()​

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

Impedance force limit, joint space. Takes effect after fcStart() and expires after fcStop. Limits end effort during impedance motion and also monitors end force.

  • Parameters:
    • [in] max_torque Force limit, Nm, range [0, 1000], default is the maximum
    • [out] ec Error code

setCartesianControlMaxVel()​

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

Impedance velocity limit, Cartesian. Takes effect after fcStart() and expires after fcStop. Same use as the joint velocity limit.

  • Parameters:
    • [in] max_cart_vel XYZ range [0, 3.0] m/s, ABC range [0, 10.0] rad/s, default is the maximum
    • [out] ec Error code

setCartesianControlMaxWrench()​

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

Impedance force limit, Cartesian. Takes effect after fcStart() and expires after fcStop. Same use as the joint force limit.

  • Parameters:
    • [in] max_wrench XYZ in N, then ABC in Nm, range [0, 1000], default is the maximum
    • [out] ec Error code

7 Real-time Control​

Collaborative robots create the object with getRtMotionController(). The classes live in xCoreSDK_python.motioncontrolRT and are named PyRTmotioncontrol5 / PyRTmotioncontrol6 / PyRTmotioncontrol7. The bind text calls the class RtMotionControlCobot. Industrial robots do not have this call. Receive state with startReceiveRobotState() on the robot; see section 1.

getRtMotionController()​

def getRtMotionController(self):

Create a real-time motion controller and use it for real-time mode. Collaborative robots only.

  • Note: The client does not destroy the returned object unless this call is made again. Calling disconnectFromRobot() or leaving real-time mode, then controlling in real-time again, raises an exception.
  • Return: Controller object
  • Raises:
    • RealtimeControlException: failed to create the instance because of the network
    • ExecutionException: not switched to real-time motion control mode

disconnectNetwork()​

def disconnectNetwork(self) -> None:

Disconnect from the real-time control server and close the state and command ports. This does not disconnect the robot. If the robot is moving, motion stops immediately.

reconnectNetwork()​

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

Reconnect to the real-time control server.

  • Parameter: [out] ec Error code

setControlLoop()​

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

Three overloads. The callback corresponds to JointPosition, CartesianPosition, or Torque. The bind attaches no docstring to these overloads. The parameters match the three functions below.

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

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

Start running the callback. setControlLoopJoi and setControlLoopTor take the same parameters.

  • Parameters:
    • [in] callback Callback. Depending on RtControllerMode, it returns a joint position, a Cartesian pose, or a torque
    • [in] priority Task priority. 0 means unspecified. Used only on a real-time operating system. A failed set prints an error to the console
    • [in] useStateDataInLoop Whether to read state data inside the cycle

startLoop()​

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

Start running the callback.

  • Parameter: [in] blocking When true, the calling thread blocks. A non-blocking loop must be stopped with stopLoop() before another cycle can start.

stopLoop()​

def stopLoop(self) -> None:

Stop the periodic scheduled task.

startMove()​

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

Select the control mode and prepare motion. Call it before each callback run. The robot does not move until a motion command is sent.

  • Note: Set filter, impedance, and similar parameters before startMove. Commands such as power-off may fail after startMove. Stop with stopMove.
  • Parameter: [in] rtMode Control mode
  • Raises:
    • RealtimeStateException: called again after motion has started
    • RealtimeParameterException: unsupported control mode
    • RealtimeControlException: the controller cannot switch to that mode, often when switching to force control

stopMove()​

def stopMove(self) -> None:

Stop robot motion and stop accepting client motion commands.

sendCommand()​

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

Send a joint position, Cartesian pose, or torque directly, without the scheduler. Keep calling it after motion starts. The controller period is 1 ms, so the send interval must also stay at 1 ms: too long is treated as packet loss, too short causes a servo error. Direct sending does not use setControlLoop(), startLoop(), or stopLoop(). Errors are raised from updateRobotState(). Call startReceiveRobotState() first; 1 ms is suggested so an error is not overwritten.

  • Parameter: [in] cmd One of the three command types, matching the control mode
  • Raises:
    • ArgumentException: the command contains an illegal value
    • RealtimeStateException: motion has not started
    • RealtimeControlException: network send error, command type does not match the control mode, or the controller failed while executing a sent command

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:

Planned on the client. Blocks until the target is reached. An error during motion ends the block and returns. These are deprecated. Use the non-real-time commands MoveAbsJCommand, MoveLCommand, and MoveCCommand.

  • MoveJ: speed is a scale. start must be the current joint position, or power-off may occur. target is the goal joint position.
  • MoveL: speed is in 0–1. start must be the current pose. If a TCP is set, start and target are the tool in the base frame.
  • MoveC: aux is the auxiliary pose. If a TCP is set, all three poses are the TCP in the base frame. A pose set that cannot form an arc raises RealtimeParameterException. An error during motion raises RealtimeMotionException.

setServoJoint()​

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

Enable servoJ for joint positions sent by real-time sendCommand, and set the call period, gain, and lookahead.

  • Parameters:
    • [in] ServoJ_T Call period, seconds
    • [in] ServoJ_Lookahead Lookahead time, limiting speed after a joint command, seconds
    • [in] ServoJ_Kp Control gain
    • [out] ec Error code

stopServoJoint()​

def stopServoJoint(self) -> None:

Disable servoJ. Call this after setServoJoint.

hasMotionError()​

def hasMotionError(self) -> bool:

Whether real-time motion has a motion error. true means there is an error.

automaticErrorRecovery()​

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

Recover the robot automatically after an error.

  • Parameter: [out] ec Error code

setFilterLimit()​

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

Set the limit-filter parameters.

  • Parameters:
    • [in] limit_rate true enables limiting
    • [in] cutoff_frequency Cutoff frequency, 0 to 1000 Hz, suggested 10 to 100 Hz
  • Return: true if the setting succeeded

setCartesianLimit()​

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

Set a Cartesian motion region. Motion stops outside it. This is a non-force-control virtual wall. If the end or the TCP leaves the safe region, the motors power off as well.

  • Parameters:
    • [in] lengths Box length, width, and height, XYZ, meters
    • [in] frame Homogeneous pose of the box center in the base frame
    • [out] ec Error code

setEndEffectorFrame()​

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

Set the end-effector pose relative to the flange. The controller stores it and restores the default after a reboot.

  • Parameters:
    • [in] frame Homogeneous matrix, units rad and m
    • [out] ec Error code

setLoad() (real-time control)​

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

Set tool and load mass, center of gravity, and inertia. The controller stores it and restores the default after a reboot. This is not the setLoad on force control or on the model.

  • Parameters:
    • [in] load Load
    • [out] ec Error code

setJointImpedance()​

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

Set joint-space impedance factors, used during joint impedance motion. Unit Nm/rad.

  • Parameter: [out] ec Error code

setCartesianImpedance()​

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

Set Cartesian impedance factors, used during Cartesian impedance motion. Order [X, Y, Z, Rx, Ry, Rz], maximum {3000, 3000, 3000, 300, 300, 300}, units N/m and Nm/rad.

  • Parameter: [out] ec Error code

setCartesianImpedanceDesiredTorque()​

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

Set the desired end force, used during Cartesian impedance motion. Allowed range {±60, ±60, ±60, ±30, ±30, ±30}, units N and N·m.

  • Parameter: [out] ec Error code

setFilterFrequency()​

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

Set controller filter cutoff frequencies used to smooth commands. Allowed 1 to 1000 Hz, suggested 10 to 100 Hz.

  • Parameters:
    • [in] jointFrequency Joint position, Hz
    • [in] cartesianFrequency Cartesian position, Hz
    • [in] torqueFrequency Joint torque, Hz
    • [out] ec Error code

setTorqueFilterCutOffFrequency()​

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

Set the filter parameter. frequency is allowed from 1 to 1000 Hz.

  • Parameter: [out] ec Error code

setFcCoor()​

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

Set the force-control frame.

  • Parameters:
    • [in] frame Homogeneous transform of the force-control frame relative to the flange
    • [in] type Task frame: FrameType.world, FrameType.tool, or FrameType.path (follows the path)
    • [out] ec Error code

setCollisionBehaviour()​

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

Set collision-detection thresholds. Active only in position control, not in force control. On a collision the controller powers off and the brakes engage.

  • Parameters:
    • [in] torqueThresholds Joint collision thresholds, unit N
    • [out] ec Error code

8 Model​

xCoreSDK_python.model always provides Model_0_3 / Model_0_4 / Model_0_6 and Model_1_5 / Model_1_6 / Model_1_7. Their calls are the existing calcIk, calcFk, and calcAllIkSolutions.

With CMake option XMATE_MODEL (off by default, macro XMATEMODEL_LIB_SUPPORTED), the build also provides xmateModel_1_5 / xmateModel_1_6 / xmateModel_1_7. The class text lists xMateER, XMC7/12/18/20, and XMS3/4. Collaborative model() then returns this class. It inherits inverse and forward kinematics. The functions below exist only on this class.

model_doc.h also describes calcIk_SearchElbow, getJointPosSearchPsi, getTorque, and getTorqueWithFriction. model_bind.cpp does not .def them, so they are not listed here.

setLoad() (model)​

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

Set the load for calculation only. It is not sent to the controller. Dynamics results change after this call.

  • Parameters:
    • [in] mass Mass
    • [in] cog Center of gravity, meters
    • [in] inertia Inertia

setTcpCoor()​

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

Set the TCP for calculation only. It is not sent to the controller. Forward and inverse results and inputs change after this call.

  • Parameters:
    • [in] f_t_ee End-effector pose relative to the flange
    • [in] ee_t_k Stiffness frame relative to the end effector

getCartPose()​

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

Cartesian position.

  • Parameters: [in] jntPos joint angles; [in] nr frame, default flange
  • Return: Row-major 4×4 pose matrix

getCartVel()​

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

Cartesian velocity.

  • Parameters: [in] jntPos joint angles; [in] jntVel joint velocities; [in] nr, default flange
  • Return: Result

getCartAcc()​

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

Get Cartesian acceleration.

  • Parameters:
    • [in] jntPos Joint angles used to compute Cartesian velocity
    • [in] jntVel Joint velocities used to compute Cartesian velocity
    • [in] jntAcc Joint accelerations used to compute Cartesian velocity
    • [in] nr Frame, default flange
  • Return: Result

getJointPos()​

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

Inverse kinematics for joint position. One pose may have several solutions; the one closest to jntInit is chosen. jntPos is cleared and then filled.

  • Parameters:
    • [in] cartPos Flange Cartesian pose
    • [in] elbow Elbow angle
    • [in] jntInit Initial joint angles
    • [out] jntPos Joint angles
  • Return:
    • -1, -2, -3: no solution; cartPos is outside the workspace
    • -4, -5: the result is far from jntInit; the equivalent speed exceeds the rated speed
    • -6, -7: the result exceeds the soft limits
    • -8: singularity

getJointVel()​

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

Inverse kinematics for joint velocity. cartVel is the flange Cartesian velocity. jntPos is the current joint position.

getJointAcc()​

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

Inverse kinematics for joint acceleration. cartAcc is the flange Cartesian acceleration. jntPos and jntVel are the current joint position and velocity.

jacobian() [1/2]​

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

Jacobian of the selected frame in the base frame, row-major. Length 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]:

Same, plus the end-effector pose in the flange frame and the stiffness frame in the end-effector frame.

getTorqueNoFriction()​

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

Joint torque without friction, unit Nm. Call setLoad() first when a load is present. The four output lists are cleared and then filled.

  • Parameters: [in] jntPos, jntVel, jntAcc; [out] trq_full total torque, trq_inertia inertia, trq_coriolis Coriolis including centrifugal, trq_gravity gravity

9 Utility​

Functions are in 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]:

Convert a scalar or an array between degrees and radians. Fixed-size variants: degToRad_array6, radToDeg_array6 (6 elements), degToRad_array16, radToDeg_array16 (16 elements). The parameter name is degrees or rad.

transMatrixToArray()​

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

Rotation matrix and translation vector to a row-major array.

transMatrixToArray_all()​

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

4×4 transform to a row-major array.

arrayToTransMatrix()​

def arrayToTransMatrix(arr) -> tuple:

Row-major array to (rotation matrix, translation vector).

arrayToTransMatrix_all()​

def arrayToTransMatrix_all(arr) -> ...:

Row-major array to a 4×4 transform.

postureToTransArray()​

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

{X, Y, Z, Rx, Ry, Rz} to a row-major homogeneous matrix.

transArrayToPosture()​

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

Row-major homogeneous matrix to {X, Y, Z, Rx, Ry, Rz}.

eulerToMatrix()​

def eulerToMatrix(euler) -> ...:

Euler angles to a rotation matrix. Order [z, y, x], radians.

eulerToQuaternion()​

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

Euler angles to quaternion {Q1, Q2, Q3, Q4}. Order [z, y, x], radians.

quaternionToEuler()​

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

Quaternion to Euler angles [Rx, Ry, Rz]. The parameters are Q1, Q2, Q3, Q4.

toolsetCalcPos()​

def toolsetCalcPos(toolset: Toolset) -> tuple:

Toolset to (external-frame transform, end-frame transform).

EndInRefToFlanInBase()​

def EndInRefToFlanInBase(base_in_world, tool_set, end_in_ref):

End pose in the external reference frame to flange pose in the base frame.

FlanInBaseToEndInRef()​

def FlanInBaseToEndInRef(base_in_world, tool_set, flan_in_base):

Flange pose in the base frame to end pose in the external reference frame.

10 Planner​

Classes are in xCoreSDK_python.planner. FollowPosition_5 / FollowPosition_6 / FollowPosition_7 are bound only when XMATE_MODEL is on, same as xmateModel.

CartMotionGenerator​

Cartesian S-curve motion.

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

Build a smooth Cartesian trajectory from path length and a speed factor. speed_factor is in [0, 1]. Speed and acceleration are the maxima times this factor. s_goal is the path length in meters.

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

ds_max is the maximum speed, default 1.0 m/s. dds_max_start and dds_max_end are start and end acceleration, default 2.5 m/s².

def getTime(self) -> float:

Total motion time, seconds.

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

Arc length at time t (seconds), written into delta_s_d. false means planning is still running. true means it has finished.

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

Synchronize the current arc length from s_init.

JointMotionGenerator​

Joint-space S-curve motion. The goal is seven joint angles.

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

Build a joint trajectory from the goal and a speed factor. It can move home or to a given position. speed_factor is in [0, 1]. q_goal is in radians.

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

Default maximum speed is 1.0 rad/s for J1–J4 and 1.25 rad/s for J5–J7. Default start and end acceleration is 2.5 rad/s².

def getTime(self) -> float:

Total motion time, seconds.

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

Joint increments at time t. delta_q_d is cleared and then filled. The return value matches the Cartesian planner.

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

Synchronize the current joint position from the initial joint angles.

FollowPosition​

Follow a Cartesian pose or joint angles. Intended for visual servoing. Present only when XMATE_MODEL is on.

def __init__(self) -> None:

Default constructor. Call init() afterwards.

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

robot is the robot instance. model is an xmateModel from robot.model(). endInFlange is the end pose in the flange frame, length 16.

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

Initialize with the robot and an xmateModel.

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

Start following. Non-blocking. After the Cartesian overload, update() must also take a Cartesian pose. After the joint overload, update() must also take joint angles. bMe_desire is the TCP pose of the end in the base frame, length 16. jnt_desire is joint angles.

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

Update the desired pose or joint angles. The type must match start(): Cartesian pose with Cartesian pose, joint angles with joint angles. Following accelerates and decelerates, and slows near the target, so targets should not be too dense. The suggested interval is at least tens of milliseconds. Joint angles are in radians.

def stop(self) -> None:

Stop following.

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

Set the speed scale. It can be changed while following. The default is 0.5. Speed is capped, and the caps cannot be changed: per-axis maximum speed is 120, 120, 180, 180, 200, 200, 200 °/s, and per-axis maximum acceleration is 500 °/s².