SO-101
Course overview/Chapter 02 · Robot Arm Joints
中文
Chapter 02Kinematics~12 min

Robot Arm Joints

Companion page: the "Joint Control" tab in the console. Dragging a few sliders beats reading ten pages of text.

7 sections 1 figures 3 code blocks Degrees of freedomJointsLimits
Joint control page

1. First, the three numbers to keep straight#

On a first encounter with this arm, these are the numbers most easily confused:

Number What it is Don't mix it up with
6 Number of servos 6 servos ≠ 6 DoF
5 Number of joints (degrees of freedom, DOF) Only these 5 determine the end-effector position
4 The unknowns that IK actually solves pan / lift / elbow / wrist_flex; roll is supplied directly by wrist_roll; yaw is not controllable
1 The gripper It moves the fingers, does not change the TCP, and does not count as a DoF

In one sentence: 6 servos = 5 joints + 1 gripper.

2. From the base to the fingertip#

This is a serial chain: rotating any one link carries every link downstream with it:

text
base
 └─ Rotation                     shoulder pan (horizontal)
     └─ Pitch                    upper-arm pitch
         └─ Elbow                elbow flexion
             └─ Wrist_Pitch      wrist pitch
                 └─ Wrist_Roll   wrist roll
                     └─ Jaw      gripper moving finger

The first two columns hold the SDK name and the URDF joint name (lerobot naming / URDF naming), one-to-one:

SDK / lerobot URDF Meaning Axis URDF limit
shoulder_pan Rotation Base rotation vertical −110° to 110°
shoulder_lift Pitch Upper-arm pitch horizontal −100° to 100°
elbow_flex Elbow Elbow flexion horizontal −100° to 90°
wrist_flex Wrist_Pitch Wrist pitch horizontal −95° to 95°
wrist_roll Wrist_Roll Wrist roll along the approach axis −160° to 160°
gripper Jaw Gripper open / close — −10° to 100°

Don't use the URDF names in code. starm accepts only the first column; URDF_JOINT_NAMES does the translation internally.

3. What each joint actually does#

Joint What it determines What you see when you move it
shoulder_pan The TCP's horizontal azimuth (x and y both change), and the horizontal heading of the approach direction The whole arm sweeps across the table like a broom
shoulder_lift Working height and reach The arm rises / falls, and the end-effector traces a large arc
elbow_flex How far the end-effector is from the base The forearm folds against the upper arm, reaching out or pulling in
wrist_flex The gripper's approach angle, pitch The gripper tilts up / down; at 90 it points straight down
wrist_roll The gripper's rotation about its own axis, roll The two fingers turn, but the TCP barely moves
gripper The distance between the two fingers Opens / closes; the TCP does not move at all

A few points worth remembering#

shoulder_lift carries the heaviest load. It has to hold up every downstream link plus the payload. The flatter the arm is extended, the longer the lever arm. That is also why the nominal 500 g payload holds only in certain poses.

elbow_flex determines "how far it reaches". A given target point usually has two configurations — elbow-up and elbow-down. IK uses the seed to decide which one it converges to, and with path="line" it also forbids switching configuration along the way, otherwise the arm would sweep across.

wrist_flex is the direct source of pitch. pitch=90 means the gripper points straight down; the highest point it can reach then is only about 80 mm above the table, while pitch=75 gets to roughly 120 mm. When something is out of reach, think of this joint first.

wrist_roll is the only joint that essentially does not change the TCP position. "Essentially" because the TCP sits about 10 mm off the wrist axis laterally (the x component of tcp_offset is −10.1 mm), so strictly speaking the TCP traces a very small circle as it turns.

gripper is not a DoF. It drives only the moving finger; the static finger does not move, and neither does the TCP. It plays no part in pose measurement.

INTERACTIVE LAB

Joint workbench

URDF · live FK

Drag the five joints and see where the end effector goes. The skeleton uses the joint origins and axes from the URDF; the TCP matches the zero-pose measurement in Chapter 4, and the gripper does not affect the TCP.

JointTCPTable
X20.4mm
Y−381.1mm
Z256.8mm
PITCH0.0°
ROLL0.0°
The zero-pose TCP is (20.4, −381.1, 256.8) mm; this is the base frame, and the table sits at z = 30.1 mm. "Grasp pose" is exactly the solution from the round-trip IK experiment in Chapter 4.

4. Why 5 and not 6#

To "point the gripper in an arbitrary orientation in space" you need 3 for position + 3 for orientation = 6 DoF.

This arm has only 5, so the missing one shows up as an uncontrollable yaw:

  • position (x, y, z): three
  • approach angle pitch: one
  • wrist roll roll: one (supplied directly by wrist_roll)
  • yaw: none — it is determined by x / y

The reason is plain: once the gripper points at a given point, the horizontal projection of that direction uniquely fixes "from which side it approaches". You cannot change the gripper's horizontal heading while keeping its position.

In code this shows up as Pose having only five components:

python
Pose(x, y, z, pitch, roll)   # no yaw

pitch=90 has another side effect: the approach direction is straight down, its horizontal projection degenerates to zero, and at that point yaw is simply meaningless.

Joint count comparison#

Joints Can control Cannot do
3-axis End-effector position x / y / z Orientation is completely uncontrollable
4-axis Position + one approach angle, pitch The gripper's rotation about its own axis is fixed
5-axis · this arm Position + pitch + roll Yaw cannot be specified independently
6-axis Position + full orientation —
7-axis 6 axes + a redundant DoF — (the extra axis is used for obstacle avoidance and steering around singularities)

"Six-axis robot" in industry means 6 joints, not 6 motors. This arm is 5 joints + 1 gripper, so strictly speaking it is a 5-DoF robot arm.

For how these 5 DoF turn into 5 numbers from the end-effector pose point of view, see Chapter 3.

5. Limits: just use the joint's own bounds#

Every joint in the URDF declares <limit lower=… upper=…>, and that is the joint's real upper and lower bound. The safety layer uses it as-is: no shrinking, and no narrowing to the calibrated travel:

Joint Lower / upper bound (URDF)
shoulder_pan ±110
shoulder_lift ±100
elbow_flex −100 to 90
wrist_flex ±95
wrist_roll ±160
gripper 0 to 100 %

The gripper is the exception: the URDF specifies jaw-finger rotation (−10…100°), while the SDK commands an opening of 0–100 %, so the safety layer takes the two ends as 0 and 100 in percent.

Going out of range gives you:

text
SafetyError: shoulder_pan target 130.00 is outside soft limits [-110.0, 110.0]

There used to be an extra "soft limit" layer here: replace the URDF range with the calibrated travel, then shrink everything by 2°. Both side effects showed up in the field — the calibrated travel is symmetric about center, so the extra degrees on the longer side were thrown away (elbow_flex stopped at ±88.7 although the URDF gives −100…90); and the 2° shrink made every joint stop two degrees short of its end point. That layer is gone now.

If you want some margin (gear backlash, gravity sag after power-off), raise [safety] limit_margin_deg in ~/.starm/config.toml (default 0); to narrow the range to the measured calibrated travel, set limit_source = "calibration"; to take the intersection of the two, set "narrower".

If the arm is already outside a limit (for example it sagged after a power cut), the rule is: holding is allowed, moving back inward is allowed, moving further out is not. Otherwise it would be stuck at the boundary and reject every command.

6. Common misconceptions#

Claim Right? Explanation
"6 servos means 6 DoF" ✗ The gripper takes no part in positioning
"The gripper counts as a DoF" ✗ It only changes the distance between the fingers
"Joint angles can be set to anything" ✗ Each joint stops at its own upper/lower bound (URDF); the gripper at 0–100 %
"Wrist roll doesn't affect end-effector position" ≈ The TCP is offset about 10 mm laterally, so it traces a small circle
"A 5-axis arm can't reach it because the motors are weak" ✗ It is geometrically unreachable; Unreachable is not SafetyError

7. Hands-on in the UI#

Open the "Joint Control" tab in the console:

  1. Drag a slider — six joints, the command is sent on release, and the model on the right follows
  2. Edit the number — the field to the right of each slider takes an angle directly; press Enter to send (Esc reverts). It is quicker than dragging when you need 0.1° precision, and values beyond the joint limit are clamped to the bound automatically
  3. Click "−20° / +20°" — moves one joint only, so you can see exactly what it affects; this is the fastest way to understand the joints
  4. Watch the telemetry — end-effector pose and the six joint angles update in step
  5. Run a small experiment: set wrist_flex to 90°, then go to the "End-Effector Pose" tab, set Z to 230 and click "IK Pre-check", and you get Unreachable. That is the price of "5 DoF + pointing straight down"

Try anything in simulation; the safety layer is the same code as on the real robot. Before you try it on the real robot, take a look around.

For the coordinate frame the pose values use and the point the TCP refers to, see Chapter 3: End-Effector Pose.