ASPIRE真机YAM部署全流程:从相机手眼标站到双臂机械臂闭环控制
ASPIRE真机YAM部署全流程:从相机手眼标站到双臂机械臂闭环控制
ASPIRE(Agentic Skills Discovery for Robotics)是一个把"技能精炼"当作持续学习方式的机器智能体框架,其 RealYamEnv 真机适配器让开发者可以驱动真实的 YAM 双臂工作站:两臂各 6 关节、独立 CAN 电机服务,加上 RealSense 相机与手眼标定,即可完成从"看见物体"到"抓起物体"的双臂闭环控制。本文带你完整走一遍部署流程:安装环境、用 ChArUco 板做相机手眼标定、配置 station.yaml 站点档案、启动双臂服务,最后跑通观察与关节运动验证。
一、先认识 YAM 真机系统的架构
在动手之前,先理解 ASPIRE 真机栈的分层设计,这样部署时每个命令该在哪台机器上跑就一目了然:
- Arm Server(双臂服务):每个机械臂一个进程,独占 CAN 总线,负责电机驱动与重力补偿。启动服务即给电机上电。
- 客户端运行时:独占相机采集与运行录制,通过
RealYamEnv.execute_action_batch下发所有动作(包括 home 与夹爪命令)。 - 站点档案(station profile):每个站点一个目录,包含
station.yaml与带哈希校验的标定 bundle,档案中的station字段必须与ASPIRE_STATION环境变量一致。
完整架构说明见 docs/system2.md 中的控制链路图:Coding agent → MCP → 共享会话 → RealYamEnv → arm RPC clients → CAN motor drivers。
⚠️ 安全提示:ASPIRE 会执行大模型生成的 Python 代码。真机运行务必使用隔离主机,不挂载敏感凭据,网络访问受限。
二、第一步:准备主机环境
真机部署的宿主机前置条件(NVIDIA 驱动、CUDA、uv、SocketCAN、USB 相机权限与 arm 的 udev 规则)不会由安装脚本代劳,需按 docs/host-setup.md 提前配好。关键点:
- 安装
uv并加入PATH; - 配置 SocketCAN 接口(如
can_follow_l、can_follow_r)并确认相机 USB 可访问; - 若后续要跑 SAM3/cuRobo 视觉与规划服务,还需申请 SAM3 的 Hugging Face 门禁权重。
然后克隆仓库并进入根目录:
git clone https://gitcode.com/gh_mirrors/aspire5/ASPIRE
cd ASPIRE
三、第二步:一条命令安装 YAM 真机运行时
运行一键引导脚本:
scripts/bootstrap_yam_real.sh
它会创建 .venv-yam-real 环境,安装客户端、相机、录制与本地 Mink 逆运动学依赖(yam-real extra),并内置自检:用假站点验证配置加载、被动读取正常、未授权动作会被 safety_interlock 拒绝且 0 条命令下发——不触碰任何硬件。
如果你需要在本机驱动电机,还要额外安装服务端依赖:
VIRTUAL_ENV="$VENV_ROOT" UV_PROJECT_ENVIRONMENT="$VENV_ROOT" \
uv sync --frozen --active --project "$REPO_ROOT" \
--extra yam-real --extra yam-real-server --extra dev
细节见 scripts/bootstrap_yam_real.sh 末尾的提示。
四、第三步:相机手眼标定(ChArUco 板工作流)
标定是整条链路里最"动手"的一步,工作流完整文档在 src/cap_harness/yam_real/calibration/README.md。
1)建立标定环境
标定预览需要图形桌面,使用独立虚拟环境:
uv venv --python 3.12 .venv-yam-calibration
uv pip install --python .venv-yam-calibration/bin/python \
-r src/cap_harness/yam_real/calibration/requirements.txt
uv pip install --python .venv-yam-calibration/bin/python --no-deps -e .
2)打印 ChArUco 标定板
python -m cap_harness.yam_real.calibration board --output board.png
按实际尺寸打印:每边 5 格、方格 40 mm、标记 30 mm,外加白边,测量确认并平整刚性安装。
3)选择挂载模式
| 相机安装位置 | --mode |
标定板安装位置 |
|---|---|---|
| 固定在站点 | fixed |
刚性固定在选定的机械臂上 |
| 装在腕部 | wrist |
放在桌面或其他固定支撑上 |
4)采集与求解
保持选中手臂的 ASPIRE 服务运行,停掉其他相机/手臂客户端后执行(固定相机示例):
python -m cap_harness.yam_real.calibration calibrate \
--serial CAMERA_SERIAL --camera-name top --mode fixed --arm left \
--resolution 1280 720 --output-dir outputs/calibration/top --confirm-motion
交互流程:重力补偿下引导手臂使标定板入画 → 按 Space 保持标称位姿 → 确认扫描目标后再次按 Space 执行 15 位姿扫描(0.2 rad/s)→ 手臂回位后求解器自动写出结果。腕部相机则复用已标定的 XML 继续求解。
5)验收标定结果
每个输出目录包含 samples.json、采集 PNG、calibration.json 和 station_calibrated.xml。硬性指标:
- 至少 12 个可用样本且绕多轴旋转;
- 一致性 RMS ≤ 10 mm 且 ≤ 3°,使用前务必人工检查残差;
- 相机内参与畸变直接取 RealSense 出厂标定,本流程求解的是相机外参。
参考档案中可看到合格样例:src/cap_harness/configs/yam_real/yam-example/calibration/yam-example-v1/manifest.json 记录了 translation_rms_mm: 0.74、rotation_rms_deg: 0.34 的残差。标定输出只是数据,选入运行档案还需单独的站点配置步骤。
五、第四步:配置站点档案 station.yaml
站点档案是整个闭环控制的"契约"。包内参考档案 src/cap_harness/configs/yam_real/yam-example/station.yaml 也是默认站点 ID(yam-example),它声明了:
arms:左右臂的 CAN 接口、host/port(本机能用127.0.0.1加不同端口)、关节名、基座变换、home_joints与ready_joints;joint_limits与planning_workspace:关节限幅与规划工作空间;controller:30 Hz 控制频率、60 Hz 指令流、增益kp/kd、跟踪误差上限等;camera/aux_cameras:RealSense 序列号与分辨率;calibration:标定 bundle 名称与manifest_sha256哈希——加载器会校验 bundle 哈希,更换标定要同步更新 manifest。
自定义档案放到自己的目录,通过 --station-config-root 传入即可,说明见 src/cap_harness/configs/yam_real/README.md。
六、第五步:启动双臂服务
在每个服务终端先设置环境变量(替换占位符):
export ASPIRE_STATION="<station-id>"
export ASPIRE_CONFIG_ROOT="/absolute/path/to/station-profiles"
然后在两个终端分别启动左右臂:
yam-servers left --station "$ASPIRE_STATION" --config-root "$ASPIRE_CONFIG_ROOT"
yam-servers right --station "$ASPIRE_STATION" --config-root "$ASPIRE_CONFIG_ROOT"
记住三条运行法则:
- 启动 arm 服务即上电,初始标定夹爪行程时加
--calibrate-gripper且手指须为空; - CAP runner 只连接已存在的服务,不会替你启动它们;
- 关闭客户端不会停止服务,停止 arm 服务才会断电机动力。
完整说明见 docs/yam-real.md。
七、第六步:跑通观察与关节闭环验证
服务就绪后,用 cap-harness run 依次验证"只读"与"运动"两条通路:
1)观察站点(无需运动授权)
.venv-yam-real/bin/cap-harness run \
--benchmark yam_real --station "$ASPIRE_STATION" \
--station-config-root "$ASPIRE_CONFIG_ROOT" --suite observe_station --task-id 0 \
--program examples/yam_real/observe_station.py --output-root outputs
该程序仅三行语义:取任务上下文、取机械状态、取相机观测(见 examples/yam_real/observe_station.py)。
2)关节运动(需要 --allow-motion)
examples/yam_real/joint_motion.py 把右臂第 1 关节目标加 0.03 rad 后执行 move_to_joints。未加 --allow-motion 时,物理命令会在动作前返回 safety_interlock 错误——这是内置安全联锁在正常工作。
注意:夹爪位置是归一化的(0 闭合、1 张开);校准相机提供米制 RGB-D,未校准的辅助视角仅供目视检查;--max-steps 统计的是提交的动作数而非伺服周期。
八、进阶:接入 System 2 智能体,实现"看-想-做"全闭环
验证通路打通后,即可让编码智能体接管双臂。System 2 运行手册 docs/system2.md 描述了标准四终端 + 智能体的启动方式:
- 终端 1:
scripts/supervise_services.sh --providers sam3,curobo --profile "$ASPIRE_PROFILE"启动 SAM3(分割,默认端口 8114)与 cuRobo(带碰撞感知规划,默认端口 8118); - 终端 2/3:左右臂
yam-servers; - 终端 4:
scripts/start_system2.sh --station ... --allow-motion启动 CAP MCP 服务与 Viser 可视化页(http://127.0.0.1:8080,含 3D 机器人模型、Go home 按钮与实时相机流); - 终端 5:
scripts/start_system2_agent.sh --allow-motion启动新智能体,开机自动开夹爪并双臂回 home。
此时位姿任务走完整闭环:SAM3 分割 → 校准 RGB-D 定位 → 本地 Mink 求 IK → cuRobo 规划防碰撞轨迹 → 双臂执行 → 相机验证。笛卡尔运动请显式选择 YAM 求解器:MotionStrategy(ik_solver="mink", trajectory_planner="interpolation"),防碰撞规划用 cuRobo。
官方真机演示配方都以纯文本任务技能形式提供,例如 examples/yam_real/unscrew_bottle/TASK_CONTEXT.md(拧瓶盖倒药丸,双臂分工:一手持瓶一手拧盖)、examples/yam_real/rubiks_cube/TASK_CONTEXT.md(解魔方)、examples/yam_real/pill_in_bottle/TASK_CONTEXT.md(装瓶盖瓶)和 examples/yam_real/cup_stacking/TASK_CONTEXT.md(倒扣叠杯)。
九、录制产物与安全收尾
每次运行都保留标准 CAP trace 与时钟采样的 episode/raw 剧集,视频按站点控制率写入 media/videos,加 --no-videos 可关闭双路录制;采样会在运行 manifest 封存前停止。产物契约(run.json、outcome.json、manifest.json、trace/ 等)详见 docs/run-artifacts.md。
关机顺序:先完成进行中的动作、放稳手持物体并支撑手臂,然后依次 Ctrl-C 停 MCP、两个 arm 服务与服务监管进程——停 arm 服务即断电机动力。MCP 关机会等待执行中任务并关闭相机,但它不是急停。
想在不碰硬件的情况下做控制/打包测试,可以用 build_sim_station() 换入 MuJoCo 仿真体与合成相机,或在 MCP 上加 --sim 参数。
部署小结:bootstrap_yam_real.sh 装环境 → ChArUco 标定求外参 → station.yaml 落档案 → 双臂服务上电 → 观察/关节两级验证 → System 2 智能体接管闭环。走通这条链路后,你的 YAM 工作站就具备了 ASPIRE 论文级真机演示的完整运行基础。

