主从遥操
配套页面:控制台的「主从遥操」页签
先说结论: 主从遥操默认不受关节限位、速度/加速度上限、桌面高度和底座禁区的影响;急停、过温、心跳/控制环故障和跟随误差仍然生效(见 §5)。
推荐绝对映射: 启动前先用「主从对照」把两臂差收到 5° 以内(见 §4)。
1. 原理:每个控制周期都在跑的一条链#
主从遥操就是一个人用手摆主臂,从臂照着做。听起来简单,实现上是一条固定频率的链:
每 1/30 秒(30 Hz):
① 读主臂的六个角度 backend.read_leader()
② 加一个偏置 target = leader + offset
③ 过安全层 急停、过温、跟随误差(限位/禁区默认不参与,见 §5)
④ 写给从臂 backend.write_follower()
关键点:主臂是从臂的"目标源",不是"另一台要控制的机器"。从臂的运动指令完全来自主臂读数,没有任何规划和插值——所以主臂动多快,从臂就跟多快(在安全层允许的范围内)。
代码在 starm/teleop.py 的 TeleopSession._target(),每个周期调一次:
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 |
两份标定文件各自独立,标了一个不代表另一个能用:
~/.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 |
行程两端:保存时以中位为中心对称裁剪后的值 |
标定流程:中位 → 全行程 → 保存#
整个过程是你用手搬、程序只读:程序不发任何运动指令,只在你转动时持续读位置。页面上是五个动作:
① 开始标定 → 卸力、打开总线,手臂可以自由推动
② 摆中位 → 大臂近似水平、小臂水平前伸、手腕居中、夹爪半开
③ 确认中位 → 把这个姿态写进编码器半圈;**从这一刻才开始记最小/最大**
④ 扫全行程 → 逐个关节缓慢转到两端,表格里的「最小/最大」实时跟着走
⑤ 保存标定 → 校验行程 → 以中位为中心对称裁剪 → 写舵机寄存器 + 标定文件
六个关节都要扫,每个关节两个方向都转到机械端点:
| 关节 | 怎么转 |
|---|---|
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 (这只臂仍是卸力状态;重新「连接」后力矩恢复、新标定生效)
"已标定"是怎么判定的#
不是看文件在不在,而是拿文件里的值和舵机里存的值逐项比对:
same_ranges = range_min / range_max 全部相等
same_offsets = homing_offset 全部相等
is_calibrated = same_ranges and same_offsets
所以会出现"我明明标过,它却说没标定"——多半是舵机被重新写过、文件没更新。
两种修复手段#
| 情况 | 用什么 | 代价 |
|---|---|---|
| 舵机被改过,文件还好 | 从文件恢复(把文件值原样写回舵机) | 2 秒 |
| 没有文件,或文件也坏了 | 重新标定(中位 → 扫行程 → 保存) | 2–3 分钟 |
如果现有标定文件存在,点「开始标定」会先把它备份成
*.json.bak;第一次标定还没有文件,所以不会产生备份。
4. 映射方式:推荐绝对,回退相对#
两种模式的公式完全一样:
target = leader + offset
区别只在 offset 怎么取:
| 相对(回退) | 绝对(推荐) | |
|---|---|---|
| offset | 启动时抓一次:从臂 − 主臂 |
恒为 0 |
| 从臂 = | 主臂 + 起始差 | 主臂 |
| 启动要求 | 两臂姿势可以完全不同 | 两臂必须已对齐(差 ≤5°) |
| 适合 | 两臂标定零点差很大、只想快速跟上 | 推荐:要求从臂严格复刻主臂;采集/复现/训练希望关节角与示教一致 |
推荐用绝对映射。 绝对模式下
从臂 = 主臂,主臂和从臂的关节角一一对应,适合教学、采集和复现;它不会像相对映射那样把启动时的两臂偏置一直保留下去。代价是启动前必须先把两臂对齐(差 ≤5°)。如果两臂标定零点差很大、怎么都收不进 5°,再回退相对映射。
同一张卡片,切换下拉就换一种映射;页面的默认选项已经选「绝对(推荐)」。选「绝对」后会多出 「两臂差 / 对齐到主臂」一行;想先跑起来也可以切回「相对」。
为什么绝对模式要求先对齐#
绝对模式下 offset=0,从臂的第一条指令就是主臂的角度。如果两臂差 20°,从臂会在一个周期内跳 20°——机械上是一次猛烈的冲击。
所以这事必须有个门槛。这个页面的门槛是 5°:SDK 的默认值是 2°,页面显式放宽了——两臂是各自标定的,零点差几度很常见,2° 常常怎么扳都收不进去;而 5° 仍然只是一次小姿态修正。超过门槛就拒绝执行:
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)都不一样。所以主臂能到的角度,从臂不一定能到。现场踩过的一个例子:
主臂 shoulder_lift = -102.6° 从臂限位 = [-100.0°, 100.0°]
主臂 elbow_flex = 96.5° 从臂限位 = [-100.0°, 90.0°]
主臂 wrist_roll = 162.0° 从臂限位 = [-160.0°, 160.0°]
旧实现把这些角度原样下发给从臂,安全层在发指令之前就把整条目标拒掉:
SafetyError: shoulder_lift target -102.55 is outside soft limits [-100.0, 100.0]
从臂一动不动,操作者只看到一句英文报错,不知道该怪谁。
现在「对齐到主臂」分三步:
- 夹紧:逐关节把主臂目标夹进从臂当前可达的区间,得到「最接近的可达姿态」;
- 预检:先用
SafetyLayer.workspace_check()看这个姿态会不会把末端带到桌面以下、或钻进底座禁区——会的话直接拒绝,并说出具体的 z 和半径; - 残差:被夹掉多少、主臂要往哪个方向扳多少,逐关节报回来:
从臂已走到可达边界,还差 6.5°:请把主臂扳回来 —— elbow_flex 6.5°(主臂 96.5° → 从臂边界 90.0°)
从臂先走到最靠近的位置,剩下的交给手:主臂是无扭矩的,扳回来几度就行。差值降到 5° 以内, 「两臂差」变绿,绝对模式就能启动。
对齐是后台运动:从臂还在走的时候页面会显示「从臂正在移动…」,这时点「开始遥操」 会把这次对齐打断,所以等它停下再开始。
还是收不进 5°?那是标定零点不一致#
两臂读到的「度」是 (原始计数 − 标定区间中点) × 360/4095,中点取的是标定时扫出来的行程中点,不是机械上精确的同一个姿态。两次标定的「中位」摆得不一样,零点就差几度:物理上明明对齐了,页面还显示 elbow_flex +6.0°,怎么扳都收不进去。
判断方法:把两臂摆成同一个姿势(比如都回到中位),逐关节看差值。如果某个关节始终差一个固定的量,那就是零点差,不是你的手不准。
处理:
- 重新标定两臂,两次都用同一个物理姿态摆中位(页面标定第 1 步的那句「大臂近似水平、小臂水平前伸、各关节都在行程中间」就是给这个用的);
- 或者干脆用相对映射——它只传位移,零点差多少都不影响。
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. 页面怎么用#
- 先确认两只臂都标定过:报
not calibrated就回 §3 走一遍(主臂、从臂各一次) - 连接:真机模式下填两个串口(从臂 + 主臂),点「连接」
- 连上后「主从遥操」卡会显示 "就绪",同时「主从对照」表已经在刷新 ——不用先开始遥操就能看到两只臂现在差多少
- 选映射方式:推荐绝对;先看「主从对照」把两臂差收到 5° 以内(流程见 §4),收不进去再回退相对
- 扶住主臂,点「开始遥操」
- 移动主臂,从臂跟着动;「主从对照」表里看主臂 / 从臂 / 跟随误差
- 结束时点「停止」——从臂保持在当前位置,不会弹回
没点「开始遥操」之前,对照表最后一列叫「差值」,是两臂当前的原始角度差(从臂 − 主臂),既不扣偏置也不受映射方式影响——它就是你想先看清的那个差异。点「开始遥操」后这一列变成「跟随误差」:相对模式下会扣掉起始偏置,所以刚开始时接近 0,只有从臂被挡住或跟不上时才会变大。
仿真模式下有一条虚拟主臂(三个滑块),没有硬件也能看懂主从是怎么回事。
先分清两个串口#
两台机械臂用的是同一型号的 USB 转接板,/dev/serial/by-id/ 下的名字只差一串序列号,光看名字分不出谁是主臂:
/dev/serial/by-id/usb-1a86_USB_Single_Serial_5B79081041-if00
/dev/serial/by-id/usb-1a86_USB_Single_Serial_5B7A001004-if00
^^^^^^^^^^ 只有这段不同
方法一:拔插法(最可靠)
# 1. 两个都插着,先列一遍
ls -1 /dev/serial/by-id/
# 2. 只拔掉主臂(你手扶着的那台),再列一遍
ls -1 /dev/serial/by-id/
# → 少掉的那条就是主臂
# 3. 把主臂插回去,确认它又出现
ls -1 /dev/serial/by-id/
也可以用 SDK 自带的命令,输出会带序列号,更好记:
发布包没有把 starm 装进 PATH,用模块方式跑:
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)