SO-101
Course overview/Chapter 03 · End-Effector Pose
中文
Chapter 03Kinematics~15 min

End-Effector Pose

Companion page: the "End-Effector Pose" tab on the console.

9 sections 2 figures 3 code blocks PoseFramesPath
End-effector pose page

1. Pose = position + orientation#

Position is where the point at the gripper fingertips (the TCP) sits in space; orientation is the direction the gripper points. Together they make a "pose".

This sits on a different level from joint angles:

Describes Managed by
Six joint angles How the arm is arranged The servos — the single source of truth
End-effector pose Where the tip is and which way it points Computed from the joint angles by FK

Joint angles are the low-level state; pose is the high-level representation. Give the SDK a pose and it translates it into joint angles with IK; conversely, joint angles fed through FK produce the pose. This also explains why "the pose is right" does not mean "the orientation is unique" — the same pose may correspond to different arm configurations (elbow-up / elbow-down).

2. The five components#

Pose is exactly these five numbers, in mm and degrees:

Component What it is Notes
x Left-right position Base frame; positive to the left
y Front-back position Positive backwards; negative when the arm reaches out
z Height Positive upwards; the tabletop is at 30.1 mm, not 0
pitch Approach angle Angle between the gripper's pointing direction and the horizontal plane; 90 = straight down
roll Rotation about the approach axis Equal to the wrist_roll joint angle

The first three fix "where"; the last two fix "which way".

3. Degrees of freedom: why only 5 numbers#

To pin a rigid body completely in space you need 6 DoF: 3 position + 3 orientation (roll / pitch / yaw). This arm's end effector has only 5 — the missing one is yaw.

Component Controllable Why
x / y / z Yes Determined jointly by the base rotation, upper arm and elbow
pitch Yes Provided by wrist_flex
roll Yes Provided directly by wrist_roll
yaw No Once the arm points at a location, its horizontal heading is fully determined

In other words: 3 position DoF + 2 orientation DoF = 5. That is also why Pose has five fields instead of six.

What a missing yaw means#

Once the arm points at a location, the projection of the approach direction onto the horizontal plane fixes "from which side you approach". You cannot change the gripper's horizontal heading while keeping the position.

Practical consequences:

  • To change the gripper's horizontal heading you can only change x / y — the position moves with it
  • At pitch=90 (straight down) the horizontal projection of the approach direction degenerates to zero, and yaw is not even well defined
  • Some poses "look graspable" but are angles a 5-DoF arm cannot reach

How the solver handles it#

IK solves only 4 unknowns: shoulder_pan / shoulder_lift / elbow_flex / wrist_flex, against 4 residuals (x, y, z, orientation). wrist_roll is not decided by the solver; it simply takes the target roll.

How those 4 unknowns are iterated, how the two solvers ("lm" and "riemann") differ, and why pitch = 90 is a sensitive configuration are all covered in Chapter 4: FK and IK, Section 4.

4. What these numbers are relative to: the base frame#

The x / y / z in the UI are in the base frame — the coordinates of the base link in the URDF. The origin is the origin of the base link, which lies 30.1 mm below the tabletop, not on it.

Axis Direction in the base frame
+X Left
+Y Backwards (so y is negative when the arm reaches out)
+Z Up

At the zero position the arm reaches out along −Y, with the TCP at (20.4, −381.1, 256.8) mm.

The 3D view draws these axes: the white dot is the origin, red is +X (left), green is +Y (back), blue is +Z (up). They rotate with the view, so you can always confirm which axis is which in the direction you are currently looking.

The tabletop is not at z = 0. The URDF base origin is 30.1 mm below the table (table_z_mm default), so the tabletop is at z ≈ 30.1 mm. The line in the UI reading "ground = tabletop (base frame z = 30.1 mm)" is there to remind you of this. Put another way: entering z = 0 puts the end effector 30 mm below the tabletop, and the safety layer will block it.

Confirming the tabletop height#

The tabletop height is not always 30.1 mm. Different tables, mats and base mounting heights change it; z is in the base frame, so the reliable method is to touch the real tabletop with the real TCP instead of copying the number from this page.

Confirming table height: (1) teach the TCP down to the table, (2) use the current TCP, (3) save

UI path: "Teach" in the motion panel → "Table Height" in Telemetry → "Use Current TCP" → "Save".

  1. Connect the real hardware, clear the workspace, keep the e-stop within reach and support the arm with one hand.
  2. Click Teach in the motion panel (a "Teaching mode" banner appears and torque is released). Support the TCP and lower it slowly until it just touches the tabletop.
  3. Keep the TCP still. In the Telemetry area find the Table Height input and click Use Current TCP to fill it with the current TCP z.
  4. Click Save. After the confirmation, the "Keep-out line z ≥ …" hint updates to the new tabletop.
  5. Click the finish-teaching button ("Done Teaching") to re-enable torque. From then on, the coordinate interpretation and safety layer use this tabletop height.

Notes:

  • Touch the tabletop with the TCP, not the gripper shell; lower it slowly and only make contact, do not press into the table.
  • Teaching mode has no brake; keep supporting the arm and never leave it unattended.
  • Re-check and save again after changing tables, adding a mat or changing the base mounting height; do not reuse a previous value.
  • This only tells the safety layer where the tabletop is; it does not disable the safety zone. E-stop, over-temperature and tracking error remain active.

Which point is the TCP#

The X/Y/Z in the UI is the TCP — the fixed fingertip contact point on the gripper link (not the midpoint between the two fingers), and not the gripper's rotation center:

Base-frame coordinates (mm)
Gripper rotation center (20.6, −277.5, 266.9)
TCP (20.4, −381.1, 256.8)
Separation 104.1 mm

If you change the gripper or mount a tool, this offset has to be recalibrated:

toml
[kinematics]
tcp_offset_mm = [-10.1, -0.2, -103.6]

What pitch and roll measure#

Component Definition Measured
pitch Angle between the approach direction and the horizontal plane; 90 = straight down wrist_flex=45° → pitch=45, approach (0, −0.71, −0.71)
roll Rotation about the approach axis, equal to the wrist_roll joint angle wrist_roll=90° → roll=90, approach direction unchanged

At pitch=90 the approach direction is (0, 0, −1), and the arm can then only reach about 80 mm above the tabletop.

An easy-to-miss detail: rotating wrist_roll moves the TCP a little — the TCP is offset laterally by about 10 mm from the wrist axis (the x component of tcp_offset is −10.1 mm). So "wrist roll does not affect end-effector position" is only an approximation.

The same applies in scripts#

The starm SDK exposes the base frame throughout, exactly as the UI does:

python
with Arm.sim() as arm:
    arm.move_pose(y=-200, z=90, pitch=60)   # base frame, mm
    print(arm.get_pose())                    # Pose(x=…, y=…, z=…, pitch=…, roll=…)

There is no second coordinate system to remember. The only thing to remember is still the same sentence: the tabletop is at z ≈ 30.1 mm, not 0.

INTERACTIVE LAB

Pose reader

Base frame · mm / °

Enter the five numbers and see what they actually mean in the base frame. Note that +Y is backward and −Y is forward, and that the table sits at z = 30.1 mm, not 0.

From base—mm
Above table—mm
Approach angle—°
The side view draws only the Y–Z plane; the X component appears in the top view at the lower right. The red arrow is the approach direction, not the line between the gripper's two fingers.

5. How to read a set of numbers#

When the UI shows (0, −260, 150, 65, 0), read it term by term:

Component Value Reads as
x 0 Dead center over the base, neither left nor right
y −260 260 mm in front of the base
z 150 150 mm from the base origin, i.e. about 120 mm above the tabletop
pitch 65 Gripper angled 65° downwards (only 90° is straight down)
roll 0 Gripper not rotated about its own axis

6. Two paths: joint and line#

After entering the five numbers and before clicking "Move", one more option decides "how to get there". It does not change the endpoint, only the path in between.

joint line
Method IK is solved once at the start point, then the six joint angles are interpolated independently The TCP follows a straight line in space, with IK re-solved every control cycle (30 Hz)
TCP path An arc A straight line
Speed Fast 15–20% slower

Measured (starting from the zero position, changing only the path):

Target Chord length joint deviation from straight line joint duration line deviation from straight line line duration
Forward, low 163 mm 26.2 mm 5.00 s 0.0 mm 5.85 s
Left side 247 mm 41.1 mm 4.51 s 0.0 mm 5.44 s

Why joint draws an arc: it interpolates joint angles, and the end-effector position is a nonlinear function of those angles. The six angles each change smoothly, so the tip naturally follows a curve. The longer the travel and the closer to the edge of the workspace, the more pronounced the arc.

joint#

  • Advantages: fast, simple planning; best suited to large transfers and homing
  • Risk: the arc sweeps through the space in between. When translating sideways right above the tabletop, the arc may dip into the table

line#

  • Advantages: the TCP path is predictable; suited to descending grasps, surface-following translation and obstacle avoidance
  • Cost: IK is solved once per cycle (more CPU), and it is slower — it paces against the steepest joint rate along the path, otherwise some joint would hit its speed limit and drag the TCP off the straight line
  • Extra constraint: configuration changes are forbidden during solving (allow_reseed=False). Otherwise, switching to an elbow-up / elbow-down solution midway would make the arm swing across

A built-in safety net#

Before the motion starts, line samples 32 points along the straight line and trial-solves each one. If any point is unreachable, it raises an error before moving:

text
Unreachable: straight-line path leaves the workspace 43% of the way along it: ...

How to choose#

Scenario Use
Large move from A to B, homing joint
Descending vertically to grasp / place line
Translating right above the tabletop line
Changing only roll (gripper self-rotation) Either

7. Hands-on in the UI#

Open the "End-Effector Pose" tab:

  1. Click "Get current" — fills the input fields with the arm's current pose
  2. Change one component and click "IK pre-check" — computes without moving, so you can see whether the target is reachable
  3. Click "Move" — actually goes there
  4. Switch the joint / line path and run it again — same start and end, but joint makes the TCP follow an arc and line a straight line, entirely different trajectories. See Section 6 for the trade-offs
  5. Lower the speed and run it again — the speed slider appears in both "End-Effector Pose" and "Joint Control"; change one and the other follows. It is a fraction of "the maximum joint speed the safety layer allows (60 °/s by default)": 0.4 means 24 °/s, and 0.1 leaves only 6 °/s. On the real robot, start at 0.15 and raise it once you feel comfortable

Two experiments worth doing:

  • Set z to 20 (below the tabletop's 30.1) → the safety layer rejects it outright with a SafetyError
  • Set z to 230 and pitch to 90, then click "IK pre-check" → Unreachable, because when pointing straight down the arm reaches only about 80 mm above the tabletop

8. Common misconceptions#

Statement Right? Explanation
"Pose is just joint angles" ✗ Joint angles are the low-level state; pose is what FK produces from them
"z = 0 is the tabletop" ✗ The tabletop is at 30.1 mm; z = 0 is below the table
"5 numbers means 5 DoF, so it is only slightly short of a 6-axis arm" ✗ The missing yaw is precisely what "arbitrary orientation" depends on
"Rotating wrist roll does not affect end-effector position" ≈ The TCP has about 10 mm of lateral offset, so it traces a small circle
"Arriving means the gripper arrived" ✗ What arrives is the TCP (between the fingertips), 104 mm further forward than the gripper rotation center

References#

  • Chapter 2: Robot Arm Joints — what each of the five joints controls
  • In the code: Pose in starm/types.py, pose() / ik() in starm/kinematics.py