认识与连接机械臂
面向工程 / 研发人员 · 每一步的输出现场实测 · 配套 Web 控制台在发布包 so101-webapp-* 里
1. 读完你会什么#
- 说清这台臂的能力边界,以及它在整条控制链里的位置
- 用发布包装好依赖,判断只跑仿真还是接真机,以及为什么真机一定要 lerobot(约 1.5–5 GB)
- 找到并确认机械臂的串口(用
/dev/serial/by-id/,不是ttyACM0) - 打开 Web 控制台,把机械臂连上并动起来
- 看懂三维姿态视图,知道每个标记的含义
- 用 IK 预检在动手之前判断一个位姿够不够得着
2. 先建立一张链路图#
你写的每一行代码,最终都会走完这条链:
你的脚本
└─ starm.Arm move_joints / move_pose / gripper
├─ MotionPlanner 关节插值、直线插值、速度 → 时长
├─ Kinematics URDF 正解 / LM 逆解
├─ SafetyLayer 限位、限速、限加速、工作空间、跟踪误差、急停
└─ ControlLoop (30 Hz) 每周期:读状态 → 安全层 → 写目标
└─ LeRobotBackend lerobot → STS3215 舵机总线
记住两件事,后面所有行为都能解释:
- 安全层是唯一写舵机的路径。
Arm的任何方法都绕不过它,所以越界的目标不会"飞出去",只会报错。 - 移动是"提交 + 推进"。
move_*默认阻塞到到位;wait=False时只提交轨迹,由 30 Hz 回路去推进。
主从遥操是这条规则的例外:手就是参考,限位 / 限速 / 限加速 / 工作空间在遥操时不参与(可在页面上加回来),跟踪误差、过温、急停仍然生效。见第 6 章 §5。
3. 环境与依赖#
这一节按发布包 so101-webapp-0.3.0-20261112.zip 走:解压 → 装依赖 → 自检 → 启动
→ 连接机械臂 → 用 Web 的各项功能。只跑仿真的话,十分钟内能打开;要接真机,再加
lerobot 和串口权限。
本文以
0.3.0-20261112为例;以后换版本,把目录名和 zip 名换掉即可,命令不变。
3.1 解压后先认识目录#
so101-webapp-0.3.0-20261112/
├── start.sh 启动 Web 控制台
├── requirements.txt 仿真 / Web 必需依赖
├── README.md 三分钟快速开始
├── INSTALL.md 安装、启动、常见问题
├── docs/webapp-guide.md 界面逐屏说明
├── webapp/ Flask 后端 + 前端静态资源
├── so101_studio_sdk/ 机械臂 SDK(server 自动加载,不用 pip install)
└── scripts/check_env.py 环境自检:仿真 / Web / 真机
几个要点:
- 整个目录一起用,不要把
index.html或webapp/单独拖出来;前后端和 SDK 是配套的。 - 运行期数据默认写在包目录下:采集在
recordings/,数据集在datasets/,训练输出在outputs/。位姿库、config.toml和仿真标定在~/.starm/(可用STARM_HOME改);真机标定在~/.cache/huggingface/lerobot/calibration/下的robots/so_follower/、teleoperators/so_leader/。 - 包按 Linux(Ubuntu 22.04+) 打包,实测环境是 Python 3.12.13;代码本身要求Python ≥ 3.11(SDK 用标准库
tomllib),3.11 和 3.13 也跑过仿真连接与控制回路。 Windows 建议用 WSL2 Ubuntu,并把 USB 串口直通进去;原生 Windows 不能直接跑./start.sh,macOS 未验证。
3.2 安装:三个 profile,按需要选#
| profile | 装什么 | 能做什么 |
|---|---|---|
| A. 只仿真 / 看界面 | requirements.txt |
打开 Web、仿真连接、熟悉界面 |
| B. 加真机 | A + CPU 版 torch + lerobot[feetech] |
连真机、主从遥操、相机标定、采集、质检 |
| C. 加训练 / 推理 | B + lerobot[training](含 dataset) |
ACT 训练、数据集推理、实机推理 |
A. 只仿真 / 先看界面(不需要机械臂,也不需要 lerobot):
unzip so101-webapp-0.3.0-20261112.zip
cd so101-webapp-0.3.0-20261112
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
B. 加真机:只接真机、不训练时,CPU 版 torch 就够了,还省约 3.4 GB:
pip install "torch==2.11.0+cpu" --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt
pip install "lerobot[feetech]==0.6.1"
C. 加训练 / 推理:训练/推理还需要 lerobot[training](它会带 dataset 的
datasets / av / torchcodec)。训练不要用 CPU 版 torch——会慢到不可用:
# NVIDIA:先装与驱动匹配的 CUDA 版 torch,不要 +cpu
pip install "torch==2.11.0"
python -c "import torch; print(torch.cuda.is_available())" # 期望 True
pip install "lerobot[feetech,training]==0.6.1"
# 只做数据集推理、不训练:也可以只装 lerobot[feetech,dataset]
如果机器没有 NVIDIA GPU,保留 B 的 +cpu 也能跑训练/推理,但只适合冒烟测试;正式训练请换 CUDA 版,或明确接受 CPU 的慢。
已经按 B 装了
+cpu再想训练:torch==2.11.0会匹配本地的2.11.0+cpu, pip 不一定会替换。最稳的是从干净.venv按 C 重装;或在装 CUDA 轮子时加--force-reinstall,装完用torch.cuda.is_available()确认。
真机(B/C)还要求:
- 当前用户在
dialout组(sudo usermod -aG dialout $USER,然后重新登录); - 机械臂已经做过关节标定;没有的话,先在「主从遥操」页底部的「关节标定」卡片完成主臂/从臂标定;
- 串口不要被别的脚本占用(一个进程一个连接)。
不需要
pip install starm:webapp/server.py会把包内的so101_studio_sdk/加进导入路径。之后都从包根目录启动,别在webapp/里面另起一个解释器。只装 A 时,训练/数据集推理会提示缺
lerobot / datasets;要离线训练和推理,按 C 装,即使不接机械臂。
3.3 自检:先看四行结论#
python3 scripts/check_env.py
它会逐项检查 numpy / flask / lerobot / scservo_sdk / torch、串口、dialout 组、标定文件和训练依赖,最后给出四行结论:
✓ 仿真(Arm.sim) 可以跑
✓ Web 控制台 可以跑
✓ 真机(Arm.connect) 可以连
✓ 模型训练(ACT) 可以训练
- 只跑仿真时,后三行可能显示“缺 lerobot / 缺标定 / 缺训练依赖”,不影响打开界面;
- 要连真机,仿真 / Web / 真机三行都要过;要训练/推理,最后一行也要过;
- 退出码
0= 至少能仿真,1= 连仿真都跑不了,先把依赖装齐。
3.4 启动 Web 控制台#
./start.sh
# 浏览器打开 http://127.0.0.1:8010
常用参数:
./start.sh --port 8080 # 端口被占用时换一个
./start.sh --host 0.0.0.0 # 同一局域网的其他设备可访问
启动时会打印这次用的是哪个解释器,以及 lerobot 可用 → 可连真机 还是
无 lerobot → 只能连仿真。看到这两行,就知道自己装到哪一步了。
--host 0.0.0.0只给可信局域网用:控制台没有登录/鉴权,不要直接暴露到公网。停止服务在终端按Ctrl+C;不要在服务运行时拔掉 USB 串口。
3.5 连接机械臂#
先仿真,再真机。 仿真不需要硬件,控制回路、安全层和真机是同一份代码,最适合确认“包能跑、界面能动”。
仿真
- 打开
http://127.0.0.1:8010; - 连接卡片选 仿真;
- 点 连接,顶栏出现绿色“已连接 · 仿真”;
- 拖一个关节滑块,看 3D 姿态和遥测是否跟着变;
- 点 断开,确认能正常收尾。
真机
- 插好从臂 USB,确认串口:
ls /dev/serial/by-id/(串口细节见本章 §4); - 页面选 真机,点「重新扫描」,选中从臂串口;扫不到就直接填
/dev/serial/by-id/...,不要长期写死ttyACM0; - 要主从遥操:在同一张「连接」卡片里先填「主臂串口」;只连从臂就留空。连接后再改串口,必须先「断开」重连;
- 勾选安全确认,再点 连接;
- 顶栏显示“已连接 · 真机”后,先做一个小幅度关节动作;鼠标/手指停在右上角急停按钮上,并另备一个可断电的插排或物理开关。
连接失败先看页面日志和 scripts/check_env.py 的结论:
| 现象 | 原因 | 处理 |
|---|---|---|
lerobot is not installed |
用的是没装 lerobot 的解释器 | 从包根目录用 .venv/bin/python 或 ./start.sh |
串口打不开 / Permission denied |
不在 dialout 组,或串口被占用 |
加组后重新登录;先断开其他脚本/页面 |
| 扫不到串口 | 没装 udev 规则、转接板不同、或 WSL 没直通 USB | 手填 /dev/serial/by-id/...;WSL 用 usbipd 直通 |
| 连接报未标定 | 缺关节标定 | 先在「主从遥操」页底部的「关节标定」卡片完成标定 |
| 页面 8010 打不开 | 服务没启动/端口被占 | 看终端;换 ./start.sh --port 8081 |
3.6 Web 各项功能地图#
连接成功后,按下面的顺序用。第一次不要跳步——每一步都建立在前一步正确的基础上。
| 区域 | 能做什么 | 第一次怎么用 |
|---|---|---|
| 连接 | 仿真 / 真机、扫描串口、连接/断开 | 先仿真,再真机;真机要勾安全确认 |
| 关节 | 六个关节滑块、数值输入、实时角度 | 先小幅度拖 shoulder_pan,松手即下发 |
| 末端位姿 | x/y/z/pitch/roll、IK 预检、直线/关节路径 | 每个新位姿先「IK 预检」,再「移动」 |
| 到位判断 | 设目标位姿/容差,判断是否到位 | 先取当前位姿,再设容差;不要用眼睛代替数值(第 5 章) |
| 夹爪与动作 | 张开/闭合、力度、回零、停止、卸力 | 先空夹几次;卸力前一定扶住手臂 |
| 位姿库 | 保存/跳转常用姿态 | 先保存一个安全收拢姿态,再试其他位姿 |
| 主从遥操 | 主臂带动从臂、绝对/相对映射 | 主臂串口先在「连接」卡片填好;两臂标定,急停放手边(第 6 章) |
| 相机标定 | 顶部/腕部相机、九点/ArUco、单应矩阵 | 先用顶部相机做九点标定(第 7 章) |
| 数据采集 | 多相机录制、episode、开始/停止 | 先确认相机画面,再录一条短 episode(第 8 章) |
| 数据质检 | 丢帧/重复帧/时间戳/动作对齐 | 录完先质检,别直接拿去训练(第 9 章) |
| 模型训练 | 构建数据集、ACT 参数、loss 曲线、checkpoint | 先用小数据跑 quick 验证流程(第 10 章) |
| 数据集推理 | 离线对比预测/示教、chunk、误差表 | 选测试集,推理步数 chunk 先等于模型 chunk |
| 实机推理 | 相机 + 模型闭环、速度/间隔、安全层 | 第一次 1–2°、手放急停,基座和相机固定(第 10 章) |
| 遥测 / 日志 / 急停 | 末端位姿、频率、电压温度、错误、急停 | 出问题先看日志;急停任何页面都有效 |
3.7 全流程地图:从安装到第一次推理#
- 解压、装依赖、
check_env.py三行都过(只仿真可暂时不管真机行); ./start.sh,浏览器打开 8010;- 仿真连接 → 拖关节 → 夹爪开合 → 回零;
- 末端位姿:取当前、改 z/pitch、IK 预检、移动;
- 接真机:串口、安全确认、小幅度动作、断开;
- 主从遥操:主臂 + 从臂,确认跟随方向;
- 相机标定 → 采一条数据 → 质检;
- 训练一个短 run → 数据集推理 → 再考虑实机推理。
走完这 8 步,包里的 Web 功能就都摸过一遍了;后面各章只是把其中一步讲深。
3.8 数据、停止和常见问题#
数据位置
<包目录>/recordings/ 原始采集
<包目录>/datasets/ 构建后的数据集
<包目录>/outputs/ 训练输出和 checkpoint
~/.starm/ 位姿库、config.toml、仿真标定
~/.cache/huggingface/lerobot/calibration/
真机标定:robots/so_follower/*.json
teleoperators/so_leader/*.json
换机器或升级包时,把 recordings/、datasets/、outputs/ 一起带走;位姿库在 ~/.starm/,真机标定在 HF 缓存目录;两边都要备份,不要只复制包目录。
停机
- 终端
Ctrl+C停止 Web 服务; - 先「断开」机械臂,再关服务/拔 USB;
- 一个进程一个连接,页面共享同一个机械臂;串口是独占的,脚本和页面不要同时抢。
高频问题
| 现象 | 处理 |
|---|---|
missing required dependencies |
在包根目录激活 .venv 后 pip install -r requirements.txt |
lerobot is not installed |
真机路线没装 lerobot,或用了系统 python;用 .venv/bin/python / ./start.sh |
ModuleNotFoundError: scservo_sdk |
装 lerobot[feetech]==0.6.1,不要只装 lerobot |
| 串口权限 | sudo usermod -aG dialout $USER,重新登录 |
| 端口被占 | ./start.sh --port 8081 |
| 浏览器打开是旧页面 | Ctrl+F5;本项目静态服务默认 no-store |
| WSL 找不到 USB | usbipd list → usbipd attach --wsl --busid ... |
更细的安装说明在包内 INSTALL.md,逐屏界面说明在 docs/webapp-guide.md;本教程第 6–10 章分别讲遥操、相机标定、采集、质检、训练和推理。
4. 找到串口#
先说结论:用 Web 控制台的话,这一步可以跳过。 打开页面切到「真机」,串口框会把扫到的设备列成下拉候选,只有一个时还会自动填好 —— 你不需要手抄任何东西。
要在命令行里看,用这个:
ls -1 /dev/serial/by-id/
实测输出(42 个字符,正常终端宽度下不会折行):
usb-1a86_USB_Single_Serial_5B79081041-if00
把它前面拼上 /dev/serial/by-id/ 就是完整路径:
/dev/serial/by-id/usb-1a86_USB_Single_Serial_5B79081041-if00
网上常见的
ls -l /dev/serial/by-id/会把权限、属主、日期和-> ../../ttyACM0一起打出来,一行 96 个字符,在 80 列的终端里必然折成两行,看起来像文件被劈开了。换ls -1只打文件名,就不会。折行只是显示问题,选中复制仍然是完整的——但何必呢。
发布包里没有把 starm 命令装进 PATH,直接敲 starm ports 会 command not found。在包根目录用模块方式跑,它同样会给出完整路径、对应的 ttyACM0 和序列号:
PYTHONPATH=so101_studio_sdk .venv/bin/python -m starm ports
# /dev/serial/by-id/usb-1a86_USB_Single_Serial_5B79081041-if00 -> /dev/ttyACM0 serial=5B79081041
只有你以前在开发环境执行过
pip install -e so101_studio_sdk,starm ports才会在 PATH 里;用发布包时不要假设它存在。
优先用 /dev/serial/by-id/ 下的路径,不要用 /dev/ttyACM0。原因很实际:重新插拔之后 ACM 编号会变,写死 ttyACM0 的脚本今天能用、明天就连错了设备。
ls -1 什么都没有 → USB 线、供电或 CH340/CP2102 驱动的问题,先解决这个,不要往下走。
5. 界面总览#
串口确认之后,最快的验证方式是打开 Web 控制台——它把 SDK 的状态、安全层和运动学都摆在界面上,出错时连报错原文都直接给你。
控制台分十一个页签:连接(本图)、关节控制、末端位姿、到位判断、主从遥操、相机标定、数据采集、数据质检、模型训练、数据集推理、实机推理。右边那列(姿态视图 / 遥测 / 日志)由 8 个页签共用:连接、关节控制、末端位姿、到位判断、主从遥操、相机标定、数据采集、数据质检。模型训练、数据集推理、实机推理这 3 页是全宽布局,不显示右栏。
| 区域 | 作用 | 上手顺序 |
|---|---|---|
| 连接 | 选仿真 / 真机,连接与断开;真机可另填「主臂串口」(遥操用) | 第一步必做 |
| IK 求解器 | 热切换 lm / riemann,不用重连 |
求解失败时再动 |
| 夹爪与动作 | 张合、力度、回零、停止、卸力、示教 | 随时 |
| 位姿库 | 保存 / 跳转常用姿态 | 熟练后 |
| 姿态视图 | 真实 URDF 模型,可旋转 / 缩放 / 复位 | 一直看 |
| 遥测 | 末端位姿、回路频率、电压温度、安全标志 | 排查时看 |
| 日志 | 每条指令和每个报错 | 出问题先看这里 |
| 急停 | 任何状态下都有效 | 出事第一反应 |
先看右上角的红色 E-stop。 位置固定、一眼能找到;它是网页按钮,不是物理急停——另配一个可断电的插排/物理开关作为后备。
六个关节滑块在「关节控制」页签里(见 第 2 章);位姿输入和 IK 预检在「末端位姿」页签里;锚点、动作记录与复现在「到位判断」页签里;主从遥操在「主从遥操」页签里;真机遥操要回到「连接」卡片(不是遥操页),先填「主臂串口」再点「连接」。
6. 连接:两种模式#
仿真模式(推荐第一次用)#
- 选 仿真
- 点 连接
不需要硬件。控制回路、安全层、运动学和真机是同一份代码,唯一区别是最底下的执行器换成了虚拟关节。仿真跑通只说明控制链路可用;再上真机还要确认串口权限、方向/限位和现场安全。
真机模式#
- 选 真机
- 确认串口 —— 页面会自动扫描并填好(只有一个候选时),输入框下面那行会告诉你扫到几个;插拔了设备点「重新扫描」,也可以直接改成别的路径
- 勾选安全确认
- 点 连接
勾选框不是走形式:服务端会再校验一次 confirm 字段,没确认的请求直接 400。
为什么可以直接填?
/dev/serial/by-id/下不一定有条目——没装 udev 规则、用了别的转接板、或者在 macOS 上(路径是/dev/cu.usbserial-…),都可能扫不到。这时直接把路径写进去就能连。代价是ttyACM0这类编号插拔后会变,所以脚本里别写死。主臂串口在「连接」卡片,不在遥操页。 要主从遥操时,先在「主臂串口」填主臂的 by-id 路径,再点「连接」;已经连上后再填,需要先「断开」重连。
点「连接」后报
lerobot is not installed?你用的是没装 lerobot 的解释器。先确认启动的是哪个解释器:./.venv/bin/python -c "import lerobot; print(lerobot.__version__)";没有就装进.venv,而不是换./webapp/run.sh。
7. 读懂姿态视图#
渲染的是 URDF 里的真实网格,不是骨架线框。13 个 STL 零件按关节树装配,每一帧的位姿来自 SDK 的正运动学。
视角可以调:
| 操作 | 效果 |
|---|---|
| 拖动 | 绕机械臂旋转(方位角 + 仰角) |
| 滚轮 | 缩放 |
| 双击 / 「重置视角」 | 回到默认视角,并重新对准模型 |
| 标记 | 含义 |
|---|---|
| 灰色模型 | 当前姿态 |
| 橙色夹爪 | 活动指单独上色。它跟着 wrist_roll 转,所以末端旋转一眼可见 |
| 绿色圆环 | 当前 TCP |
| 半透明橙色模型 | 目标姿态,只在运动过程中出现 |
| 橙色圆环 | 目标 TCP |
| 白点 | 基座原点(z = 0) |
| 地面网格 | 桌面平面(z ≈ 30.1 mm) |
坐标系#
界面上的 X / Y / Z 用的是基座坐标系(URDF 的 base link):
- 原点在底座中心
- X 向左、Y 向后、Z 向上,单位 mm
- 桌面不在
z = 0,而在z ≈ 30.1 mm(底座原点比桌面低 30.1 mm)
注意它是 TCP(gripper 连杆上的固定指尖接触点,不是两指中点)的坐标,不是夹爪的转动中心——两者相差约 104 mm。
pitch / roll 与坐标系怎么摆无关:pitch 是进近方向与水平面的夹角,roll 就是 wrist_roll。
位姿怎么读、TCP 偏移、各个分量的含义,见第 3 章:末端位姿。
模型和位姿分别从哪来#
| 部分 | 来源 |
|---|---|
| 网格、装配关系 | webapp/static/models/so101/(URDF + STL) |
| 每帧的连杆变换 | /api/state 的 links,服务端用 starm.kinematics.fk() 算好 |
前端不重算运动学,只把服务端给的 4×4 矩阵套到对应网格上。所以三维图里的姿态和 SDK 认为的姿态永远是同一个东西——这也是拿它排查"我觉得它不该在那儿"的依据。
解析 URDF 时只取
<visual>,不取<collision>。这两者在 URDF 里成对出现,全拿会因为重复几何导致画面闪烁、材质发黑。
为什么夹爪单独上色#
手臂本体是灰白的,末端那根橙色的是活动指。它跟着 wrist_roll 转动,所以想确认
"到底转了多少度",看它就够了——灰色连杆绕自身轴转是看不出来的。
8. IK 预检:先算,再动#
IK 预检只求解、不移动。它回答两件事:
- 可达 → 给出一组关节角,你可以先看再决定要不要动
- 不可达 → 直接说清原因,比如
wrist_flex is at its upper limit (95.0 deg)
右侧那条报错里藏着一句最有用的话:
Pointing straight down costs reach height: at pitch 90 the arm only reaches about 80 mm above the table
5 自由度臂越要竖直向下,就越贴桌面。想在高处干活,把 pitch 降到 60–75。
习惯养成:每个新位姿先预检,再移动。 预检是零风险的,移动不是。
9. 仿真里的第一次上手:8 步#
| 步骤 | 在哪一页 | 操作 | 应该看到 |
|---|---|---|---|
| 1 | 连接 | 选「仿真」→ 连接 | 顶栏变绿点,显示「已连接 · 仿真」 |
| 2 | 关节控制 | 拖 shoulder_pan 到 20°,松开 |
模型转动,遥测里的角度跟着变 |
| 3 | 末端位姿 | 点「取当前」,看位姿框被填满 | X/Y/Z/pitch/roll 是当前值 |
| 4 | 末端位姿 | 填 X 0、Y -300、Z 150、pitch 65,先点「IK 预检」,通过后点「移动」 | 预检通过,列出一组关节角;再移动,状态栏显示目标航点 |
| 5 | 连接 | 点「张开」「闭合」 | 夹爪开合,夹爪开度 数值变化 |
| 6 | 末端位姿 | 保持 Y=-300,把 Z 改成 230、pitch 改成 90,点「IK 预检」 | 红色报错:够不着(约差 1.4 mm / 43.5°),并说明原因 |
| 7 | 连接 | 点「回零」 | 回到全 0° 姿态 |
| 8 | 连接 | 点「断开」 | 顶栏变灰,控件变暗 |
走完这 8 步,你已经把「连接 → 读状态 → 动关节 → 动末端 → 控夹爪 → 处理错误 → 收尾」 这条完整链路过了一遍。
10. 示教:用手摆姿态#
真机连上之后,「夹爪与动作」里有一个 示教 按钮。它的作用是卸掉力矩,让机械臂变成可以掰动状态——比拖滑块直观得多,尤其是要找个"大概齐"的姿态时。
操作顺序:
- 先扶住机械臂,或用支架托住它——示教一确认就会卸力,手臂会因重力下落;
- 点 示教,在确认框里点确定(此时力矩才释放);
- 用手把它摆到想要的姿态。左边六个关节滑块会实时跟着你动;
- 摆好之后点 完成示教(横幅右侧那个)——力矩恢复,机械臂就地保持,不会弹回原位;
- 想留下来,点「保存当前」存进位姿库,之后一键回位。
几个要点:
- 示教期间运动控件全部禁用。不是防你误触,是因为力矩关掉之后后端会跳过写目标,这时发运动指令只会报错。
- 示教时机械臂没有力矩,急停不能代替扶住手臂。急停按钮仍然可以按,但手臂已经无力矩,不能靠它阻止重力下落;所以第 1 步必须先扶稳/托住。
- 「完成示教」不会让机械臂动。它把目标冻结在当前实测位置,所以是"就地保持"。
- 示教中断开连接,服务端会先恢复力矩再关闭,不会把机械臂留在瘫痪状态。
- 仿真模式下这个按钮是灰的。虚拟关节掰不动,示教没有意义。
示教和「卸力」按钮的区别:卸力是一个开关,点了之后没有任何额外状态;示教是一个模式,有横幅、有明确的开始和结束、期间锁住运动控件。临时想挪一下用卸力,正经摆姿态用示教。
11. 常见状态与处理#
| 现象 | 原因 | 处理 |
|---|---|---|
| 控件全是灰的 | 未连接 | 先连接 |
| 「连接」是灰的,但「断开」亮着 | 已经连着(看顶栏写的哪种模式) | 先点「断开」,再切换模式或重连 |
| 「示教」是灰的 | 当前是仿真模式 | 示教只在真机上可用 |
| 点「连接」没反应 | 真机模式没勾安全确认 | 勾上 |
lerobot is not installed |
解释器没有 lerobot,或没从 .venv 启动 |
用 ./.venv/bin/python -c "import lerobot" 确认;没有就装进 .venv,不是换启动脚本 |
SafetyError: … outside soft limits |
目标越界 | 往回收,指令本身非法,重试没用 |
Unreachable: … |
IK 无解 | 改 pitch 或 z,不是 bug |
| 顶栏显示「急停中」 | 急停未解除 | 确认安全后点「解除急停」 |
| 遥测里「安全标志」有内容 | 这一拍被安全层削了 | 看是限位、限速还是工作空间 |
12. 几个必须知道的约定#
- 一个进程一个连接。 所有打开的页面共享同一个机械臂连接,它是单用户控制台,不是多人协作系统。
- 移动是"提交 + 推进"。 点「移动」后接口立刻返回,运动在 30 Hz 回路里跑。界面靠位置和目标的差值显示进度。
- 串口是独占的。 页面连着的时候,你的脚本打不开同一个串口。要跑脚本先点「断开」。
- 卸力会掉。 点「卸力」前先扶住机械臂——它没有抱闸。
- 急停不会自动恢复。 解除后不会继续急停前的动作,需要你重新发指令。
13. 想改界面?#
前端没有构建步骤,就四个文件:
webapp/static/index.html 页面结构
webapp/static/app.js 状态轮询、指令下发
webapp/static/view3d.js three.js 场景:URDF 网格 + 轨道相机
webapp/static/style.css 深色主题
本文件里的插图由 scripts/make_figures.py 生成。改版后重拍截图、改几个坐标就能重新出图,不用手工 P。
参考#
scripts/check_env.py—— 环境自检(依赖 / 串口 / 权限 / 标定)webapp/README.md—— Web 控制台的架构与 APIso101_studio_sdk/README.md—— API 全表so101_studio_sdk/examples/—— 四个可运行样例(01–04)so101-course-outline.md—— 配套的课程大纲(本章对应其中的 A2 / A3 两章)