Unitree A1 Joint Motor User Manual

Unitree A1 Joint Motor User Manual

Add content here

1. Motor Overview

A permanent magnet synchronous motor mainly consists of two parts: the stator and the rotor. The stator is rigidly connected to the motor housing, while the rotor is rotatable and has permanent magnets attached to it.

We know that when an external magnetic field of constant direction is applied to a permanent magnet from a certain direction, the permanent magnet experiences both attractive and repulsive forces due to the external field, generating a rotational torque. Ultimately, the permanent magnet will be attracted, rotate, and come to rest in a direction parallel to the applied external magnetic field. A typical example is a compass needle in the Earth's magnetic field — the compass needle rotates until it points toward the Earth's North and South Poles (i.e., the magnetic needle aligns parallel to the geomagnetic field direction). Similarly, if this fixed magnetic field begins to rotate, the permanent magnet will rotate along with it, trying to follow the direction that minimizes the angle between the external field and its own magnetic field.

In this way, we can rotate the permanent magnet to a desired angle by rotating the magnetic field. At the same time, the torque generated by the permanent magnet in the applied external magnetic field depends on the angle between the permanent magnet's field direction and the external field direction. Therefore, we can also control the torque produced by the permanent magnet by controlling the angle between the external magnetic field and the permanent magnet's magnetic field.

From the motor perspective, this means that by controlling the magnitude and direction of the currents in the three windings of the stator, we can control the direction and magnitude of the stator's magnetic field, thereby controlling the output torque of the rotor. This control method is known as Field-Oriented Control (FOC) for permanent magnet synchronous motors.

2. Introduction to Field-Oriented Control (FOC)

FOC control has many unique advantages. It allows us to achieve "pixel-level" control of permanent magnet synchronous motors, enabling results that are unattainable with traditional motor control methods:

1. Precise control can be maintained at low speeds;
2. Motor reversal (forward/reverse rotation) can be achieved smoothly;
3. Three closed-loop controls of the motor — torque, speed, and position — can be realized;
4. Permanent magnet synchronous motors with FOC control have lower noise.

As described in the overview of permanent magnet synchronous motors, the foundation of FOC control is the rotating magnetic field. In the magnetic field vector diagram below, we can see that the three coils a, b, c of the motor stator can generate magnetic fields Ba, Bb, Bc in three directions, which together synthesize the resultant magnetic field B within the motor. Based on the current angle and angular velocity of the permanent magnet rotor, the desired output torque, and the sampled/measured currents of the three coils a, b, c, the FOC controller calculates the on/off states and durations of the voltages applied to the three coils. It then controls the on/off states of the voltages across the three coils via MOSFETs. In this way, the desired magnetic field B is synthesized, thereby driving the motor rotor to move in the desired manner.

Figure 1: Magnetic Field Vector of FOC

3. A1 Joint Motor Hardware Overview

3.1 Basic Structure of Joint Motor

The core components of the joint motor are the motor driver board, stator, rotor, and planetary gearbox. Because the motor is suitable for operating under high-speed, low-torque conditions, while our robot requires low-speed, high-torque output, the motor rotor needs to be decelerated through a gearbox before delivering torque. The general structure of the A1 joint motor is shown in Figure (1.2):

Figure 1.2: Main components of the A1 joint motor

3.2 Single-Turn Absolute Position Encoder

The encoder is a sensor used to measure the rotation angle. Encoders can be classified into several types, including incremental encoders, multi-turn absolute position encoders, and single-turn absolute position encoders. Here, we will only discuss in detail the single-turn absolute position encoder as it is actually used in the joint motor.

The single-turn absolute position encoder of the joint motor is mounted on the motor rotor. The single-turn absolute position encoder (hereinafter referred to simply as the encoder) can be thought of as a "clock dial." Every time we look at the clock, we can read the current date and time, for example, April 1st, 23:00. If two hours pass, the clock passes 24:00 on April 1st, the date increases by one day to become April 2nd, and the time restarts from 0:00, becoming 01:00 on April 2nd. For convenience in calculating elapsed time, we could also say the current time is 25:00 on April 1st. Although 25:00 exceeds the 24-hour range of a single day, this is essentially because the date has increased by one day.

The same principle applies to the single-turn absolute position encoder. Each time the system is powered on, our rotor may be at any arbitrary position. The encoder tells us the angular position of the rotor (a value between 0 and 2π). If the rotor rotates past the 2π angle position, the encoder can also record that the number of full rotations has increased by one, thereby outputting an angular position that exceeds the range of 0 to 2π. It seems that the encoder can also output angular positions beyond a single turn, so why is it called a "single-turn" absolute position encoder? The reason is that this type of encoder cannot store the number of rotations that occurred before a power loss. Let us illustrate this with the following example.

Assume the current angle value output by the encoder is 2.3π. This means that since power-on, the encoder has passed 2π, the rotation count has changed from 0 to 1, and the encoder is currently at the position 0.3π. At this moment, we power off the encoder without moving it at all. When we power it back on, the angle value output by the encoder will become 0.3π. Because the rotation count resets to 0 after power-off, the encoder only outputs the current position of 0.3π.

3.3 Hybrid Control of Joint Motor

As a highly integrated power unit, the joint motor has already encapsulated the underlying control algorithms of the motor internally. As a user, you only need to send relevant commands to the joint motor, and the motor will complete the entire process from receiving the command to outputting joint torque.

For the underlying control algorithm of the motor, the only control target required is the output torque. However, for robots, we usually need to set the position, velocity, and torque for the joints. This necessitates hybrid control of the joint motor.

The joint motors from Unitree include the following five control commands:

1. Feedforward torque: $τ_{ff}$
2. Desired angular position: $p_{des}$
3. Desired angular velocity: $ω_{des}$
4. Position stiffness: $k_p$
5. Velocity stiffness (damping): $k_d$

In the hybrid control of the joint motor, a PD controller is used to feed back the deviation of the motor's output position to the torque output as follows:

$τ = τ_{f f} + kp · (p_{des} − p) + kd · (ω_{des} − ω)$ (1.1)

In Equation (1.1), τ is the output torque of the joint motor's rotor, p is the current angular position of the motor rotor, and ω is the angular velocity of the motor rotor. When using the joint motor in practice, it is necessary to pay attention to converting the control target quantities at the motor output end into the commands sent to the motor rotor.

3.4 Wiring Connection of Unitree Joint Motor

In order to send the above five control commands to the joint motor manufactured by Unitree, we need to send the commands via a serial port. The joint motor from Unitree communicates with the host computer through an RS-485 interface, with a fixed baud rate of 4.8 MBd. For the convenience of users, we provide a USB to RS-485 adapter.

Figure 1.3: Wiring connection of the joint motor

Taking the joint motor of the quadruped robot A1 as an example, as shown in Figure (1.3). There are three interfaces provided to the user. The middle interface is the 24V DC power supply interface. The two on the sides are RS-485 interfaces, and these two RS-485 interfaces are completely equivalent. Therefore, RS-485 cables can be used to connect the motors in series (up to 3 motors in series) and control them simultaneously.

When controlling the joint motor with your own computer, in order to send commands from the host computer to the joint motor, you need to connect the RS-485 interface to the host computer via a USB to RS-485 adapter. After connecting the 24V DC power supply, the motor's green indicator light begins to flash, indicating that the motor is powered on.

3.5 Configuration of the Joint Motor

Since all the underlying motor control algorithms have already been integrated inside the motor, the host computer (typically the user's computer) only needs to handle the upper-level control and the data transmission/reception via the RS-485 serial port. To facilitate user operation of the joint motor, Unitree provides a Software Development Kit (SDK) for RS-485 serial port communication, namely unitree_actuator_sdk. This SDK is located in the folder with the same name as the accompanying code.

The unitree_actuator_sdk supports the following platforms and systems:

1. Linux systems on x86/x64 platforms
2. Linux systems on ARM32/ARM64 platforms
3. Windows systems on x64 platforms

On each supported system, the unitree_actuator_sdk provides code examples in C, C++, Python, and ROS. Users only need to follow the examples to control the motors. Below, we demonstrate how to control the motor using the Linux system as an example.

3.5.1 Check the serial port name

When connecting the USB to RS-485 adapter to the host computer, the host computer assigns a serial port name to this port. In Linux systems, this serial port name typically begins with "ttyUSB". In Windows systems, the serial port name often begins with "COM".

In Linux systems, all external devices exist in the form of files. The USB to RS-485 adapter can also be considered a "file" under the /dev folder. Open any terminal window (the shortcut key in Linux is Ctrl+Alt+t), and run the following command:

cd /dev
ls |grep ttyUSB

The cd /dev command switches the current folder to /dev, and the ls | grep ttyUSB command displays all files in the current folder whose filenames contain "ttyUSB". After running the above commands, you can obtain the serial port name currently connected to the host computer. For example, as shown in Figure (1.4), the serial port name currently connected to the host computer is ttyUSB0. Considering the folder path where the serial port is located, its complete serial port name is /dev/ttyUSB0.

Figure 1.4: Checking the serial port name on a Linux system

3.5.2 Motor ID Modification

Each motor must be assigned a unique ID, and every control command sent by the host computer also contains an ID. A motor will only execute a control command if the ID matches its own. Therefore, when multiple joint motors are connected in series on the same RS-485 bus, each motor must be assigned a unique ID in order to control them individually.

The following is the procedure for modifying a motor’s ID. First, the host computer uses broadcast mode to switch all joint motors on the RS-485 bus into ID modification mode. In this mode, the output shaft of each motor becomes an electronic ratchet — meaning that when you rotate the output shaft, you can feel a distinct, ratchet-like detent. Rotating the output shaft allows the motor’s ID to be set to the corresponding value. Finally, the host computer sends a command to the motor to save the ID, completing the ID modification process.

To enable the host computer to send the above commands, we provide a motor ID modification program. This program is located in the ChangeID_Tools folder within the unitree_actuator_sdk. The motor ID modification program is available in both Linux and Windows versions. Below, we will demonstrate how to modify the motor ID on a Linux system.

First, run the executable file ChangeID located in the Linux folder with administrator privileges:

sudo ./ChangeID

Among these, sudo means to run with administrator privileges. Therefore, after pressing Enter, you will need to enter the administrator password. Please note that in Linux, when entering the password, no indicators such as "***" will be displayed. Simply enter the password and press Enter. The following ./ChangeID indicates executing the executable file ChangeID located in the current folder (./). The program execution process is shown in Figure (1.5).

Figure 1.5: Executing the ID modification program under Linux

After starting the ChangeID program, the first step is to enter the current serial port name. As mentioned above, in this example, the serial port name is /dev/ttyUSB0. After entering it, press Enter, and all motors will enter ID modification mode.

Due to the high stiffness of the electronic ratchet on the motor's output shaft, it is recommended that the operator install a tooling screw as shown in Figure (1.6) and use a lever to rotate the motor's output shaft. It should be noted that the tooling screw is an M4 screw, and the depth of insertion must not exceed 5 mm. As shown in Figure (1.5), each time the output shaft is rotated, the motor's ID is set to 0, and so on. The ID can only be 0, 1, or 2. After rotating the output shaft of each motor, type "a" in the terminal window and press Enter to complete the motor ID modification.

3.6 Trial Run of the Python Example

Let's verify the result of the motor ID modification by making the motor spin. Since Python is a scripting language, after modifying the source code, it can be run directly without compilation. Therefore, for simplicity, we will use the Python example code in the unitree_actuator_sdk.

Figure 1.6: Tooling screws for mounting the motor output shaft

First, open the check.py file in the script folder. The first step is to modify the serial port name. If running on only one system, simply modify the serial port name under that system:

fd = c.open_set(b'\\.\COM4') // Under Windows system
fd = c.open_set(b'/dev/ttyUSB0') // Under Linux system

Next, modify the commands sent to and received from the motor:

motor_s = MOTOR_send()
motor_s1 = MOTOR_send()
motor_r = MOTOR_recv()

Among them, motor_s and motor_s1 are data packets sent to the motor, both of which are structures of the MOTOR_send type. A structure is a data packet that contains many different types of data, and we will soon demonstrate operations on structures. Similarly, motor_r is a data packet that receives commands returned by the motor, and it is a structure of the MOTOR_recv type. For the specific contents of these two structures, please refer to the script/typedef.py file, which will not be repeated here.

Next, we modify motor_s and motor_s1. First, let me explain the data contained in the MOTOR_send type structure:

1. id: The target motor ID for the current control command
2. mode: The operating mode of the target motor. 0 means stop, 5 means open-loop slow rotation, and 10 means closed-loop servo control
3. T: Feedforward torque τ_ff
4. W: Desired angular velocity ω_des
5. Pos: Desired angular position p_des
6. K_P: Position stiffness k_p
7. K_W: Velocity stiffness (damping) k_d

When the value of mode is 0 or 5, the following five control parameters have no effect. For safety reasons, we set mode = 5 for the first operation. After we send this command to the motor, the motor will continuously execute this command, i.e., open-loop slow rotation. To stop the motor, we also need to create a command that stops the motor from rotating:

motor_s.id = 0
motor_s.mode = 5
motor_s1.id = 0
motor_s1.mode = 0

In the above code, motor_s commands the motor to perform open-loop slow rotation, and motor_s1 commands the motor to stop. Before sending motor_s and motor_s1 to the motor, their data needs to be processed first:

c.modify_data(byref(motor_s))
c.modify_data(byref(motor_s1))

Below, we can send commands to the motor. The following code will use the send_recv() function to send the motor_s command to the motor once per second, and use motor_r to receive the current status of the motor, lasting for 5 seconds:

i = 0
while(i < 5):
c.send_recv(fd, byref(motor_s), byref(motor_r))
c.extract_data(byref(motor_r))
print(’*******************’)
print(’Motor torque: ’, motor_r.T)
print(’Motor position: ’, motor_r.Pos)
print(’Motor velocity: ’, motor_r.W)
time.sleep(1)
i = i + 1
c.send_recv(fd, byref(motor_s1), byref(motor_r))

In fact, if we only need the motor to run continuously, there is no need to continuously send the same command. The reason for doing so is to continuously obtain the motor's current status, such as torque, position, speed, etc. Since the motor only returns its own status after receiving a command, continuous command transmission is required. The status returned by the motor is compressed and encoded, so it needs to be decoded using the extract_data() function. After decoding, the various status values can be printed using Python's print() function. After completing the loop, send the motor_s1 command to the motor to stop it from running.

Figure (1.7) shows the result after running check.py. Since operating the serial port requires administrator privileges, we need to execute check.py in the script folder using the command sudo python3 check.py.

3.7 Motor Control Mode

In section (1.3), we mentioned that the five control parameters of the motor can be modified. Different combinations of these five parameters can form different control modes. Below, we will continue to use the example code check.py for explanation.

First, we must switch to the servo mode with mode = 10:

motor_s.mode = 10

Next, we will demonstrate the parameter settings for different control modes.

Figure 1.8: Motor output end

3.7.1 Position Mode

In position mode, the output shaft of the motor will stabilize at a fixed position. For example, if we want the motor output end to be fixed at a position of 3.14 radians, we can set the control parameters as follows:

motor_s.T = 0.0   # Unit: Nm, |T| < 128
motor_s.W = 0.0   # Unit: rad/s, |W| < 256
motor_s.Pos = 3.14 * 9.1  # Unit: rad, |Pos| < 823549
motor_s.K_P = 0.2  # 0 < K_P < 16
motor_s.K_W = 3.0  # 0 < K_W < 32

In the above parameter settings, by setting T and W to 0, a PD control for Pos is achieved. Here, K_P is the proportional coefficient, K_W is the derivative coefficient, and 9.1 is the reduction ratio. The units of each parameter are as shown in the comments (after the "#"), and due to the requirements of the parameter compression algorithm, the absolute value of each parameter must be less than the limit value.

After making the above modifications, run check.py. From the status returned by the motor, it can be seen that the motor rotor position stabilizes at 3.14 × 9.1 radians, meaning the motor output end is fixed at 3.14 radians. According to Equation 1.1, if the difference between the target position and the current position is large, the torque τ generated by the motor will also be large, resulting in a large current. If the output current limit of the power supply supplying the motor is relatively low, power supply protection may be triggered, i.e., the motor stops rotating. In this case, it is necessary to consider slowly changing motor_s.Pos to avoid generating an instantaneous extremely large torque.

3.7.2 Speed Mode

In speed mode, the output shaft of the motor will stabilize at a constant speed. To stabilize the motor output shaft speed at 5 rad/s:

motor_s.T = 0.0   # Unit: Nm, |T| < 128
motor_s.W = 5.0 * 9.1  # Unit: rad/s, |W| < 256
motor_s.Pos = 0.0   # Unit: rad, |Pos| < 823549
motor_s.K_P = 0.0   # 0 < K_P < 16
motor_s.K_W = 3.0   # 0 < K_W < 32

In speed mode, T and K_P must be 0, which constitutes a P control for W. Here, K_W is the proportional coefficient for speed.

3.7.3 Damping Mode

Damping mode is a special case of speed mode. When we set W = 0.0, the motor will maintain the shaft speed at 0. When rotated by an external force, it generates a resistive torque. The direction of this torque is opposite to the direction of rotation, and its magnitude is proportional to the rotational speed. When the external force is removed, the motor will come to a stop at its current position. Because this behavior is similar to that of a linear damper, it is called damping mode.

3.7.4 Torque Mode

In torque mode, the motor will continuously output a constant torque. However, when the motor is running idle (no load), if a large target torque is applied, the motor will keep accelerating until it reaches its maximum speed, and even then, the target torque will still not be achieved.

Below are the parameter settings for torque mode that are relatively safe under no-load conditions:

motor_s.T = 0.05 # Unit: Nm, |T|<128
motor_s.W = 0.0  # Unit: rad/s, |W|<256
motor_s.Pos = 0.0 # Unit: rad, |Pos|<823549
motor_s.K_P = 0.0 # 0 < K_P < 16
motor_s.K_W = 0.0 # 0 < K_W < 32

With these parameters, you can observe the motor gradually accelerating under a constant torque. Due to slight differences between individual motors, if the motor fails to rotate smoothly, you can increase the value of T by an appropriate amount.

3.7.5 Zero Torque Mode

Zero Torque Mode is a special torque mode. When we set T = 0.0, the motor will maintain zero torque on the shaft. At this point, the motor does not stop running; instead, it actively generates torque to counteract its own friction torque. Therefore, in zero torque mode, when you try to turn the output shaft, you will feel that the resistance of the output shaft is significantly lower than when the motor is powered off.

3.7.6 Hybrid Mode

In the actual control of a quadruped robot, the motion controller often sends feedforward torque τ_ff, target angle p_des, and target angular velocity ω_des to the joints simultaneously. The control mode used in this case is hybrid control, which is also the most frequently used control mode in our subsequent practical applications.

3.8 Porting to other host computer platforms

Considering that some users may use special host computer platforms to control the motor, we also explain here how to write your own motor control program. Following the methods described in this section, readers can send control commands to the motor and receive motor status on any platform that meets the hardware requirements. This part is intended only for the few readers who have such needs; most readers can skip it directly.

3.8.1 Communication Configuration

The motor of the A1 robot uses serial communication with the RS-485 standard and a baud rate of 4.8 MBd. The serial port has 8 data bits, no parity bit, and 1 stop bit. It should be noted that in order to increase the communication frequency of the motor, we use a very high baud rate of 4.8 MBd. Users need to check whether their hardware supports such a high baud rate.

According to the RS-485 standard, the serial communication line requires two wires: the A line and the B line. Additionally, we have added a ground wire (GND).

3.8.2 Motor Message Format for Sending and Receiving

When controlling the motor, we send a 34-byte command to the motor via the serial port, and the motor returns a 78-byte status. If no command is sent to the motor, the motor will not return a status. The format for sending commands to the motor is shown in Table 1.1, and the status format returned by the motor is shown in Table 1.2. These two tables detail the meaning of each byte in the transmitted and received messages. Below, we will explain some of the details.

First, consider bytes 13 and 14 in the command sent to the motor. These two bytes represent the feedforward torque τ_ff. Clearly, the feedforward torque τ_ff is a floating-point number (float type). However, on most platforms, a float occupies 4 bytes. To represent a floating-point number using only 2 bytes, we use a bit-shifting operation. The specific principle will not be explained here. From an application perspective, readers can think of it as multiplying the feedforward torque by 256 and then assigning it to a 2-byte signed short int variable. During this assignment, rounding is forced, allowing us to send the feedforward torque τ_ff using only two bytes. When the motor receives this data, it only needs to divide by 256 to obtain the value of the feedforward torque τ_ff. Although this operation sacrifices some precision, it is sufficient for practical applications.

Another point to note is that a 2-byte variable has a total of 16 bits. One bit is used as the sign bit, leaving 15 bits to represent the magnitude of the value. This means that the absolute value of T in the command cannot exceed 2^15. Considering that we previously multiplied the original data τ_ff by 256, its absolute value has an upper limit:

$|τ_{f f} | < \frac{2^{15}}{256}= 128$

It should also be noted that due to the forced rounding during assignment, the larger the value of τ_ff, the lower the fractional precision retained. The description "×256 times" in the explanation of variable T in Table 1.1 refers to the multiplication by 256 mentioned above. The same applies to the "times" descriptions for other variables.

At the end of both the command sending and status receiving messages, there is a 4-byte CRC check. If a data error occurs during transmission, the CRC check will fail, helping us to avoid erroneous data. We will not go into the details of the CRC algorithm here. Readers can refer directly to the following code:

It can be seen that the first parameter of the crc32_core function is a pointer ptr of type uint32_t. The uint32_t type is an unsigned 4-byte integer, and ptr points to the data on which the CRC check is to be performed. The other parameter, len, indicates the length of the data to be checked. Since the command we send has 30 bytes remaining after removing the final CRC check field — which corresponds to 7 complete uint32_t values — we need to set len = 7 when calculating the CRC for the transmitted command.

Table 1.1: Message Format of Commands Sent to the Motor

Table 1.2: Message format for receiving status from the motor

4. Motor Dimensions and Mounting

5. Motor Parameters Table

On this page

• Unitree A1 Joint Motor User Manual
• 1. Motor Overview
• 2. Introduction to Field-Oriented Control (FOC)
• 3. A1 Joint Motor Hardware Overview
• 3.1 Basic Structure of Joint Motor
• 3.2 Single-Turn Absolute Position Encoder
• 3.3 Hybrid Control of Joint Motor
• 3.4 Wiring Connection of Unitree Joint Motor
• 3.5 Configuration of the Joint Motor
• 3.5.1 Check the serial port name
• 3.5.2 Motor ID Modification
• 3.6 Trial Run of the Python Example
• 3.7 Motor Control Mode
• 3.7.1 Position Mode
• 3.7.2 Speed Mode
• 3.7.3 Damping Mode
• 3.7.4 Torque Mode
• 3.7.5 Zero Torque Mode
• 3.7.6 Hybrid Mode
• 3.8 Porting to other host computer platforms
• 3.8.1 Communication Configuration
• 3.8.2 Motor Message Format for Sending and Receiving
• 4. Motor Dimensions and Mounting
• 5. Motor Parameters Table