lerobot-find-joint-limits

Discover joint position limits and end-effector bounds via teleoperation

The lerobot-find-joint-limits command helps you determine the physical limits of robot joints and end-effector workspace by moving the robot through its full range of motion during teleoperation.

Command

lerobot-find-joint-limits [OPTIONS]

Location: src/lerobot/scripts/lerobot_find_joint_limits.py

Overview

This script:

• Records joint positions during teleoperation
• Computes min/max limits for each joint
• Calculates end-effector (x, y, z) workspace bounds
• Uses forward kinematics from URDF
• Outputs limits in radians and meters
• Includes warmup phase for safe operation

Key Options

Robot Configuration

--robot.type · str · required

Robot type (e.g., so100_follower, koch_follower).

--robot.port · str · required

Serial port for robot connection.

--robot.id · str · required

Unique robot identifier.

Teleoperator Configuration

--teleop.type · str · required

Teleoperator type (e.g., so100_leader, koch_leader).

--teleop.port · str · required

Serial port for teleoperator.

--teleop.id · str · required

Unique teleoperator identifier.

Kinematics Configuration

--urdf_path · str · required

Path to robot URDF file for forward kinematics.

--target_frame_name · str · default: "gripper"

End-effector frame name in URDF.

Recording Configuration

--teleop_time_s · float · default: "30"

Duration of recording phase in seconds.

--warmup_time_s · float · default: "5"

Duration of warmup phase in seconds.

--control_loop_fps · int · default: "30"

Control loop frequency in Hz.

Usage Examples

Find Limits for SO-100 Robot

lerobot-find-joint-limits \
  --robot.type=so100_follower \
  --robot.port=/dev/ttyUSB0 \
  --robot.id=follower \
  --teleop.type=so100_leader \
  --teleop.port=/dev/ttyUSB1 \
  --teleop.id=leader \
  --urdf_path=/path/to/SO-ARM100/Simulation/SO101/so101_new_calib.urdf \
  --target_frame_name=gripper \
  --teleop_time_s=60 \
  --warmup_time_s=10

Find Limits for Koch Robot

lerobot-find-joint-limits \
  --robot.type=koch_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.id=koch \
  --teleop.type=koch_leader \
  --teleop.port=/dev/ttyACM1 \
  --teleop.id=koch_leader \
  --urdf_path=/path/to/koch.urdf \
  --target_frame_name=end_effector \
  --teleop_time_s=45

Quick Test with Short Recording

lerobot-find-joint-limits \
  --robot.type=so100_follower \
  --robot.port=/dev/ttyUSB0 \
  --robot.id=test \
  --teleop.type=so100_leader \
  --teleop.port=/dev/ttyUSB1 \
  --teleop.id=test_leader \
  --urdf_path=./robot.urdf \
  --teleop_time_s=15 \
  --warmup_time_s=3

Workflow

1. Warmup Phase

Script output:

========================================
  WARMUP PHASE (5s)
  Move the robot freely to ensure control works.
  Data is NOT being recorded yet.
========================================

During warmup:

• Test teleoperation control
• Verify robot responds correctly
• Check for any connectivity issues
• Data is not recorded

2. Recording Phase

Script output:

========================================
  RECORDING STARTED
  Move robot to ALL joint limits.
  Press Ctrl+C to stop early and save results.
========================================

Time remaining: 60.0s

During recording:

• Move each joint to its minimum position
• Move each joint to its maximum position
• Explore full workspace
• Cover all reachable positions
• Script tracks min/max values

3. Results Output

Script output:

Disconnecting devices...

========================================
FINAL RESULTS
========================================

# End Effector Bounds (x, y, z):
max_ee = [0.4521, 0.3245, 0.5612]
min_ee = [-0.1234, -0.3456, 0.0123]

# Joint Position Limits (radians):
max_pos = [3.1416, 1.5708, 2.0944, 1.5708, 3.1416, 2.0944]
min_pos = [-3.1416, -1.5708, -2.0944, -1.5708, -3.1416, -2.0944]

Understanding the Results

End Effector Bounds

Format: [x, y, z] in meters

max_ee = [0.4521, 0.3245, 0.5612]
min_ee = [-0.1234, -0.3456, 0.0123]

• x: Forward/backward extent
• y: Left/right extent
• z: Up/down extent

Workspace volume:

• X range: min_ee[0] to max_ee[0]
• Y range: min_ee[1] to max_ee[1]
• Z range: min_ee[2] to max_ee[2]

Joint Position Limits

Format: Radians for each joint

max_pos = [3.1416, 1.5708, 2.0944, 1.5708, 3.1416, 2.0944]
min_pos = [-3.1416, -1.5708, -2.0944, -1.5708, -3.1416, -2.0944]

For a 6-DOF arm:

• Index 0: Shoulder pan
• Index 1: Shoulder lift
• Index 2: Elbow flex
• Index 3: Wrist flex
• Index 4: Wrist roll
• Index 5: Gripper

Convert to degrees:

import numpy as np
max_deg = np.degrees(max_pos)
min_deg = np.degrees(min_pos)

Using the Results

Validate Joint Limits

Compare discovered limits to URDF or specification:

# Your discovered limits
max_pos = [3.1416, 1.5708, 2.0944, 1.5708, 3.1416, 2.0944]
min_pos = [-3.1416, -1.5708, -2.0944, -1.5708, -3.1416, -2.0944]

# URDF or spec limits
urdf_max = [3.14, 1.57, 2.09, 1.57, 3.14, 2.09]
urdf_min = [-3.14, -1.57, -2.09, -1.57, -3.14, -2.09]

# Add safety margin (5 degrees = 0.087 radians)
margin = 0.087
safe_max = [m - margin for m in max_pos]
safe_min = [m + margin for m in min_pos]

Configure Workspace Bounds

Use end-effector bounds for task planning:

from lerobot.envs.workspace import WorkspaceBounds

bounds = WorkspaceBounds(
    x_min=-0.1234,
    x_max=0.4521,
    y_min=-0.3456,
    y_max=0.3245,
    z_min=0.0123,
    z_max=0.5612,
)

# Check if point is reachable
point = [0.3, 0.1, 0.2]
is_reachable = bounds.contains(point)

Update Robot Configuration

Add limits to robot config:

class MyRobotConfig:
    # Joint limits (radians)
    joint_limits_min = [-3.1416, -1.5708, -2.0944, -1.5708, -3.1416, -2.0944]
    joint_limits_max = [3.1416, 1.5708, 2.0944, 1.5708, 3.1416, 2.0944]
    
    # Workspace bounds (meters)
    workspace_min = [-0.1234, -0.3456, 0.0123]
    workspace_max = [0.4521, 0.3245, 0.5612]

Best Practices

Thorough Exploration

1. Move slowly: Avoid sudden movements that might miss limits
2. Test each joint: Move one joint at a time to extremes
3. Explore workspace: Move end-effector to corners and edges
4. Multiple passes: Go through the range twice to confirm limits
5. Use full time: Don’t rush; use the full teleop_time_s

Safety

1. Check workspace: Ensure clear area around robot
2. Emergency stop: Know how to stop the robot
3. Start slow: Use warmup to verify control
4. Watch temperatures: Monitor for overheating
5. Add margins: Use discovered limits minus safety margin

URDF Selection

SO-100/SO-101 robots:

• Use official URDF from SO-ARM100 repo
• Recommended: Simulation/SO101/so101_new_calib.urdf
• Contains accurate kinematic parameters

Custom robots:

• Ensure URDF matches physical robot
• Verify joint names and frame definitions
• Test forward kinematics accuracy

Troubleshooting

Kinematics Initialization Failed

Error:

Error initializing kinematics: ...
Ensure URDF path and target frame name are correct.

Solutions:

• Check --urdf_path points to valid file
• Verify --target_frame_name exists in URDF
• Test URDF in simulation first
• Check URDF syntax is valid

Robot Not Moving

During warmup:

• Verify robot and teleop are connected
• Check ports are correct
• Ensure devices are calibrated
• Test with lerobot-teleoperate first

Incomplete Coverage

If limits seem too narrow:

• Increase --teleop_time_s (e.g., 60-120 seconds)
• Move more systematically through workspace
• Test individual joints separately
• Run multiple sessions and combine results

Port Connection Errors

See lerobot-find-port for port identification.

Advanced Usage

Multiple Recording Sessions

Combine results from multiple runs:

import numpy as np

# Run 1
max_pos_1 = [3.1, 1.5, 2.0, 1.5, 3.1, 2.0]
min_pos_1 = [-3.1, -1.5, -2.0, -1.5, -3.1, -2.0]

# Run 2
max_pos_2 = [3.14, 1.55, 2.05, 1.52, 3.14, 2.05]
min_pos_2 = [-3.14, -1.55, -2.05, -1.52, -3.14, -2.05]

# Combined limits (take extremes)
final_max = np.maximum(max_pos_1, max_pos_2).tolist()
final_min = np.minimum(min_pos_1, min_pos_2).tolist()

See Also

• lerobot-calibrate - Calibrate motor positions
• lerobot-teleoperate - Test robot control
• Robot Control - Robot control concepts
• SO-ARM100 Repository - URDF files