TRLC-DK1

软件设置

插件安装、主从臂配置、ROS2双手控制、乐机器人DK1集成、Python API和故障排除。 从全新的 Ubuntu 安装到移动的双手系统。

跳转到一个部分：

› SDK安装 › 领导者/跟随者配置 › ROS2 双手设置 › 乐机器人DK1配置 › Python API > 模拟 › 故障排除
第 1 步 — SDK 安装

SDK安装

DK1 SDK 作为 LeRobot 插件通过 trlc-dk1 存储库。 它注册了四种设备类型： dk1_leader, dk1_follower, bi_dk1_leader， 和 bi_dk1_follower.

首先安装乐扫机器人

pip install lerobot

克隆并安装 DK1 插件

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

验证安装

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)
"

你应该看到 dk1_leader, dk1_follower, bi_dk1_leader, bi_dk1_follower 打印。 如果没有，请确保插件正确安装 uv pip show trlc-dk1.

从特定提交安装（为了重现性）

cd trlc-dk1
git checkout v0.3.0
uv pip install -e .
📄 SDK 快速入门（维基） 📄 完整 API 参考 (wiki)
第 2 步 — 领导者/跟随者配置

引导臂/从动臂配置

DK1 的双手系统依靠端口分配来区分引导臂 (Dynamixel XL330) 和从动臂 (DM4340 + DM4310)。 不正确的端口分配是最常见的设置错误。

检测USB串口

运行 LeRobot 端口检测实用程序，一次连接一只手臂：

# 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

创建双手机器人配置

为双手配对创建 YAML 配置文件。 乐机器人使用它来将命令发送到正确的手臂：

# ~/.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

验证配置

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

它连接到双臂而不移动它们。 检查连接错误。 如果任一臂无法连接，请重新运行端口检测或交换端口分配。

端口持久化： USB 串行端口可以在重新启动之间更改。 使用udev规则通过USB序列号将端口绑定到特定的arm。 请参阅 设置指南 用于 udev 规则模板。

第 3 步 — ROS2 双手设置

ROS2 双手控制

ROS2 Humble 为 DK1 提供了更高级别的控制层，并提供完整的 MoveIt2 双手规划支持。 对于仅限 LeRobot 的数据收集工作流程来说，这是可选的。

安装 ROS2 Humble 和双手包

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

克隆并构建 DK1 ROS2 包

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

以双手模式启动

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

使用假硬件进行测试（无需手臂）

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

发送双手轨迹

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}}]}'
步骤 4 — 乐机器人 DK1 配置

乐机器人DK1配置

带有 DK1 插件的乐机器人可以原生处理双手遥控录音。 这 bi_dk1_follower 同时从双臂和所有摄像机进行设备类型记录。

校准双臂

# 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

启动双手遥控操作

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

记录双手数据集

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

推送至 HuggingFace Hub

huggingface-cli login
python -m lerobot.scripts.push_dataset_to_hub \
  --repo_id=your-username/dk1-bimanual-pick-place-v1
第 5 步——Python API

用于双手控制的 Python API

DK1 Python API 提供通过串行方式对双臂的直接访问。 基本控制和数据记录不需要 ROS2。

连接双臂

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()

读取双臂的关节状态

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()

手动运行领导者-跟随者循环

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()
📄 SDK 快速入门 📄 完整 API 参考
可选 — 模拟

模拟支持

DK1 通过反映真实硬件运动学的校准模型支持 MuJoCo 双手模拟。 在部署到硬件之前在模拟中训练策略。

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

训练针对 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

模拟与真实的对齐： DK1 MuJoCo 模型使用 TRLC-DK1-Follower_v0.3.0 STEP 文件几何结构和测量的 DM4340/DM4310 电机扭矩曲线。 在 sim 中训练的策略可传输到真实硬件，只需对结构化拾取和放置任务进行最少的调整。

故障排除

双手特定的三大问题

错误1 分配到同一端口的武器——追随者镜像领导者，但严重滞后

两条手臂连接到同一个 /dev/ttyACM* 端口或交换端口分配。 引导臂（Dynamixel XL330）和从动臂（DM系列）使用不同的协议； 错误的分配会导致立即控制失败。

使固定：

# 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
错误2 远程操作期间从动臂振荡或超调

从动臂的 PD 增益对于当前有效负载或臂配置来说太高。 当手臂装载有末端执行器或完全伸展操作时，这种情况尤其常见。

使固定：

# 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
错误3 双手录制期间相机帧丢失或不同步

同一总线控制器上的两个摄像头和两个 USB 串行臂存在 USB 带宽争用。 LeRobot 相机流和联合状态读数之间的时间戳偏差超出了可接受的限制。

使固定：

# 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

还卡住了吗？ 询问 DK1论坛 或检查现有的 GitHub 问题.

以前的 ← 设置指南
下一个 规格 →

软件工作正常吗？ 开始收集双手数据。

一旦双臂开始移动，下一步就是远程操作和双手数据集记录。

数据收集指南 → 完整 API 参考 在论坛上获取帮助