Configuração do Software

Instalação do LeRobot

O LeRobot é o único pacote de software que você precisa para o SO-101. Ele gerencia a comunicação do servo, calibração, teleoperação e gravação de dados.

Crie um ambiente virtual

python -m venv ~/.venvs/so101
source ~/.venvs/so101/bin/activate   # Windows: .venvs\so101\Scripts\activate

Instale o LeRobot

pip install lerobot

Verifique a instalação

python -c "import lerobot; print(lerobot.__version__)"

Instalar a partir do código-fonte (opcional — para os recursos mais recentes)

git clone https://github.com/huggingface/lerobot.git
cd lerobot
pip install -e ".[so101]"

Configuração do Robô SO-101

O LeRobot inclui uma configuração de robô SO-101 embutida. Você especifica a porta USB para o braço seguidor (e o braço líder se estiver usando teleoperação de dois braços).

Encontre sua porta USB

# Linux / macOS
ls /dev/ttyUSB*    # typical: /dev/ttyUSB0, /dev/ttyUSB1
ls /dev/tty.usbserial*   # macOS alternative

# Windows — check Device Manager → Ports → COMx

Configuração YAML do SO-101

O LeRobot usa uma configuração inline na linha de comando ou um arquivo YAML. Para uma configuração de braço único:

# ~/.lerobot/robots/so101_follower.yaml
robot_type: so101
port: /dev/ttyUSB0   # update to your port
cameras:
  wrist_cam:
    type: opencv
    index_or_path: 0
    fps: 30
    width: 640
    height: 480

Configuração de dois braços (líder-seguidor)

# ~/.lerobot/robots/so101_bimanual.yaml
robot_type: so101
port: /dev/ttyUSB1      # follower arm
leader_arms:
  main:
    type: so101
    port: /dev/ttyUSB0   # leader arm
cameras:
  top_cam:
    type: opencv
    index_or_path: 0
    fps: 30
    width: 640
    height: 480

Testar conexão

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=none   # just connects and reads state

Você deve ver as leituras da posição das juntas impressas. Se você receber um erro de porta, verifique Solução de Problemas.

Calibração do Servo

Ao contrário dos braços CAN-bus que usam encoders absolutos, os servos Feetech STS3215 precisam de calibração para definir suas posições zero. O LeRobot lida com isso automaticamente.

Executar calibração

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=calibrate

O script solicitará que você mova o braço para posições específicas (inicial, mínima, máxima para cada junta) e pressione Enter em cada posição. Ele salva os dados de calibração em ~/.cache/huggingface/lerobot/calibration/so101/.

Posições de calibração

O LeRobot pedirá que você posicione cada junta em três poses:

• Posição inicial: braço totalmente estendido, efetor final apontando para frente
• Posição de torque zero: braço pendurado naturalmente sob a gravidade
• Referência de 90 graus: cada junta em seu ponto médio

Verificar calibração

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=teleoperate   # move arm by hand to verify joint readout

Mova o braço manualmente (modo de conformidade). As posições das juntas devem ler perto de zero na posição inicial e aumentar/diminuir suavemente à medida que você move cada junta.

Teleoperação Líder–Seguidor

O SO-101 é projetado para teleoperação líder-seguidor: um braço (líder) captura os movimentos da sua mão, e o segundo braço (seguidor) os espelha em tempo real. Isso produz as demonstrações de treinamento de mais alta qualidade.

Iniciar teleop líder-seguidor

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB1 \
  --robot.leader_arms.main.type=so101 \
  --robot.leader_arms.main.port=/dev/ttyUSB0 \
  --control.type=teleoperate

Teleop de teclado com um braço (sem segundo braço)

Se você só tem um braço, use o modo de controle por teclado:

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=teleoperate \
  --control.teleop_keys=true

Modo de conformidade / compensação de gravidade

Coloque o braço líder em modo de baixo torque para que você possa movê-lo livremente com a mão:

python -c "
from lerobot.common.robot_devices.robots.so101 import SO101Robot
robot = SO101Robot(port='/dev/ttyUSB0')
robot.connect()
robot.set_compliance_mode(True)   # arm moves freely under hand guidance
"

Início Rápido da API Python

Você pode controlar o SO-101 diretamente via API do robô LeRobot sem os scripts CLI.

Controle básico das juntas

from lerobot.common.robot_devices.robots.so101 import SO101Robot
import torch

robot = SO101Robot(port="/dev/ttyUSB0")
robot.connect()

# Read current joint positions (6 DOF)
obs = robot.capture_observation()
print("Joint positions:", obs["observation.state"])

# Send joint position command (in degrees, normalized to [-1, 1] range)
action = torch.zeros(6)   # all joints to zero position
robot.send_action(action)

robot.disconnect()

Compensação de gravidade (modo reversível)

from lerobot.common.robot_devices.robots.so101 import SO101Robot

robot = SO101Robot(port="/dev/ttyUSB0")
robot.connect()

# Enable backdrive — arm can be moved freely by hand
robot.set_compliance_mode(True)

import time
for _ in range(100):
    obs = robot.capture_observation()
    print(obs["observation.state"])   # prints live joint positions as you move arm
    time.sleep(0.02)

robot.disconnect()

Lendo o status do servo

from lerobot.common.robot_devices.motors.feetech import FeetechMotorsBus

bus = FeetechMotorsBus(port="/dev/ttyUSB0",
                       motors={"joint1": (1, "sts3215"),
                               "joint2": (2, "sts3215"),
                               "joint3": (3, "sts3215"),
                               "joint4": (4, "sts3215"),
                               "joint5": (5, "sts3215"),
                               "gripper": (6, "sts3215")})
bus.connect()
positions = bus.read("Present_Position", ["joint1", "joint2", "joint3"])
print("Positions:", positions)
bus.disconnect()

3 Principais Problemas Comuns

# Check if the device is listed
ls /dev/ttyUSB*   # Linux
ls /dev/tty.usbserial*   # macOS

# Linux: add yourself to the dialout group (requires logout)
sudo usermod -aG dialout $USER

# Windows: install CP2102 or CH340 USB driver,
# then check Device Manager for COM port number

# 1. Verify 5V power supply is connected and LED on servo board is on
# 2. Check all servo daisy-chain cables are fully seated
# 3. Try scanning for servos directly:
python -c "
from lerobot.common.robot_devices.motors.feetech import FeetechMotorsBus
bus = FeetechMotorsBus('/dev/ttyUSB0', motors={})
bus.connect()
ids = bus.find_motor_ids()
print('Found motor IDs:', ids)
bus.disconnect()
"

# Check calibration file location
ls ~/.cache/huggingface/lerobot/calibration/so101/

# Re-run calibration if the file is missing
python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=calibrate

# Pass explicit calibration path if needed
python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --robot.calibration_dir=/path/to/calibration \
  --control.type=teleoperate

Ainda preso? Pergunte no Fórum SO-101 ou verifique o Problemas do GitHub do LeRobot.