Getting Started with SO-100 Robot Arms - lerobot.js (Node.js/TypeScript)

🚀 Complete setup guide for SO-100 robot arms using lerobot.js
Zero Python dependencies - pure TypeScript/JavaScript implementation

Prerequisites

Node.js 18+ (Windows, macOS, or Linux)
SO-100 robot arms (follower + leader)
USB cables for both arms

🚨 Current Implementation Status

✅ Available Now:

lerobot find-port - USB port detection
lerobot calibrate - Robot/teleoperator calibration

🔄 Coming Soon (Python equivalent shown for reference):

lerobot check-motors - Motor ID verification
lerobot setup-motors - Motor ID configuration
lerobot teleoperate - Real-time control
lerobot record - Data collection

For now, use Python lerobot for motor setup, then switch to lerobot.js for calibration!

Install lerobot.js

Option 1: Global Installation (Recommended)

# Install globally for easy access
npm install -g lerobot

# Verify installation
lerobot --help

Option 2: Use without Installation

# Use directly with npx (no installation needed)
npx lerobot --help

Option 3: Development Setup

# Clone and build from source
git clone https://github.com/timpietrusky/lerobot.js
cd lerobot.js
pnpm install
pnpm run install-global

1. Identify USB Ports

What this does: Identifies which USB port each robot arm is connected to. Essential for all subsequent commands.

Connect and Test

Connect both arms: Plug in USB + power for both follower and leader arms
Run port detection:

lerobot find-port

Example output:

Finding all available ports for the MotorsBus.
Ports before disconnecting: ['COM3', 'COM4']
Remove the USB cable from your MotorsBus and press Enter when done.

The port of this MotorsBus is 'COM3'
Reconnect the USB cable.

Repeat for second arm: Run lerobot find-port again to identify the other arm
Record the ports: Note which port belongs to which arm (e.g., COM3=leader, COM4=follower)

2. Check Motor IDs

Important: Always do this first! This checks if your robot motors are already configured correctly.

What are motor IDs? Each motor needs a unique ID (1, 2, 3, 4, 5, 6) so the computer can talk to them individually. New motors often have the same default ID (1).

Check Follower Arm

# 🔄 Coming soon - use Python lerobot for now:
python -m lerobot.check_motors --robot.port=COM4

Check Leader Arm

# 🔄 Coming soon - use Python lerobot for now:
python -m lerobot.check_motors --teleop.port=COM3

✅ If you see this - you're ready for calibration:

🎉 PERFECT! This arm is correctly configured:
   ✅ All 6 motors found: [1, 2, 3, 4, 5, 6]
   ✅ Correct baudrate: 1000000

✅ This arm is ready for calibration!

⚠️ If you see this - continue to "Setup Motors" below:

⚠️  This arm needs motor ID setup:
   Expected IDs: [1, 2, 3, 4, 5, 6]
   Found IDs: [1, 1, 1, 1, 1, 1]
   Duplicate IDs: [1] (likely all motors have ID=1)

3. Setup Motors (If Needed)

⚠️ Only do this if the motor check above showed your motors need setup!

This assigns unique ID numbers to each motor. It's a one-time process.

Safety notes:

Power down (unplug power + USB) when connecting/disconnecting motors
Connect only ONE motor at a time during setup
Remove gears from leader arm before this step

Setup Follower Arm

# 🔄 Coming soon - use Python lerobot for now:
python -m lerobot.setup_motors --robot.type=so100_follower --robot.port=COM4

Setup Leader Arm

# 🔄 Coming soon - use Python lerobot for now:
python -m lerobot.setup_motors --teleop.type=so100_leader --teleop.port=COM3

After setup: Run the motor check commands again to verify everything worked.

4. Calibrate Robot Arms

What is calibration? Teaches both arms to understand joint positions identically. Crucial for leader arm to control follower arm properly.

Why needed? Manufacturing differences mean position sensors might read different values for the same physical position.

Calibrate Follower Arm

lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm

Example output:

Calibrating device...
Device type: so100_follower
Port: COM4
ID: my_follower_arm

Connecting to so100_follower on port COM4...
Connected successfully.
Starting calibration procedure...
Initializing robot communication...
Robot communication initialized.
Reading motor positions...
Motor positions: [0.5, 45.2, 90.1, 0.0, 0.0, 0.0]
Setting motor limits...
Motor limits configured.
Calibrating motors...
  Calibrating motor 1/6...
  Motor 1 calibrated successfully.
  [... continues for all 6 motors ...]
Verifying calibration...
Calibration verification passed.
Calibration completed successfully.
Configuration saved to: ~/.cache/huggingface/lerobot/calibration/robots/so100_follower/my_follower_arm.json
Disconnecting from robot...

Calibration steps:

Move to neutral position: Position arm in standard reference pose
Move joints through range: Gently move each joint to its limits
Automatic save: Calibration data saved automatically

Calibrate Leader Arm

lerobot calibrate --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_leader_arm

Calibration steps:

Move to neutral position: Same reference pose as follower
Move through range: Test all joint movements
Button mapping: Test all buttons and triggers
Automatic save: Configuration saved

✅ After both arms are calibrated, you're ready for teleoperation!

5. Test Teleoperation

Test that your leader arm can control the follower arm:

# 🔄 Coming soon - use Python lerobot for now:
python -m lerobot.teleoperate \
  --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm \
  --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_leader_arm

Expected behavior:

Both arms connect automatically
Moving leader arm → follower arm copies movements
Press Ctrl+C to stop teleoperation

6. Record Demonstrations (Optional)

Record demonstrations for training robot learning policies:

# 🔄 Coming soon - use Python lerobot for now:
python -m lerobot.record \
  --robot.type=so100_follower --robot.port=COM4 --robot.id=my_follower_arm \
  --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_leader_arm \
  --dataset-name=my_first_dataset \
  --num-episodes=10 \
  --task="Pick up the red block and place it in the box"

CLI Command Reference

Core Commands

# Show all available commands
lerobot --help

# Find USB ports
lerobot find-port

# Calibrate robot
lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_robot

# Calibrate teleoperator
lerobot calibrate --teleop.type=so100_leader --teleop.port=COM3 --teleop.id=my_teleop

# Show calibrate help
lerobot calibrate --help

Alternative Usage Methods

# Method 1: Global installation (recommended)
lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_robot

# Method 2: Use with npx (no installation)
npx lerobot calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_robot

# Method 3: Development mode (if you cloned the repo)
pnpm run cli:calibrate -- --robot.type=so100_follower --robot.port=COM4 --robot.id=my_robot

# Method 4: Direct built CLI
node dist/cli/index.js calibrate --robot.type=so100_follower --robot.port=COM4 --robot.id=my_robot

Configuration Files

Calibration data is stored in Hugging Face compatible directories:

~/.cache/huggingface/lerobot/calibration/
├── robots/
│   └── so100_follower/
│       └── my_follower_arm.json
└── teleoperators/
    └── so100_leader/
        └── my_leader_arm.json

Environment variables:

HF_HOME: Override Hugging Face home directory
HF_LEROBOT_CALIBRATION: Override calibration directory

Troubleshooting

Port Issues

# Error: Could not connect to robot on port COM99
lerobot find-port  # Re-run to find correct ports

Solutions:

Verify robot is connected to specified port
Check no other application is using the port
Verify you have permission to access the port
Try different USB port or cable

Motor Communication Issues

# Error: Robot initialization failed

Solutions:

Check power connection to robot
Verify USB cable is working
Ensure motors are properly daisy-chained
Check motor IDs are correctly configured

Permission Issues

Windows:

# Run as administrator if needed

Linux/macOS:

# Add user to dialout group
sudo usermod -a -G dialout $USER
# Log out and back in

Browser Usage (Alternative)

You can also use lerobot.js in the browser with Web Serial API:

Build and serve:

git clone https://github.com/timpietrusky/lerobot.js
cd lerobot.js
pnpm install
pnpm run build:web
pnpm run preview

Visit: http://localhost:4173
Requirements: Chrome/Edge 89+ with HTTPS or localhost

Next Steps

✅ You now have working SO-100 robot arms with lerobot.js!

Continue with robot learning:

Add cameras for vision-based tasks
Record more complex demonstrations
Train neural network policies
Run policies autonomously

Resources:

Community:

Discord - Get help and discuss
GitHub Issues - Report bugs

🎉 Congratulations! You're now ready to use SO-100 robot arms with TypeScript/JavaScript!