你将搭建什么,以及需要准备什么
LeRobot 是 Hugging Face 的开源机器人库。用同一套命令就能驱动机器人、录制示范、训练策略并运行策略。SO-101 是它的旗舰机械臂:你用手移动主臂,从臂随之复制动作,录下的动作和摄像头图像会教神经网络自己重复完成任务。
整个过程分为七个阶段:备齐零件并安装软件,为每个电机设置 ID,组装两条机械臂,校准,带摄像头遥操作,录制数据集,最后训练并运行策略。最后一个搭建章节加入 LeKiwi 移动底盘,之后是一份故障排查清单。
左右滑动可查看完整图示。
你需要两条机械臂(零件见下一节)、每条机械臂各一块 USB 总线舵机控制板和一个电源、一台安装了 Python 3.12 或更高版本的电脑、两个 USB 摄像头(本指南中的命令用到两个)、一个用于存放数据集和检查点的免费 Hugging Face 账号,以及用于训练的 GPU。本文使用的 ACT 策略,笔记本级别的 GPU 就够用,租用 GPU 也可以。
本指南根据官方文档和社区搭建报告整理而成,我们没有在每一个硬件版本上对每一步都做过台架测试。调用 control_robot.py 的旧教程不适用于 0.7.0,该版本使用的是 lerobot-* 命令。
零件、打印与供电
SO-101 项目公布了物料清单和打印文件,Hugging Face 的 SO-101 页面链接了这两项内容。一套完整的主臂和从臂需要 12 个 Feetech STS3215 舵机、两块控制板、两个电源、两根 USB-C 线、桌面夹具。组装使用 M2×6 和 M3×6 螺丝;项目的物料清单没有列出它们,所以请查看舵机或套件随附了什么。也有已打印好的零件和完整套件出售。
从臂的六个舵机减速比均为 1/345。主臂使用三种不同的减速比,这样它既能撑住自身重量,又只需很小的力就能移动。
电源要与舵机匹配。7.4 V 的 STS3215 在 6 V 时堵转扭矩为 16.5 kg·cm(使用 5 V 电源时略小),通常使用 5 V 电源供电。从臂可以改用 12 V 舵机(30 kg·cm)获得更大动力,但这时需要额定 5 A 或以上的 12 V 电源;主臂始终使用 7.4 V 舵机。切勿把 12 V 电源接到装有 7.4 V 舵机的控制板上;请在每个电源上标明它的电压以及它所属的机械臂。
左右滑动可查看完整图示。
使用 PLA+ 打印,0.4 mm 喷嘴配 0.2 mm 层高(或 0.6 mm 喷嘴配 0.4 mm 层高),填充率 15%。每条机械臂的零件各自是一个文件,摆放方向已设计成只需少量支撑;不要在水平的螺丝孔里留支撑。先打印 Gauge Zero 和 Gauge Tight 这两个测试件,并拿舵机对照检查;如果 Gauge Zero 不能像项目视频中所示那样装配,请先调整打印机设置并重新打印,然后再打印机械臂。
备好 0 号和 1 号十字螺丝刀,测试前先把每个底座夹在桌面上。我们为这套搭建提供的零件链接在下方。
横向滚动以比较全部栏目。
| 关节 | 电机 ID | 主臂减速比 | 从臂减速比 |
|---|---|---|---|
| 肩部平转 | 1 | 1/191 | 1/345 |
| 肩部抬升 | 2 | 1/345 | 1/345 |
| 肘部弯曲 | 3 | 1/191 | 1/345 |
| 腕部弯曲 | 4 | 1/147 | 1/345 |
| 腕部滚转 | 5 | 1/147 | 1/345 |
| 夹爪 | 6 | 1/147 | 1/345 |
安装 LeRobot 和电机支持
LeRobot 0.7.0 需要 Python 3.12 或更高版本。用 conda(来自 miniforge)或 uv 创建独立环境,并在每个新终端中激活它。在大多数平台上,视频处理需要 ffmpeg(在 macOS Intel 和 32 位 ARM Linux 上,LeRobot 会改用 PyAV,可以跳过它);conda 版的 ffmpeg 适用于所有 PyTorch 版本。
conda create -y -n lerobot python=3.12
conda activate lerobot
conda install ffmpeg -c conda-forge从 PyPI 安装 LeRobot,并带上你需要的扩展。core_scripts 提供录制、回放和校准所用的内容,feetech 增加对 STS3215 舵机的支持,training 增加训练工具。
pip install 'lerobot[core_scripts,feetech]'
pip install 'lerobot[training]'平台说明:在 Apple silicon 上,PyTorch 需要 macOS 14 或更高版本,要使用 GPU(MPS)加速则需要 macOS 15 或更高版本。在 Linux 上使用 NVIDIA GPU 时,默认的 PyTorch 构建需要 580.65 或更高版本的驱动;驱动较旧时,请先安装与之匹配的 CUDA 版 PyTorch,并从 CPU 索引安装 torchcodec(见 Hugging Face 安装页面)。在 WSL 中还要安装 evdev(conda install evdev -c conda-forge;使用 uv 时先 sudo apt install libevdev-dev,再 uv pip install evdev)。使用 PyTorch 2.10 或更高版本时,可以用系统自带的 ffmpeg 代替 conda 版。
查找端口并设置电机 ID
新的 STS3215 舵机出厂时 ID 通常是 1,而且控制器和每个舵机必须使用同一波特率。LeRobot 会把这两项一次性写入每个舵机的内存,所以请在组装前完成,并且一次只连接一个舵机。从其他机器人上拆下来重复使用的舵机很可能同样需要这样做。
左右滑动可查看完整图示。
用 USB 把一块控制板连接到电脑并通电,然后运行端口查找工具。按提示只拔掉这块控制板的 USB 线并按 Enter 键;脚本会打印出端口,例如 Linux 上的 /dev/ttyACM0、macOS 上的 /dev/tty.usbmodem… 或 Windows 上的 COM3。把线插回去,再对第二块控制板重复此步骤。在 Linux 上,你可能需要对每个端口用 sudo chmod 666 授予访问权限(例如 /dev/ttyACM0 和 /dev/ttyACM1)。
lerobot-find-port先为从臂运行设置脚本,再为主臂运行,两者各用各自的端口。脚本每次只点名一个电机,所以运行之前请先读完下面的步骤。
lerobot-setup-motors \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0主臂使用遥操作器选项,而不是机器人选项。在每次提示时,请取零件一节表格中该关节所列减速比的那个电机(主臂上:肩部平转和肘部弯曲为 1/191,肩部抬升为 1/345,腕部弯曲、腕部滚转和夹爪为 1/147),并在脚本报告某个电机已设置好之后,立刻在该电机上标出它的 ID。
lerobot-setup-motors \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1- 脚本每次只点名一个电机,从夹爪(ID 6)开始,到肩部平转(ID 1)结束。只把该电机连接到控制板,它不能与任何其他电机串联。
- 按 Enter 键。脚本提示 ID 已设置后,从控制板上拔下该电机的线缆,连接它点名的下一个电机,然后再次按 Enter 键。
- 每次按 Enter 键之前,先检查电源线、USB 线和 3 针线缆。如果脚本报错,先检查这些线缆;使用 Waveshare 控制板时,两个跳线帽都必须放在通道 B(USB)上。
- 脚本结束后,按顺序把各电机串联起来,并把肩部平转电机(ID 1)连接到控制板。
左右滑动可查看完整图示。
一次设置一个舵机的 ID,再按顺序把舵机串联起来
组装主臂和从臂
两条机械臂共用大部分打印件,并按同样的顺序组装(腕部滚转的零件不同;从臂装有活动爪的位置,主臂装的是手柄和扳机):底座和肩部、上臂、前臂、腕部,然后是从臂的夹爪,或主臂的手柄和扳机。Hugging Face 在其 SO-101 页面上为每个关节发布了一段简短视频;请对照视频和这些说明操作。先清除打印件上的全部支撑材料,并在把每个舵机封入结构之前,先给它插好 3 针线缆。
- 关节 1,肩部平转:把两个舵盘装到电机上,上方的舵盘用一颗 M3×6 螺丝固定(下方的舵盘不需要螺丝)。用四颗 M2×6 螺丝把电机装进底座,套上第一个电机支架并用两颗 M2×6 固定,然后在上方用四颗 M3×6、下方再用四颗,装上肩部,最后加上肩部电机支架。
- 关节 2,肩部抬升:装好两个舵盘,上方的舵盘用一颗 M3×6 螺丝固定(下方的舵盘不需要螺丝),从上方滑入电机,用四颗 M2×6 固定,然后在两侧各用四颗 M3×6 装上上臂。
- 关节 3,肘部:装好两个舵盘,上方的舵盘用一颗 M3×6 螺丝固定(下方的舵盘不需要螺丝),用四颗 M2×6 装入电机 3,并在两侧各用四颗 M3×6 把前臂与它连接。
- 关节 4,腕部弯曲:装好两个舵盘,上方的舵盘用一颗 M3×6 螺丝固定(下方的舵盘不需要螺丝),套入电机支架 4,再滑入电机 4,并用四颗 M2×6 固定。
- 关节 5,腕部滚转:把电机 5 放入腕部支架,在前侧用两颗 M2×6 固定,装上一个舵盘并用一颗 M3×6 螺丝固定,然后按官方关节 5 视频所示,用 M3×6 螺丝把腕部固定到电机 4 上(文字指南写的是两侧各四颗)。
- 从臂夹爪:用四颗 M3×6 把夹爪装到腕部电机的舵盘上,在两侧各用两颗 M2×6 装入夹爪电机,装好两个舵盘,上方的舵盘用一颗 M3×6 螺丝固定(下方的舵盘不需要螺丝),再按官方夹爪视频所示,用 M3×6 螺丝固定爪子(文字指南写的是两侧各四颗)。
- 主臂手柄:用四颗 M3×6 把主臂支架装到腕部,用一颗 M2×6 把手柄固定到支架上,在两侧各用两颗 M2×6 装入电机 6(即扳机电机,官方指南称之为夹爪电机),并装一个舵盘,用一颗 M3×6 螺丝固定,然后用四颗 M3×6 装上扳机。
- 通电之前,用手慢慢让每个关节走完整个活动范围,切勿强行越过限位;关节应转动顺畅,没有刮擦。在把每个电机封入结构之前,先标出它的 ID,并把两个底座夹在桌面上。
校准两条机械臂
校准会记录每个关节的活动范围,使主臂和从臂在同一个物理姿态下报告相同的数值。它还能让在一台机器人上训练出的策略运行在另一台上。每条机械臂校准一次;硬件有改动,或 LeRobot 提示缺少校准时,要再校准一次。重新校准之前录制的数据和训练出的策略,用的是旧的校准。
先校准从臂。脚本会要求你把每个关节移到其活动范围的中间位置并按 Enter 键,然后让每个关节走完全部活动范围,等每个关节都走完之后再按一次 Enter 键。给每条机械臂设置一个唯一的 id;这个名字用来标记它的校准文件。本指南中的命令以 /dev/ttyACM0 作为从臂的端口、/dev/ttyACM1 作为主臂的端口,仅作示例:请换成你自己找到的端口,并且不要把两条机械臂弄反。
左右滑动可查看完整图示。
lerobot-calibrate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm然后用同样的动作校准主臂。
lerobot-calibrate \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm之后的每条命令都要使用同一个 id;LeRobot 靠它找到默认存放在 ~/.cache/huggingface/lerobot/calibration 下的校准文件。请备份该文件,并且不要把它放在临时文件夹里:一位社区搭建者在一次断电重启中丢失了校准文件,重新校准时没有让每个关节都处于活动范围的中间位置,结果有些关节的归零偏移是错的。
用主臂遥操作从臂
遥操作把两条机械臂连接起来:从臂复制主臂的动作。如果缺少校准,命令会先启动校准流程。从缓慢、幅度小的动作开始,远离从臂的关节,并让电源保持在伸手可及的位置。
lerobot-teleoperate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm接着添加摄像头。用摄像头查找工具列出摄像头,它会打印每个摄像头的标识符,并把每个摄像头的一帧测试画面保存到 outputs/captured_images;打开这些画面,看哪个索引对应哪个摄像头。重启或重新插拔摄像头后,索引可能改变。
lerobot-find-cameras opencv带着摄像头再次遥操作,并在 Rerun 中实时查看画面。你在这里为摄像头起的名字(例如 top 和 wrist)之后会成为数据集的键,所以从现在起请使用相同的名称和设置。
lerobot-teleoperate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm \
--display_data=true摆放摄像头,让策略学得会
策略只能看到摄像头图像和关节位置,所以摄像头的设置比高分辨率更重要。对大多数任务来说,640×480、30 fps 就足够,而且录制和训练都更快。
左右滑动可查看完整图示。
- 用漫射光均匀照亮场景。避免阳光直射、强反光和移动的阴影:录制和运行时光照不一致,可能导致策略失败。
- 牢固固定摄像头,在录制和运行之间不要移动它们。一位社区搭建者的第一个策略只会往桌面上啄,原因有好几个,其中之一是摄像头在录制和测试之间发生了轻微位移。
- 给任务取景:物体、夹爪和目标至少应在一个摄像头的画面中可见。一个好的检验办法是:只看摄像头图像,你自己能否完成这项任务。同一位社区搭建者示范时只看摄像头画面;如果你想这样试,请让电源保持在伸手可及的位置。
- 同一位搭建者把侧面摄像头(抓取时对夹爪尖端的视野不佳)换成了装在正面摄像头旁边的俯视摄像头,遮挡因此减少;腕部摄像头在那篇帖子里只是作为下一步出现。如果你全天录制,请在网络摄像头自带的设置里固定曝光和白平衡;LeRobot 的 RealSense 摄像头配置也接受
exposure、gain和white_balance。 - 在 Ubuntu 上使用两个相同的网络摄像头时,USB 地址可能互换,录制可能因摄像头错误而中断。同一位搭建者用 udev 规则解决了这个问题,规则按物理 USB 口来识别每个摄像头,所以请让每个摄像头始终插在同一个接口上;否则每次重启后都要重新运行摄像头查找工具。
录制数据集
数据集使用 LeRobotDataset 格式,并上传到 Hugging Face Hub。创建一个免费账号,在 Hugging Face 设置里生成具有写入权限的令牌,然后登录,并把你的用户名存入一个变量。请先把 HUGGINGFACE_TOKEN 设为你的令牌,或者单独运行 hf auth login,并在提示时粘贴令牌。
hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
echo $HF_USER先录制五个回合来测试环境。使用与遥操作时相同的机器人 id、端口和摄像头设置,并用简单的话描述任务。
lerobot-record \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_arm \
--display_data=true \
--dataset.repo_id=${HF_USER}/record-test \
--dataset.num_episodes=5 \
--dataset.single_task="Grab the black cube" \
--dataset.streaming_encoding=trueLeRobot 会把日期和时间追加到数据集名称后面,所以 ${HF_USER}/record-test 会保存为 ${HF_USER}/record-test_YYYYMMDD_HHMMSS。后续命令中请使用这个完整名称;可以用 ls ~/.cache/huggingface/lerobot/${HF_USER} 查到它,也可以加上 --dataset.no_stamp=true 保留你传入的名称。数据集存放在 ~/.cache/huggingface/lerobot,录制结束时推送到 Hub。从个人账号推送的数据集可能是公开的,所以请在 Hub 上检查它的可见性,如需私有就加上 --dataset.private=true;加上 --dataset.push_to_hub=False 可只保存在本地。要接着做一次中断的录制,请用同样的命令重新运行,并带上 --resume=true、带时间戳的完整 --dataset.repo_id、设为数据集本地文件夹的 --dataset.root,以及 --dataset.num_episodes;后者要设为额外还要录的回合数,而不是总数。
回合时长和复位时长默认都是 60 秒(--dataset.episode_time_s 和 --dataset.reset_time_s),默认回合数是 50。录制过程中由键盘控制流程,见下表。
第一个有用的数据集,请选一个简单的任务,例如从几个不同位置拾取物体并放入收纳盒。至少录制 50 个回合,每个位置约 10 个,保持摄像头和你的抓取方式一致,再慢慢增加变化。失败的回合要重新录制。固定位置的 50 个回合只是一个起点;预期策略主要在你录制过的位置附近有效。LeRobot 会在每个保留下来的回合之后打印一行采集频率,并在录制结束时打印汇总。如果频率远低于 30 Hz 的目标,数据集仍然声称是 30 Hz,所以动作看起来会比实际更快。请找出拖慢循环的原因(在文档的示例中是读取摄像头),并重新录制受影响的回合,而不要直接拿它们去训练。
训练之前先检查数据。在 Hugging Face 上的 LeRobot 数据集可视化工具中打开数据集,并在机器人上回放一个回合,测试动作能否重复。回放会在没有你操作的情况下移动机械臂,所以请清空工作区,让机械臂从接近该回合第一个姿态的位置开始,并让电源保持在伸手可及的位置。
lerobot-replay \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
--dataset.episode=0横向滚动以比较全部栏目。
| 按键 | 操作 |
|---|---|
| 右方向键或 n | 提前结束当前回合或复位阶段,并继续下一步 |
| 左方向键或 r | 丢弃当前回合并重新录制 |
| Esc 或 q | 停止本次录制:正在进行的回合会被保存,然后编码视频并上传数据集(若要丢弃该回合,请先按左方向键或 r) |
训练 ACT 策略
ACT(Action Chunking Transformer)是 LeRobot 教程中使用的策略:它会适应数据集中保存的电机和摄像头配置。硬件指南给出的轻量策略(ACT、VQ-BeT、TD-MPC)在批大小为 8 时约需 2 到 6 GB 的 GPU 显存,仅作参考。可以在 NVIDIA GPU(cuda)上训练;在 Apple silicon 上,把命令改为 --policy.device=mps,这需要 macOS 15 或更高版本(在 macOS 14 上,LeRobot 会回退到 CPU,不适合用于训练)。
用完整的数据集名称开始训练。
lerobot-train \
--dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
--policy.type=act \
--output_dir=outputs/train/act_so101_test \
--job_name=act_so101_test \
--policy.device=cuda \
--trackio.enable=true \
--policy.repo_id=${HF_USER}/my_policy \
--steps=20000不加 --steps 时,训练会跑 100,000 步,对小数据集来说通常过多:模仿学习一般在对数据过 5 到 10 遍之内就能收敛。一个包含 50 个回合、每个回合 30 秒、30 fps 的数据集约有 45,000 帧,在批大小为 8 时每遍约 5,600 步,所以 5 到 10 遍大约是 28,000 到 56,000 步。上面的命令使用 --steps=20000,约三遍半,作为一次简短的初跑;如果策略训练不足就调高它,如果把它调得低很多,还要把 --policy.scheduler_decay_steps 设为接近 --steps 的值。硬件指南估计,在 RTX 3090 或 4090 上以批大小 8 训练 ACT 五遍大约需要 30 到 60 分钟,在 L4 或 A10G 上需要 1 到 2 小时,在 M1、M2 或 M3 Max 上以批大小 4 训练则需要 6 到 14 小时;它称这些数字仅供参考,实际运行可能相差约 50%。
没有合适的 GPU 时,可以用 ACT 笔记本在 Google Colab 中训练,也可以先运行 hf auth login,再在同一条命令上加一个 Hugging Face Jobs 规格,例如 --job.target=a10g-small。由于该命令启用了 Trackio,作业还需要 --trackio.space_id=<user>/<space>(加上 --trackio.private=true 可让该 Space 保持私有),或者去掉 --trackio.enable=true。Jobs 按秒计费,除非设置 --job.timeout,否则上限为 48 小时;它会替你把仅存于本地的数据集上传到私有仓库,并在结束时推送训练好的模型;hf jobs hardware 会列出可用规格。
检查点写入 outputs/train/act_so101_test/checkpoints。可以从最后一个检查点恢复被中断的训练。由于训练命令设置了 --policy.repo_id=${HF_USER}/my_policy,训练好的模型会在结束时推送到该仓库(--policy.push_to_hub=false 可关闭此行为,--policy.private=true 可让它私有);如果要自己上传检查点,请使用同样的仓库名,这样 --policy.path=${HF_USER}/my_policy 才能找到它。
lerobot-train \
--config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
--resume=true
hf upload ${HF_USER}/my_policy \
outputs/train/act_so101_test/checkpoints/last/pretrained_modelLeRobot 的训练脚本不会评估真实机器人上的策略,所以请留出一些回合不参与训练,包括你没有录制过的起始位置,并用它们测试策略。一位社区搭建者用 50 个回合训练(五个起始位置区域,每个区域 10 个),在这些区域的新回合上成功率为 60%,而在训练时留出的一个区域的回合上只有 10%。把数据增加到每个区域 25 个回合后,同一位搭建者的结果分别达到 90% 和 75%。这些都是小样本,用搭建者自己的脚本打分。
在从臂上运行策略
用 lerobot-rollout 部署训练好的策略。使用与录制时相同的机器人 id、摄像头名称、摄像头设置和任务文本;如果此后重启或重新插拔过设备,请重新运行端口查找工具。--duration 的单位是秒;不加它,策略会一直运行到你停止为止。
lerobot-rollout \
--strategy.type=base \
--policy.path=${HF_USER}/my_policy \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_arm \
--robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
--task="Grab the black cube" \
--duration=60运行模式(strategy)决定运行期间会发生什么,见下表。会录制数据集的模式,其仓库名在你的用户名之后必须以 rollout_ 开头,例如 --dataset.repo_id=${HF_USER}/rollout_so101_test;系统会给它加上时间戳。sentry 等录制模式使用 --dataset.single_task 而不是 --task;各模式的参数请见 LeRobot 文档。
在 LeRobot v0.5.x 及更早版本中没有 lerobot-rollout;请按 v0.5.1 文档所述使用 lerobot-record。本指南中的训练参数针对当前版本。
第一次运行请使用较短的时长(例如 15 秒),保持工作区畅通,并想好怎样让机械臂停下来;断电会让电机失去力矩,所以没有靠在什么东西上的机械臂可能会掉下来。如果机械臂啄向桌面或伸得过远,先检查设置,不要急着怪模型:校准 id 相同、摄像头位置相同且名称和分辨率相同、光照相同,物体处于数据集覆盖到的位置。
横向滚动以比较全部栏目。
| 运行模式 | 作用 |
|---|---|
| base | 自主运行,不录制,用于快速测试 |
| sentry | 持续录制并自动上传 |
| highlight | 保留一个环形缓冲区,按键时将其保存下来 |
| dagger | 人在回路中的数据采集 |
| episodic | 逐回合录制,回合之间有复位阶段 |
用 LeKiwi 扩展你的搭建
LeKiwi 是一个三轮移动底盘,载着一条 SO-101 从臂。由 Raspberry Pi(或另一台 5 V 电脑,USB 接口要够接摄像头和电机控制板,LeKiwi 页面写的是两个或更多)运行机器人,你在笔记本上用一条主臂和键盘来驾驶它。有线版本的所有程序都在笔记本上运行,可以跳过 Pi 的步骤。零件清单、打印文件和底盘组装说明来自 Hugging Face LeKiwi 页面所链接的 LeKiwi 项目。
左右滑动可查看完整图示。
用键盘驾驶底盘需要全局按键后端,所以它可以在 X11、Windows 桌面,或已给终端授予“输入监控”权限的 macOS 上工作,但不能在 Wayland 或无图形界面的机器上工作。
- 按上面各节搭建两条 SO-101 机械臂:一条装在底盘上,另一条作为主臂。然后组装底盘。
- 安装 Raspberry Pi OS,启用 SSH,并确认可以用
ssh <user>@<pi-ip>登录。按安装一节在 Pi 和笔记本上都安装 LeRobot,然后加上 LeKiwi 扩展,它会带来舵机驱动和 ZeroMQ。安装 LeKiwi 扩展 pip install 'lerobot[lekiwi]' - 用一条命令设置所有电机。它会给机械臂电机分配 ID 6 到 1,给车轮分配 9、8 和 7;车轮 ID 必须与 LeKiwi 文档中所示的安装位置一致。LeKiwi 只使用一块控制板。
设置 LeKiwi 电机 ID lerobot-setup-motors \ --robot.type=lekiwi \ --robot.port=/dev/ttyACM0 - 在 Pi 上校准从臂,在笔记本上校准主臂。LeKiwi 页面给主臂用的是
--teleop.type=so100_leader;请查看examples/lekiwi/teleoperate.py创建的是哪个主臂类,并用同样的类型和--teleop.id来校准。车轮电机不需要校准。校准 LeKiwi 机械臂 lerobot-calibrate \ --robot.type=lekiwi \ --robot.id=my_awesome_kiwi - 在 Pi 上激活 LeRobot 环境并启动主机。除非调高
--host.connection_time_s(例如调到 600),否则它会在 30 秒后停止;录制等较长的会话需要调高。在 Pi 上启动 LeKiwi 主机 python -m lerobot.robots.lekiwi.lekiwi_host \ --robot.id=my_awesome_kiwi \ --host.connection_time_s=600 - 在笔记本上编辑 LeRobot 源码仓库中的
examples/lekiwi/teleoperate.py:把remote_ip设为 Pi 的地址,把主臂的port和 id 设为你自己的值,然后运行它。在record.py中还要设置HF_REPO_ID和TASK_DESCRIPTION;在replay.py中要设置remote_ip、port、数据集 id 和回合索引。要运行训练好的策略,LeKiwi 页面使用examples/lekiwi/evaluate.py(设置remote_ip、port和模型);上一节的lerobot-rollout命令是为独立的 SO-101 编写的。速度有三档,用 R 和 F 切换:快速 0.3 m/s 和 90°/s,中速 0.2 m/s 和 60°/s,慢速 0.1 m/s 和 30°/s。
横向滚动以比较全部栏目。
| 按键 | 操作 |
|---|---|
| W | 向前移动 |
| A | 向左移动 |
| S | 向后移动 |
| D | 向右移动 |
| Z | 向左转 |
| X | 向右转 |
| R | 提高速度 |
| F | 降低速度 |
故障排查清单
许多问题出在电源、线缆、端口,或录制与运行之间改变了的设置。修改任何代码之前,先对照下表逐项排查。
关于 LeRobot 本身的问题,Hugging Face 文档链接了它的 Discord 社区。关于我们商店出售的零件,请使用 WhatsApp 按钮或支持表单。
横向滚动以比较全部栏目。
| 现象 | 检查什么 |
|---|---|
| 找不到串口,或访问被拒绝 | 在控制板已通电、USB 线已插好的情况下重新运行端口查找工具。在 Linux 上,对该端口使用 sudo chmod 666 授予访问权限。重启或重新插拔后端口可能会变,请重新运行端口查找工具。 |
| ID 脚本找不到电机 | 检查电源、USB 线和 3 针线缆。只能连接正在设置的那个电机。使用 Waveshare 控制板时,两个跳线帽都必须在通道 B(USB)上。 |
| 重复使用的舵机找不到或没有响应 | 它们的 ID 和波特率很可能与新机器人不匹配,SO-101 指南中也有这样的提示。重新运行电机设置,一次只设置一个舵机。 |
| 校准失败,或校准后机械臂动作不对 | 重新校准:先让每个关节处于活动范围的中间位置并按 Enter 键,再让每个关节走完全部活动范围。一位没有让每个关节居中的社区搭建者,最终得到了错误的归零偏移。之后请使用相同的机器人 id。 |
| 摄像头断开或索引改变 | 每次重启或重新插拔后重新运行摄像头查找工具。两个相同的网络摄像头在 Linux 上可能互换 USB 地址;一位社区搭建者用基于物理 USB 口的 udev 规则解决了这个问题。 |
| 录制按键没有反应 | 从交互式终端启动命令,并保持该终端处于焦点;字母键 n、r 和 q 与方向键和 Esc 键同样有效。只有像 LeKiwi 那样用键盘驾驶机器人,才需要 X11、Windows 桌面或 macOS 权限。 |
| 训练找不到数据集 | 使用完整的数据集名称,包括日期和时间后缀。 |
| 采集频率远低于 30 Hz | 阅读录制时打印的采集频率行。如果读取摄像头占了大头,就降低分辨率或减少摄像头数量,然后重新录制:策略期望运行时的摄像头配置与录制时相同,而远低于 30 Hz 录制的回合,会被当作 30 Hz 存储。 |
| 策略啄向桌面或伸得过远 | 把校准 id、摄像头位置、名称和光照与录制时对比,并确认物体起始位置在数据集有示例的地方。 |
| LeKiwi 连接不上,或主机在 30 秒后停止 | 用 hostname -I 查出 Pi 的地址,在笔记本上 ping 它,并测试 ssh <user>@<pi-ip>;如有需要,在 sudo raspi-config 中启用 SSH。除非设置 --host.connection_time_s,否则主机会在 30 秒后停止。 |