TRLC-DK1

Configuración del software

Instalación de complementos, configuración de brazo líder/seguidor, control bimanual ROS2, integración de LeRobot DK1, API de Python y solución de problemas. Desde una instalación fresca de Ubuntu hasta un sistema bimanual en movimiento.

Ir a una sección:

› Instalación del SDK › Configuración de Líder/Secundario › Configuración Bimanual de ROS2 › Configuración de LeRobot DK1 › API de Python › Simulación › Solución de problemas

Paso 1 — Instalación del SDK

Instalación del SDK

El SDK de DK1 se distribuye como un plugin de LeRobot a través del trlc-dk1 repositorio. Registra cuatro tipos de dispositivos: dk1_leader, dk1_follower, bi_dk1_leader, y bi_dk1_follower.

Instala LeRobot primero

pip install lerobot

Clona e instala el plugin de DK1

git clone https://github.com/TRLC-AI/trlc-dk1.git
cd trlc-dk1
uv pip install -e .

Verifica la instalación

python3 -c "from lerobot.common.robots import make_robot; print('DK1 plugin OK')"

# Check that DK1 device types are registered
python3 -c "
from lerobot.common.robots.factory import get_robot_types
types = get_robot_types()
for t in types:
    if 'dk1' in t:
        print(t)
"

Deberías ver dk1_leader, dk1_follower, bi_dk1_leader, bi_dk1_follower impreso. Si no, asegúrate de que el plugin se instaló correctamente con uv pip show trlc-dk1.

Instalar desde un commit específico (para reproducibilidad)

cd trlc-dk1
git checkout v0.3.0
uv pip install -e .

📄 Guía Rápida del SDK (wiki) 📄 Referencia Completa de la API (wiki)

Paso 2 — Configuración de Líder/Secundario

Configuración del Brazo Líder/Secundario

El sistema bimanual del DK1 se basa en la asignación de puertos para distinguir el brazo líder (Dynamixel XL330) del brazo secundario (DM4340 + DM4310). Las asignaciones de puertos incorrectas son el error de configuración más común.

Detectar puertos seriales USB

Ejecuta la utilidad de detección de puertos de LeRobot con un brazo conectado a la vez:

# Connect ONLY the leader arm (Dynamixel XL330)
python -m lerobot.scripts.find_motors_bus_port
# Note the reported port, e.g. /dev/ttyACM0

# Disconnect leader, connect ONLY the follower arm (DM series)
python -m lerobot.scripts.find_motors_bus_port
# Note the reported port, e.g. /dev/ttyACM1

Crear la configuración del robot bimanual

Crea un archivo de configuración YAML para el par bimanual. LeRobot utiliza esto para dirigir comandos al brazo correcto:

# ~/.lerobot/robots/dk1_bimanual.yaml
robot_type: bi_dk1_follower
leader_arms:
  left:
    port: /dev/ttyACM0
    motors: [shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper_left, gripper_right]
follower_arms:
  left:
    port: /dev/ttyACM1
    motors: [shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper_left, gripper_right]
cameras:
  wrist_left:
    type: opencv
    index: 0
    fps: 30
    width: 640
    height: 480
  overhead:
    type: opencv
    index: 2
    fps: 30
    width: 640
    height: 480

Verifica la configuración

python -m lerobot.scripts.control_robot \
  --robot.type=bi_dk1_follower \
  --robot.config=~/.lerobot/robots/dk1_bimanual.yaml \
  --control.type=none

Esto se conecta a ambos brazos sin moverlos. Verifica si hay errores de conexión. Si alguno de los brazos no se conecta, vuelve a ejecutar la detección de puertos o intercambia las asignaciones de puertos.

Persistencia de puertos: Los puertos seriales USB pueden cambiar entre reinicios. Usa reglas de udev para vincular un puerto a un brazo específico por número de serie USB. Consulta el Guía de Configuración para la plantilla de regla de udev.

Paso 3 — Configuración Bimanual de ROS2

Control Bimanual de ROS2

ROS2 Humble proporciona una capa de control de nivel superior para el DK1 con soporte completo para planificación bimanual de MoveIt2. Esto es opcional para flujos de trabajo de recopilación de datos solo de LeRobot.

Instala ROS2 Humble y paquetes bimanuales

sudo apt update && sudo apt install ros-humble-desktop \
  ros-humble-ros2-control ros-humble-ros2-controllers \
  ros-humble-moveit ros-humble-joint-state-publisher-gui -y

Clona y construye el paquete ROS2 DK1

mkdir -p ~/dk1_ws/src && cd ~/dk1_ws/src
git clone https://github.com/TRLC-AI/trlc-dk1-ros2.git
cd ~/dk1_ws
source /opt/ros/humble/setup.bash
colcon build --symlink-install

Inicia en modo bimanual

source ~/dk1_ws/install/setup.bash

# Launch both arms (use_fake_hardware for testing without hardware)
ros2 launch trlc_dk1_ros2 dk1_bimanual.launch.py \
  use_fake_hardware:=false \
  leader_port:=/dev/ttyACM0 \
  follower_port:=/dev/ttyACM1

Prueba con hardware simulado (no se necesitan brazos)

ros2 launch trlc_dk1_ros2 dk1_bimanual.launch.py \
  use_fake_hardware:=true

Envía una trayectoria bimanual

ros2 topic pub /follower_left/joint_trajectory_controller/joint_trajectory \
  trajectory_msgs/msg/JointTrajectory \
  '{joint_names: ["shoulder_pan"], points: [{positions: [0.3], time_from_start: {sec: 2}}]}'

Paso 4 — Configuración de LeRobot DK1

Configuración de LeRobot DK1

LeRobot con el complemento DK1 maneja la grabación de teleoperación bimanual de forma nativa. El bi_dk1_follower tipo de dispositivo graba desde ambos brazos y todas las cámaras simultáneamente.

Calibra ambos brazos

# Calibrate the leader arm
python -m lerobot.scripts.control_robot \
  --robot.type=dk1_leader \
  --robot.port=/dev/ttyACM0 \
  --control.type=calibrate

# Calibrate the follower arm
python -m lerobot.scripts.control_robot \
  --robot.type=dk1_follower \
  --robot.port=/dev/ttyACM1 \
  --control.type=calibrate

Inicia la teleoperación bimanual

python -m lerobot.scripts.control_robot \
  --robot.type=bi_dk1_follower \
  --robot.config=~/.lerobot/robots/dk1_bimanual.yaml \
  --control.type=teleoperate

Graba un conjunto de datos bimanual

python -m lerobot.scripts.control_robot \
  --robot.type=bi_dk1_follower \
  --robot.config=~/.lerobot/robots/dk1_bimanual.yaml \
  --control.type=record \
  --control.fps=30 \
  --control.repo_id=your-username/dk1-bimanual-pick-place-v1 \
  --control.num_episodes=50 \
  --control.single_task="Bimanual: pick up the block with left arm, transfer to right arm" \
  --control.warmup_time_s=5 \
  --control.reset_time_s=10

Empuje al HuggingFace Hub

huggingface-cli login
python -m lerobot.scripts.push_dataset_to_hub \
  --repo_id=your-username/dk1-bimanual-pick-place-v1

Paso 5 — API de Python

API de Python para Control Bimanual

La API de Python DK1 proporciona acceso directo a ambos brazos a través de serie. No se requiere ROS2 para control básico y registro de datos.

Conectar ambos brazos

from trlc_dk1 import DK1Leader, DK1Follower, BimanualDK1

# Connect individually
leader = DK1Leader(port="/dev/ttyACM0")
follower = DK1Follower(port="/dev/ttyACM1")
leader.connect()
follower.connect()

# Or use the bimanual controller (recommended)
robot = BimanualDK1(
    leader_port="/dev/ttyACM0",
    follower_port="/dev/ttyACM1"
)
robot.connect()

Leer estados de las articulaciones de ambos brazos

import time
from trlc_dk1 import BimanualDK1

robot = BimanualDK1(leader_port="/dev/ttyACM0", follower_port="/dev/ttyACM1")
robot.connect()

for _ in range(100):
    leader_state = robot.get_leader_state()
    follower_state = robot.get_follower_state()
    print(f"Leader:   {leader_state.positions}")
    print(f"Follower: {follower_state.positions}")
    time.sleep(0.033)  # 30 Hz

robot.disconnect()

Ejecutar el bucle líder-seguidor manualmente

from trlc_dk1 import BimanualDK1
import time

robot = BimanualDK1(leader_port="/dev/ttyACM0", follower_port="/dev/ttyACM1")
robot.connect()
robot.enable_follower()

try:
    while True:
        leader_state = robot.get_leader_state()
        # Apply leader positions to follower (scaled if needed)
        robot.set_follower_positions(leader_state.positions)
        time.sleep(0.01)  # 100 Hz control loop
finally:
    robot.disable_follower()
    robot.disconnect()

📄 Guía rápida del SDK 📄 Referencia Completa de la API

Opcional — Simulación

Soporte de Simulación

El DK1 soporta simulación bimanual MuJoCo con un modelo calibrado que refleja la cinemática del hardware real. Entrena políticas en simulación antes de desplegarlas en hardware.

Simulación bimanual MuJoCo

pip install mujoco
git clone https://github.com/TRLC-AI/trlc-dk1-mujoco.git
cd trlc-dk1-mujoco

# Run the bimanual simulation with leader/follower
python examples/bimanual_sim.py

# Run with keyboard teleop
python examples/bimanual_sim.py --teleop keyboard

Entrenar una política contra el entorno MuJoCo

python -m lerobot.scripts.train \
  --policy.type=act \
  --env.type=dk1_bimanual_sim \
  --policy.chunk_size=100 \
  --training.num_epochs=5000 \
  --output_dir=outputs/dk1-act-sim

Alineación Sim-a-Real: El modelo MuJoCo DK1 utiliza la geometría del archivo STEP TRLC-DK1-Follower_v0.3.0 y curvas de torque de motor DM4340/DM4310 medidas. Las políticas entrenadas en simulación se transfieren al hardware real con un ajuste mínimo para tareas estructuradas de recogida y colocación.

Solución de problemas

Principales 3 Problemas Específicos de Bimanual

Error 1 Brazos asignados al mismo puerto — el seguidor refleja al líder pero se retrasa mucho

Ambos brazos conectados al mismo /dev/ttyACM* puerto, o asignaciones de puerto intercambiadas. El brazo líder (Dynamixel XL330) y el brazo seguidor (serie DM) utilizan diferentes protocolos; una asignación incorrecta causa un fallo de control inmediato.

Solución:

# 1. Unplug both arms
# 2. Connect ONLY the leader arm (XL330 servos)
python -m lerobot.scripts.find_motors_bus_port
# Note: leader_port = /dev/ttyACM?

# 3. Disconnect leader, connect ONLY the follower arm (DM servos)
python -m lerobot.scripts.find_motors_bus_port
# Note: follower_port = /dev/ttyACM?

# 4. Update your YAML config with the correct ports
# 5. Create udev rules to make assignments permanent

Error 2 El brazo seguidor oscila o se pasa durante la teleoperación

Las ganancias PD del brazo seguidor son demasiado altas para la carga actual o la configuración del brazo. Esto es especialmente común cuando los brazos están cargados con efectores finales o cuando operan a plena extensión.

Solución:

# Reduce follower PD gains in the DK1 config
# Edit trlc-dk1/configs/follower_gains.yaml:
joint_gains:
  default:
    kp: 30   # reduce from default 50
    kd: 0.5  # reduce from default 1.0
  wrist:
    kp: 15   # wrist joints need lower gains
    kd: 0.3

# Apply and restart teleoperation
python -m lerobot.scripts.control_robot \
  --robot.type=bi_dk1_follower \
  --control.type=teleoperate

Error 3 Los fotogramas de la cámara se pierden o se desincronizan durante la grabación bimanual

Contención de ancho de banda USB con dos cámaras más dos brazos seriales USB en el mismo controlador de bus. La desviación de marca de tiempo de LeRobot entre los flujos de cámara y las lecturas del estado de las juntas excede los límites aceptables.

Solución:

# 1. Check which USB bus each device is on
lsusb -t

# 2. Spread devices across separate USB bus controllers
#    - Cameras: use a powered USB hub on one controller
#    - Arms: connect directly on a different controller

# 3. Reduce camera resolution if bandwidth is still tight
# In dk1_bimanual.yaml:
cameras:
  wrist_left:
    width: 480
    height: 320   # lower resolution reduces USB bandwidth

# 4. Verify timestamp skew is acceptable
python -m trlc_dk1.tools.check_sync \
  --config ~/.lerobot/robots/dk1_bimanual.yaml
# Target: < 5ms skew between all streams

¿Aún atascado? Pregunta en el Foro DK1 o revisa los existentes problemas de GitHub.

Anterior ← Guía de configuración

Siguiente Especificaciones →

¿Software funcionando? Comienza a recopilar datos bimanuales.

Una vez que ambos brazos estén en movimiento, el siguiente paso es la teleoperación y la grabación del conjunto de datos bimanuales.

Guía de recopilación de datos → Referencia completa de la API Obtén ayuda en el foro