Robot Arm Joints
Companion page: the "Joint Control" tab in the console. Dragging a few sliders beats reading ten pages of text.
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:
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.
starmaccepts only the first column;URDF_JOINT_NAMESdoes 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.
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 bywrist_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:
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:
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_degin~/.starm/config.toml(default 0); to narrow the range to the measured calibrated travel, setlimit_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:
- Drag a slider — six joints, the command is sent on release, and the model on the right follows
- 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
- Click "−20° / +20°" — moves one joint only, so you can see exactly what it affects; this is the fastest way to understand the joints
- Watch the telemetry — end-effector pose and the six joint angles update in step
- Run a small experiment: set
wrist_flexto 90°, then go to the "End-Effector Pose" tab, set Z to 230 and click "IK Pre-check", and you getUnreachable. 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.