End-Effector Pose
Companion page: the "End-Effector Pose" tab on the console.
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_mmdefault), so the tabletop is atz ≈ 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: enteringz= 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.
UI path: "Teach" in the motion panel → "Table Height" in Telemetry → "Use Current TCP" → "Save".
- Connect the real hardware, clear the workspace, keep the e-stop within reach and support the arm with one hand.
- 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.
- 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. - Click Save. After the confirmation, the "Keep-out line z ≥ …" hint updates to the new tabletop.
- 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:
[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_rollmoves the TCP a little — the TCP is offset laterally by about 10 mm from the wrist axis (the x component oftcp_offsetis −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:
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.
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:
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:
- Click "Get current" — fills the input fields with the arm's current pose
- Change one component and click "IK pre-check" — computes without moving, so you can see whether the target is reachable
- Click "Move" — actually goes there
- Switch the
joint/linepath and run it again — same start and end, butjointmakes the TCP follow an arc andlinea straight line, entirely different trajectories. See Section 6 for the trade-offs - 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
zto 20 (below the tabletop's 30.1) → the safety layer rejects it outright with aSafetyError - Set
zto 230 andpitchto 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:
Poseinstarm/types.py,pose()/ik()instarm/kinematics.py