ASPIRE真机YAM部署全流程:从相机手眼标站到双臂机械臂闭环控制

原创2026-10-27 18:34:461,899 阅读

ASPIRE真机YAM部署全流程:从相机手眼标站到双臂机械臂闭环控制

ASPIRE(Agentic Skills Discovery for Robotics)是一个把"技能精炼"当作持续学习方式的机器智能体框架,其 RealYamEnv 真机适配器让开发者可以驱动真实的 YAM 双臂工作站:两臂各 6 关节、独立 CAN 电机服务,加上 RealSense 相机与手眼标定,即可完成从"看见物体"到"抓起物体"的双臂闭环控制。本文带你完整走一遍部署流程:安装环境、用 ChArUco 板做相机手眼标定、配置 station.yaml 站点档案、启动双臂服务,最后跑通观察与关节运动验证。

ASPIRE双臂机械臂真机部署:相机手眼标定与技能发现演示

一、先认识 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. 终端 1:scripts/supervise_services.sh --providers sam3,curobo --profile "$ASPIRE_PROFILE" 启动 SAM3(分割,默认端口 8114)与 cuRobo(带碰撞感知规划,默认端口 8118);
  2. 终端 2/3:左右臂 yam-servers;
  3. 终端 4:scripts/start_system2.sh --station ... --allow-motion 启动 CAP MCP 服务与 Viser 可视化页(http://127.0.0.1:8080,含 3D 机器人模型、Go home 按钮与实时相机流);
  4. 终端 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(倒扣叠杯)。

ASPIRE在LIBERO-Pro、Robosuite与BEHAVIOR-1K基准上的成功率对比

九、录制产物与安全收尾

每次运行都保留标准 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 论文级真机演示的完整运行基础。

登录后查看全文
ASPIRE