xArm-Python-SDK Docs

xArm Wiki
1

1. xArm-Python-SDK Installation

1. Introduction

This tutorial is written using the UFACTORY xArm 6 robotic arm, Windows system, and Python version 3.12.6
The xArm-Python-SDK is used for controlling UFACTORY robotic arms, such as xArm, Lite6, and 850.
Note: The xArm-Python-SDK only supports Python 3, and Python 3.10 or above is recommended.

2. Prerequisites

Before reading this tutorial, make sure you have:

  • Familiarity with operating UFACTORY robotic arms.
  • Understanding of Python 3 syntax and experience in Python programming.
  • Knowledge of managing Python virtual environments.

3. Installation

3.1 Install via pip [Recommended]

In a Python virtual environment, use pip to install the xarm-python-sdk with the following command:

pip install xarm-python-sdk

3.2 Install from Github Download

Download

git clone https://github.com/xArm-Developer/xArm-Python-SDK.git

Install via Command

After extracting, navigate to the \xArm-Python-SDK-master folder, and use the following command to install.

  • Windows
python setup.py install
  • Ubuntu Linux
python3 setup.py install

2. Linear motion

1. Linear Motion

Initialization

Assume the robotic arm controller’s IP address is 192.168.1.47, initialize the robotic arm.

from xarm.wrapper import XArmAPI  
arm=XArmAPI('192.168.1.47')

Enable

If the robotic arm is not enabled, it needs to be enabled. Once enabled, there is no need to enable it again.

arm.motion_enable(enable=True)

Set Mode and State

After enabling, you need to set the mode and state for the robotic arm to move.
The robotic arm has multiple modes; the commonly used linear motion and joint motion are both position commands, i.e., mode 0.

arm.set_mode(0)

The robotic arm can be set to various modes. Mode 0 is for motion, mode 3 is for pausing the motion, and mode 4 is for stopping the motion.

arm.set_state(0)

Send Position Command

In the xArm-Python-SDK, the Cartesian position is defined as x, y, z, roll, pitch, yaw.
The unit for distance is millimeters (mm), and the default angle representation is degrees (°).

As an example of linear motion in Cartesian space, let the robotic arm move to point A [300,0,150,180,0,0] first, and then to point B [400,0,150,180,0,0].

arm.set_position(300,0,150,180,0,0)  
arm.set_position(400,0,150,180,0,0)

Speed

In the set_position() interface for linear motion, the speed is passed with the speed parameter, and the unit is mm/s.
For example, let the robotic arm move to point A [300,100,150,180,0,0] at 200 mm/s.

arm.set_position(300,100,150,180,0,0, speed=200)

Complete Example

from xarm.wrapper import XArmAPI  
arm = XArmAPI('192.168.1.47')  
arm.motion_enable(enable=True)  
arm.set_mode(0)  
arm.set_state(0)  
  
arm.set_position(300,0,150,180,0,0, speed=200)  
arm.set_position(400,0,150,180,0,0, speed=200)

3. Continuous Linear Motion

Waiting

In the set_position() interface for linear motion, the wait parameter is used to set whether to wait or not.

  • wait=True means that the next command to the robotic arm will be sent only after the current command is completed.
  • wait=False means that after sending the current command, the next command will be sent immediately regardless of whether the robotic arm has completed its execution.

For example, to make the robotic arm move to the following four points (A, B, C, D) at a speed of 200 mm/s without waiting between commands:

  • Point A: [300, 100, 150, 180, 0, 0]
  • Point B: [300, -100, 150, 180, 0, 0]
  • Point C: [400, -100, 150, 180, 0, 0]
  • Point D: [400, 100, 150, 180, 0, 0]

The complete code is as follows:

from xarm.wrapper import XArmAPI  
arm = XArmAPI('192.168.1.47')  

arm.motion_enable(enable=True)  
arm.set_mode(0)  
arm.set_state(0)

arm.set_position(300, 100, 150, 180, 0, 0, speed=200, wait=False)  
arm.set_position(300, -100, 150, 180, 0, 0, speed=200, wait=False)  
arm.set_position(400, -100, 150, 180, 0, 0, speed=200, wait=False)  
arm.set_position(400, 100, 150, 180, 0, 0, speed=200, wait=False)

Blending Radius

The blending radius is similar to the turning radius of a car. When a blending radius greater than 0 is set, the robotic arm’s trajectory becomes smoother during turns.
In the set_position() interface for linear motion, the blending radius is passed through the radius parameter.
The radius parameter is only effective when wait=False, and its setting affects the continuity of the trajectory.

The table below shows the relationship between trajectory continuity and the wait and radius parameters:

Parameter radius < 0 radius ≥ 0
wait=True Discontinuous Discontinuous
wait=False Discontinuous Continuous

Therefore, continuous linear motion can only be achieved when wait=False and radius ≥ 0.

Continuous Linear Motion

The conditions required for continuous linear motion are:

  • At least two Cartesian commands are needed.
  • wait=False
  • radius ≥ 0

The following is an example of continuous linear motion with a blending radius of 5 mm:

from xarm.wrapper import XArmAPI  
arm=XArmAPI('192.168.1.47')  
arm.motion_enable(enable=True)  
arm.set_mode(0)  
arm.set_state(0)  
  
arm.set_position(300,100,150,180,0,0,speed=200,wait=False,radius=5)  
arm.set_position(300,-100,150,180,0,0,speed=200,wait=False,radius=5)  
arm.set_position(400,-100,150,180,0,0,speed=200,wait=False,radius=5)  
arm.set_position(400,100,150,180,0,0,speed=200,wait=False,radius=5)