SO-101
课程总览/第 06 章 · 主从遥操
EN
第 06 章遥操作与视觉约 25 分钟

主从遥操

配套页面:控制台的「主从遥操」页签

8 个小节 3 张图 12 段代码 遥操作标定安全层
主从遥操的数据通路

先说结论: 主从遥操默认不受关节限位、速度/加速度上限、桌面高度和底座禁区的影响;急停、过温、心跳/控制环故障和跟随误差仍然生效(见 §5)。

推荐绝对映射: 启动前先用「主从对照」把两臂差收到 5° 以内(见 §4)。

1. 原理:每个控制周期都在跑的一条链#

主从遥操就是一个人用手摆主臂,从臂照着做。听起来简单,实现上是一条固定频率的链:

text
每 1/30 秒(30 Hz):
  ① 读主臂的六个角度         backend.read_leader()
  ② 加一个偏置                target = leader + offset
  ③ 过安全层                  急停、过温、跟随误差(限位/禁区默认不参与,见 §5)
  ④ 写给从臂                  backend.write_follower()

关键点:主臂是从臂的"目标源",不是"另一台要控制的机器"。从臂的运动指令完全来自主臂读数,没有任何规划和插值——所以主臂动多快,从臂就跟多快(在安全层允许的范围内)。

代码在 starm/teleop.py 的 TeleopSession._target(),每个周期调一次:

python
reading = self.arm.backend.read_leader()
return {
    name: self.leader[name] + self.offset.get(name, 0.0)
    for name in JOINT_NAMES
}

2. 主臂为什么要卸力#

主臂如果上了力,你推它就是在跟电机较劲——根本推不动。

所以 SDK 连接时对主臂做了两件事:

  • connect(calibrate=False):只打开总线,不写目标
  • disable_torque():关掉保持力矩,让它变成一台"手轮"

从臂相反,必须是上力状态(torque_on 为真),否则遥操启动会直接报 holding torque is off。

页面上不需要你手动处理这两件事——连上就配置好了。

3. 标定:两只臂都要标#

为什么两只臂都要标#

遥操是"读主臂 → 写从臂",两边都得把计数翻译成角度:

标定对象 不标会怎样
从臂 连接时直接报 the follower arm is not calibrated
主臂 连接时直接报 the leader arm is not calibrated

两份标定文件各自独立,标了一个不代表另一个能用:

text
~/.cache/huggingface/lerobot/calibration/
    robots/so_follower/so101_follower.json      ← 从臂
    teleoperators/so_leader/so101_leader.json   ← 主臂

这个目录和 lerobot / LeLab / Studio 共用,标一次到处都能用。

舵机只报"计数",不报角度#

STS3215 的分辨率是 4096 计数/圈,约 0.088°/计数。它只知道自己转到了哪个计数,不知道对应多少度——这个映射必须靠标定建立。标定给每个关节定三个数:

量 含义
homing_offset 中点偏移:把你确认的那个中位姿态记成 2047(半圈)
range_min / range_max 行程两端:保存时以中位为中心对称裁剪后的值

标定流程:中位 → 全行程 → 保存#

整个过程是你用手搬、程序只读:程序不发任何运动指令,只在你转动时持续读位置。页面上是五个动作:

text
① 开始标定        → 卸力、打开总线,手臂可以自由推动
② 摆中位          → 大臂近似水平、小臂水平前伸、手腕居中、夹爪半开
③ 确认中位        → 把这个姿态写进编码器半圈;**从这一刻才开始记最小/最大**
④ 扫全行程        → 逐个关节缓慢转到两端,表格里的「最小/最大」实时跟着走
⑤ 保存标定        → 校验行程 → 以中位为中心对称裁剪 → 写舵机寄存器 + 标定文件

六个关节都要扫,每个关节两个方向都转到机械端点:

关节 怎么转
shoulder_pan 绕底座左右各转到头
shoulder_lift 大臂上下抬到两头
elbow_flex 小臂前后摆到两头
wrist_flex 手腕上下摆到两头
wrist_roll 整圈转一下(范围固定 0–4095,没有机械端点)
gripper 张开到最大,再闭合到底
标定卡片

卡片上半部分是标定哪个(主臂 / 从臂)+ 串口 + 六个按钮;中间是"已保存 + 文件路径";下半部分那张表是每个关节的当前 / 最小 / 最大 / 行程 / 单边五列。

六个按钮分别什么时候点:

按钮 什么时候点
开始标定 第一步。会先卸力——扶住机械臂,它会因重力下落
确认中位并开始记录 摆好中位之后点。点了才开始累计行程
保存标定 六个关节都转到两端之后
取消 中途放弃,会关总线、不留文件
从文件恢复 舵机被改过、文件还在时用(见下一节)
演示动作 不碰机械臂,只看一遍每个关节该怎么转

规则:什么算"标好了"#

保存时会做校验,不通过就直接拒绝,会话保持,转完再点一次即可:

规则 数值 不符合时
每个关节行程 ≥ 100 计数(≈8.8°) 报"行程不足"
中位是否落在行程内 必须在内 报"中位不在行程内"
单边剩余 太短则拒绝 表格里红 <100 → 会被拒绝、黄 <400 → 基本没扫够

「单边」= 以中位(2047)为中心、左右取较窄一侧后每侧剩的行程。因为保存时对称裁剪,最终 range_min + range_max = 2 × 2047——这样 0° 就永远是中位那个姿态。

两个例外:

  • wrist_roll 没有机械端点,真机保存时按整圈 0–4095 处理,仍以中位为 0°
  • 夹爪 不做对称裁剪——lerobot 用 0–100 线性映射它的行程,范围按实际扫出的值存

标定前必须断开机身连接#

标定要独占串口。开始标定前要先「断开」机械臂连接,否则会报"标定要用串口,请先断开当前的机械臂连接"。

标定全程不发任何运动指令,只读 Present_Position、只写标定寄存器,所以不存在绕过安全层的运动路径。但也正因为如此,卸力后手臂会掉下来——点「开始标定」之前先扶住。

保存后要重新连接#

保存只写了舵机和文件,已经在跑的会话不会自动生效。卡片上会提示:

已保存 /home/.../so101_leader.json (这只臂仍是卸力状态;重新「连接」后力矩恢复、新标定生效)

"已标定"是怎么判定的#

不是看文件在不在,而是拿文件里的值和舵机里存的值逐项比对:

python
same_ranges  = range_min / range_max 全部相等
same_offsets = homing_offset 全部相等
is_calibrated = same_ranges and same_offsets

所以会出现"我明明标过,它却说没标定"——多半是舵机被重新写过、文件没更新。

两种修复手段#

情况 用什么 代价
舵机被改过,文件还好 从文件恢复(把文件值原样写回舵机) 2 秒
没有文件,或文件也坏了 重新标定(中位 → 扫行程 → 保存) 2–3 分钟

如果现有标定文件存在,点「开始标定」会先把它备份成 *.json.bak;第一次标定还没有文件,所以不会产生备份。

4. 映射方式:推荐绝对,回退相对#

两种模式的公式完全一样:

text
target = leader + offset

区别只在 offset 怎么取:

相对(回退) 绝对(推荐)
offset 启动时抓一次:从臂 − 主臂 恒为 0
从臂 = 主臂 + 起始差 主臂
启动要求 两臂姿势可以完全不同 两臂必须已对齐(差 ≤5°)
适合 两臂标定零点差很大、只想快速跟上 推荐:要求从臂严格复刻主臂;采集/复现/训练希望关节角与示教一致

推荐用绝对映射。 绝对模式下 从臂 = 主臂,主臂和从臂的关节角一一对应,适合教学、采集和复现;它不会像相对映射那样把启动时的两臂偏置一直保留下去。代价是启动前必须先把两臂对齐(差 ≤5°)。如果两臂标定零点差很大、怎么都收不进 5°,再回退相对映射。

同一张卡片,切换下拉就换一种映射;页面的默认选项已经选「绝对(推荐)」。选「绝对」后会多出 「两臂差 / 对齐到主臂」一行;想先跑起来也可以切回「相对」。

为什么绝对模式要求先对齐#

绝对模式下 offset=0,从臂的第一条指令就是主臂的角度。如果两臂差 20°,从臂会在一个周期内跳 20°——机械上是一次猛烈的冲击。

所以这事必须有个门槛。这个页面的门槛是 5°:SDK 的默认值是 2°,页面显式放宽了——两臂是各自标定的,零点差几度很常见,2° 常常怎么扳都收不进去;而 5° 仍然只是一次小姿态修正。超过门槛就拒绝执行:

text
SafetyError: leader and follower differ by 20.6° (tolerance 5.0°);
align them first or use relative=True

对齐怎么做#

页面上选「绝对」后会出现一行:

两臂差 20.6°(>5°,绝对映射会被拒) [对齐到主臂]

点「对齐到主臂」,从臂自动走到主臂当前姿态(走安全层、按速度滑块的速度)。到位后差值变绿(≤5°),绝对模式就能启动了。

推荐流程:先用「主从对照」对齐,再开始绝对遥操#

选「绝对」后,页面会出现「两臂差 / 对齐到主臂」一行;同时下面的「主从对照」表不用开始遥操就会刷新。表里四列是:

列 含义
关节 六个关节 + 夹爪
主臂 主臂当前角度
从臂 从臂当前角度
差值 (°) 从臂 − 主臂;开始遥操后这一列变成「跟随误差」
用主从对照表把两臂对齐,再开始绝对映射

按这个顺序做:

① 映射方式选「绝对(推荐)」。 两臂差 >5° 时开始按钮会置灰,先别点「开始遥操」。

② 先看「两臂差」。 它是六个关节里最大的绝对差值;超过 5° 就继续对齐。

③ 从差值最大的关节开始,两种做法任选:

  • 让从臂过来:点「对齐到主臂」。从臂会按速度滑块走过去;等它停下,页面会显示残余差。对齐本身是普通运动,会过限位和桌面/底座禁区;如果从臂够不到,页面会告诉你主臂还要扳多少。
  • 让主臂过去:主臂是卸力的,用手把主臂的对应关节扳向从臂的角度。差值为正(从臂 > 主臂)就把主臂往正方向扳,差值为负就往负方向扳。比如图中 wrist_flex 差 −12.4°,主臂 −89.7°、从臂 −102.1°,把主臂往负方向扳约 12.4° 就对齐了。

④ 六个关节都看一遍,夹爪也要对;通常把最大的两三个关节收进来,总差就会落到 5° 以内。

⑤ 差值全部 ≤5° 后,「两臂差」变绿、开始按钮可用,再点「开始遥操」。绝对模式下表头会从 「差值」变成「跟随误差」,正常应接近 0。

不要用「开始遥操」去硬试两臂差 20° 的状态:绝对映射会在启动时直接拒绝,避免从臂在一个周期内跳 20°。如果怎么都收不进 5°,多半是两次标定的零点不一致,回 §3 重标,或改用相对映射。

对不齐的时候:两臂的行程本来就不一样#

主臂和从臂是各自标定的:零位(homing_offset)和行程(range_min / range_max)都不一样。所以主臂能到的角度,从臂不一定能到。现场踩过的一个例子:

text
主臂 shoulder_lift = -102.6°   从臂限位 = [-100.0°, 100.0°]
主臂 elbow_flex    =   96.5°   从臂限位 = [-100.0°, 90.0°]
主臂 wrist_roll    =  162.0°   从臂限位 = [-160.0°, 160.0°]

旧实现把这些角度原样下发给从臂,安全层在发指令之前就把整条目标拒掉:

text
SafetyError: shoulder_lift target -102.55 is outside soft limits [-100.0, 100.0]

从臂一动不动,操作者只看到一句英文报错,不知道该怪谁。

现在「对齐到主臂」分三步:

  1. 夹紧:逐关节把主臂目标夹进从臂当前可达的区间,得到「最接近的可达姿态」;
  2. 预检:先用 SafetyLayer.workspace_check() 看这个姿态会不会把末端带到桌面以下、或钻进底座禁区——会的话直接拒绝,并说出具体的 z 和半径;
  3. 残差:被夹掉多少、主臂要往哪个方向扳多少,逐关节报回来:

从臂已走到可达边界,还差 6.5°:请把主臂扳回来 —— elbow_flex 6.5°(主臂 96.5° → 从臂边界 90.0°)

从臂先走到最靠近的位置,剩下的交给手:主臂是无扭矩的,扳回来几度就行。差值降到 5° 以内, 「两臂差」变绿,绝对模式就能启动。

对齐是后台运动:从臂还在走的时候页面会显示「从臂正在移动…」,这时点「开始遥操」 会把这次对齐打断,所以等它停下再开始。

还是收不进 5°?那是标定零点不一致#

两臂读到的「度」是 (原始计数 − 标定区间中点) × 360/4095,中点取的是标定时扫出来的行程中点,不是机械上精确的同一个姿态。两次标定的「中位」摆得不一样,零点就差几度:物理上明明对齐了,页面还显示 elbow_flex +6.0°,怎么扳都收不进去。

判断方法:把两臂摆成同一个姿势(比如都回到中位),逐关节看差值。如果某个关节始终差一个固定的量,那就是零点差,不是你的手不准。

处理:

  • 重新标定两臂,两次都用同一个物理姿态摆中位(页面标定第 1 步的那句「大臂近似水平、小臂水平前伸、各关节都在行程中间」就是给这个用的);
  • 或者干脆用相对映射——它只传位移,零点差多少都不影响。
互动实验

主从映射器

相对 / 绝对(推荐)

两种模式只差一个 offset。拖主臂,看看从臂目标怎么算;推荐切到绝对模式,先把两臂差收到 5° 以内再开始。软限位红区只是参考——真实遥操默认不夹限位/禁区(见 §5)。

target = leader + offset0.0 + 0.0 = 0.0°
从臂软限位按文档里的 [−98.2°, 98.0°] 画,红区只是参考;真实遥操默认不夹限位/禁区(§5)。“对齐到主臂”是普通运动,仍会过限位和工作空间。

5. 遥操不受限位和禁区影响,但急停仍然有效#

一句话:主从遥操默认不受关节限位、速度/加速度上限、桌面高度和底座禁区的影响。主臂能到哪,从臂就跟着去哪。急停、过温、心跳/控制环故障和跟随误差仍然生效。

遥操的目标仍然要过 SafetyLayer.filter(),但规则 1–4 默认被主动关闭:主从遥操是手在带,操作者的手就是参考。这不是绕过安全层,而是安全层在遥操模式下只保留“该停的事”。

实机推理(第 10 章)走同一条豁免:那条链路的参考是模型的输出,不是规划器,所以 ActionSource.POLICY 和 ActionSource.TELEOP 一样默认不拦限位 / 速度 / 禁区,开关分别是 [safety] policy_enforce_limits 和 teleop_enforce_limits。

规则 普通运动(move / 复现 / 对齐) 主从遥操(默认) 实机推理(默认)
关节限位 拦 不拦(从臂自己的上下限也不夹) 不拦
速度 / 加速度 限 不限,主臂多快从臂多快 不限:只剩「单拍最大关节变化」
桌面高度 / 底座禁区 拦 不拦 不拦
跟随误差 不适用 开:指令最多领先实测 15°,防止从臂被挡住时目标一路飘走 开(同左)
急停 拦 拦,任何模式下都有效 拦
过温 整臂 hold 整臂 hold;过流只报警,不拦运动 整臂 hold
心跳 / 控制环故障 hold hold hold

建议:主从遥操时关闭「安全区 / 禁区」拦截(保持 teleop_enforce_limits = false)。安全区按 TCP 与底座/桌面的关系裁剪目标;一旦从臂在边界被截停,主臂还在继续走,页面就会变成“从臂卡住、跟随误差越来越大”,采集出来的示教也会断掉。前提是工作区清空、有人扶主臂、急停可触达;如果现场有固定障碍或人员会进入工作区,再打开拦截。

为什么把限位和禁区也关掉:从臂一旦停在"底座禁入圆柱"的边缘,主臂想让它展开时,关节空间的直线路径会从底座正上方扫过去——每一拍的中间目标都在禁区里,于是全被拒掉。从臂死死钉在边界上,主臂怎么动都不跟,页面只剩一个红色「超出工作空间」。现场遇到过:从臂折叠成塔(末端 z≈360 mm、离底座轴 60.3 mm,禁区半径 60 mm),主臂展开到 57.8°,从臂一动不动。

手带着的臂不会比自己更不知道要去哪,所以这些规则只留给没人扶着的运动: move_joints / move_pose、对齐到主臂、动作复现仍然照常过限位和工作空间。

想把拦截加回遥操:勾上遥操卡片里的「遥操时仍按限位 / 禁区拦截」,或直接在 ~/.starm/config.toml 的 [safety] 里写 teleop_enforce_limits = true。勾上之后从臂到边界就停,页面会亮「限位 / 超出工作空间」。

另外:遥操期间调用 move_pose / move_joints 会被拒绝(teleoperation is running; ...),急停始终有效。

可选:打开拦截时,限位只管从臂#

主臂是一台"手轮",它的读数不设任何限位——你推到哪儿,目标就是哪儿。打开拦截后,限位只作用在从臂身上,而且只在从臂自己走到行程尽头时才拦住它。

这一点以前是错的:主臂的读数超前于从臂(最多 15°),它的目标会先一步跨过从臂的行程;旧代码只看"目标被夹了没有",于是从臂还在半路上,"限位"标志就亮了、工作空间也按那个超前位姿判定,从臂会在离边界还有一段距离的地方突然停住——看起来就像 "限位是拿主臂判断的、从臂还没到就不动了"。

打开拦截后的行为:

  • 关节限位:目标夹到从臂自己的上下限,从臂一路开到那里;「限位」标志在它真正贴上去(差 ≤0.5°)时才亮。
  • 工作空间:被拦时,从臂沿"当前位置 → 主臂目标"这条线走到自己能到的最远点,停的位置就是它自己的边界,不是主臂目标越界的那一拍。

控制环停了会怎样#

每个控制周期都要读主臂、读从臂、写从臂,任何一次串口读写失败(丢一包、舵机一时没应答)都会抛异常。以前一次失败就让控制环线程静默退出:从臂定格,页面还显示 「遥操中」,点「停止」再「开始遥操」也没用——因为线程已经没了,只有断开重连才会新建一个。

现在这条路被堵上了:控制环会记下原因(health.fault)、停掉遥操会话,页面顶部显示「控制环已停止」,遥操卡片直接写「点『断开』再重新『连接』」。看到这行字就别再反复点开始了,重连一次就好。

遥测不是每个周期都读#

电压 / 温度 / 电流以前和控制环同频(30 Hz),也就是每个周期多三条 sync_read;它们都是秒级变化的量,现在固定 5 Hz 读一次,其余周期用缓存值。位置读和写仍然是每周期一次——从臂跟不跟得上,只取决于那两次。

这也解释了为什么"跟随误差"那一列有意义:正常情况下它接近 0,从臂被挡住时会明显变大。

6. 页面怎么用#

  1. 先确认两只臂都标定过:报 not calibrated 就回 §3 走一遍(主臂、从臂各一次)
  2. 连接:真机模式下填两个串口(从臂 + 主臂),点「连接」
  3. 连上后「主从遥操」卡会显示 "就绪",同时「主从对照」表已经在刷新 ——不用先开始遥操就能看到两只臂现在差多少
  4. 选映射方式:推荐绝对;先看「主从对照」把两臂差收到 5° 以内(流程见 §4),收不进去再回退相对
  5. 扶住主臂,点「开始遥操」
  6. 移动主臂,从臂跟着动;「主从对照」表里看主臂 / 从臂 / 跟随误差
  7. 结束时点「停止」——从臂保持在当前位置,不会弹回

没点「开始遥操」之前,对照表最后一列叫「差值」,是两臂当前的原始角度差(从臂 − 主臂),既不扣偏置也不受映射方式影响——它就是你想先看清的那个差异。点「开始遥操」后这一列变成「跟随误差」:相对模式下会扣掉起始偏置,所以刚开始时接近 0,只有从臂被挡住或跟不上时才会变大。

仿真模式下有一条虚拟主臂(三个滑块),没有硬件也能看懂主从是怎么回事。

先分清两个串口#

两台机械臂用的是同一型号的 USB 转接板,/dev/serial/by-id/ 下的名字只差一串序列号,光看名字分不出谁是主臂:

text
/dev/serial/by-id/usb-1a86_USB_Single_Serial_5B79081041-if00
/dev/serial/by-id/usb-1a86_USB_Single_Serial_5B7A001004-if00
                                       ^^^^^^^^^^ 只有这段不同

方法一:拔插法(最可靠)

bash
# 1. 两个都插着,先列一遍
ls -1 /dev/serial/by-id/

# 2. 只拔掉主臂(你手扶着的那台),再列一遍
ls -1 /dev/serial/by-id/
#    → 少掉的那条就是主臂

# 3. 把主臂插回去,确认它又出现
ls -1 /dev/serial/by-id/

也可以用 SDK 自带的命令,输出会带序列号,更好记:

发布包没有把 starm 装进 PATH,用模块方式跑:

bash
PYTHONPATH=so101_studio_sdk .venv/bin/python -m starm ports
# /dev/serial/by-id/usb-...5B79081041-if00 -> /dev/ttyACM0 serial=5B79081041
# /dev/serial/by-id/usb-...5B7A001004-if00 -> /dev/ttyACM1 serial=5B7A001004

认出来之后在两根线上贴标签(比如"主 = 5B7A / 从 = 5B79")。by-id 路径是跟着板子走的,以后插哪个 USB 口都不会变。

方法二:先只连从臂

分辨不出来时,把「主臂串口」留空,只填从臂串口先连上:

  • 能正常动、示教正常 → 这条是从臂,剩下那条就是主臂
  • 再断开、填上主臂串口重连

页面里怎么选

连接卡的串口输入框带下拉候选——页面上会写"检测到 2 个串口,请从下拉里选一个",点开就能看到两条完整路径,不用手打。

别填反。反了的话 SDK 会把真从臂当主臂读、把真主臂当从臂驱动—— 主臂会上力跟你较劲。所以别用"随便填一个试试"的办法。

连上之后怎么验证没连反

去「主从遥操」页看状态:

显示 含义
就绪:先扶住主臂,再点「开始遥操」 主臂认到了
没有检测到主臂… 主臂串口没填,或填错了

再点「开始遥操」,轻轻动一下主臂——「主从对照」表里主臂列应该跟着变,从臂列跟着走,而主臂本身推起来应当是松的(力矩已关)。如果主臂推不动,就是两臂填反了,立刻点「停止」。

7. 常见问题#

现象 原因 处理
the leader arm is not calibrated 主臂没有标定文件,或舵机被改过 标定,或「从文件恢复」
标定完还是老样子 保存后没重连——新标定要重新「连接」才生效 断开再连接
the follower arm is not calibrated 同上,从臂 同上
leader and follower differ by X° 绝对模式下两臂没对齐 点「对齐到主臂」,等从臂停下再开始;或改用相对
shoulder_lift target ... outside soft limits(出现在对齐 / 普通移动时) 主臂停在了从臂够不到的角度 点「对齐到主臂」:从臂会走到边界,页面告诉你主臂还要扳多少
对齐目标会把从臂带到工作空间外 主臂姿态会让末端扎进桌子或底座 先把主臂抬到桌面上方、远离底座,再点「对齐到主臂」
没有检测到主臂 连接时没填主臂串口 断开重连,填上主臂串口
leader is not connected 主臂在遥操中断开 检查线缆,重新连接
从臂不动,误差为 0 主臂没动(或主臂被卡住) 检查主臂是否真在动
从臂跟不上,误差很大 主臂动得比从臂自己跟得上的速度还快,或从臂真的被挡住 / 卡住 放慢手上的动作;必要时点「停止」看一眼从臂是不是顶着东西
勾了「遥操时仍按限位 / 禁区拦截」后从臂停在半路 从臂自己到了限位,或目标进了桌面 / 底座禁区 看「安全标志」写的是哪个;这一格默认是关的
从臂定格,主臂列和顶部 Hz 一起冻住 控制环已停止(一次串口读写失败) 断开 → 重新连接;不是重开遥操

参考#

  • 第 2 章:机械臂关节 —— 六个关节的轴、范围
  • 第 5 章:到位判断 —— 另一条"按轨迹走"的链路,可以对比着看
  • 代码:starm/teleop.py(遥操会话)、starm/backends/lerobot_backend.py(总线读写)
  • 标定文件格式:lerobot 的 MotorCalibration(id / drive_mode / homing_offset / range_min / range_max)