robot-linkerbot-linker_hand_o6

独立 LinkerHand O6 五指灵巧手(六轴,CAN 总线)的 Robonix 整机部署 —— 没有机械臂、没有移动底盘、没有相机。通过 pilot 用语音或文字指挥灵巧手跳手指舞。

本仓库只做装配,这里不含任何真实 package 源码 —— 原语与技能各自独立成仓, 由清单的 url: 在构建时拉取到 rbnx-boot/cache/。本目录只装:

robonix_manifest.yaml —— 部署清单,列出要拉起的包及其运行时配置。
soma.yaml + urdf/linkerhand_o6_right.urdf —— 供 robonix-soma 服务的手体描述与 URDF(详见 urdf/README.md)。
.env.example —— LLM 端点凭据模板(copy 为 .env)。

1. 能做什么

能力	工具	指令示例
手指舞	`gesture_dance`	“跳个舞” / “手指摆动 5 秒”
单轴位置 / 速度 / 力矩	手部原语的契约	(编程调用)

它无法伸手、抓取、搬运,也看不见东西:本部署没有机械臂也没有相机。soma.yaml 的 cannot_do 明确写了这些,以免 pilot 尝试物体操作。

2. Package 清单

manifest 中的顺序即为启动顺序。表中名称与 robonix_manifest.yaml 里 - name: 一致,也是 rbnx caps 显示的名字。

段	名称	仓库
`primitive`	`o6_hand`	primitive-linkerbot-linker_hand_o6-hand-rbnx
`skill`	`hand_gesture`	skill-hand-gesture-rbnx

原语持有 CAN 总线,提供六个 robonix/primitive/hand/* 契约。LinkerHand SDK 没有发布到 PyPI,已 vendored 进原语包,因此构建除了拉取这两个包之外不需要额外联网。

技能是独立发布的通用包,原样复用而非另建分支。它不绑定任何具体整机:作为纯消费者,它通过 atlas 发现原语、在激活时从 hand/info 读取轴序,驱动一个 6 维舞蹈向量 —— 正是 O6 的布局。

3. 前置条件

硬件:一只 LinkerHand O6 灵巧手,以及已接线通电的 USB-CAN 适配器。
robonix-cli(rbnx)在 PATH 上,且 robonix 源码树已注册(在该树执行 rbnx setup)。
Python 环境,含 python-can、numpy、grpcio、grpcio-tools、mcp、 fastmcp。两个包各自的 scripts/start.sh 里写了默认解释器路径,可分别用 LINKERHAND_O6_PYTHON / HAND_GESTURE_PYTHON 覆盖。
一个 LLM 端点供 pilot 使用。复制 .env.example 为 .env,填入 VLM_BASE_URL / VLM_API_KEY / VLM_MODEL。不需要图像输入 —— 本部署没有相机, 模型只作文本规划器。

4. 配置 —— 上机前必须确认的几处

4.1 CAN 总线

启动前先把总线拉起,波特率 1 Mbps:

sudo ip link set can0 up type can bitrate 1000000
ip -br link show can0          # 确认接口存在且已 up

接口未启用时原语会自行拉起,但那需要提权(PREFLIGHT_SUDO_PASS,见 .env.example)。推荐事先拉起:这样整个部署都不需要特权。

启动前请关掉总线上其他一切控制器 —— LinkerHand 的 ROS/ROS2 SDK、动捕手套、厂商 GUI。同一条 CAN 总线上两个写入方会互相抢手。

4.2 manifest 可调项

所有可调项都在 robonix_manifest.yaml:

hand_type —— right(CAN id 0x27)或 left(0x28)。取错则灵巧手不会应答,init 会在回读状态时失败。
can_iface / baudrate —— 默认 can0、1 Mbps。

技能没有配置项(config: {})—— 跳舞时长是逐次调用的参数。

5. 构建与运行

5.1 每次 session 拉起

rbnx build -f robonix_manifest.yaml     # 拉取两个包并执行各自的 codegen
rbnx boot  -f robonix_manifest.yaml     # 拉起整套栈,直到 Ctrl-C

然后在另一个终端:

rbnx caps -v                # 列出所有能力及其 provider 状态
rbnx tools                  # pilot 可调用的 MCP 工具
rbnx chat                   # 与机器人对话

rbnx shutdown 用于拆除由 rbnx boot 拉起的栈。

5.2 改包之后

改动某个包仓的代码后,必须清掉缓存检出,否则起来的仍是旧副本:

rbnx clean -f robonix_manifest.yaml --cache
rbnx build -f robonix_manifest.yaml

6. 手体模型

soma.yaml 描述唯一的身体部件 —— 灵巧手 —— 以 hand_base_link 为根,列出六个驱动轴以及服务它们的契约。该文件原样提供给 pilot 作为 LLM 的身体上下文。

urdf/linkerhand_o6_right.urdf 是独立的右手模型:去掉了整机模型里的机械臂、头部与底座连杆,并把 hand_base_link 提升为根。关节名与原语通过 hand/info 上报的轴名一致。远端关节是 mimic —— 六个驱动器,每个远端连杆机械地随其近端关节运动。厂商的 Python 与 ROS2 SDK 都没有提供 O6 的 URDF,所以这份是派生而非导入。

soma.yaml 里的 footprint 是手掌基座自身的静态凸包,不是可行驶底盘;soma 会校验 footprint 包住原点,而本部署没有底盘。

7. 仓库结构

robot-linkerbot-linker_hand_o6/
├── robonix_manifest.yaml   # 部署什么,用什么配置
├── soma.yaml               # 提供给 pilot 的手体模型
├── .env.example            # LLM 端点 + 可选的 CAN 提权密码
├── assets/robot.jpg        # catalog 预览图
└── urdf/
    ├── README.md                  # URDF 来源、关节树、坐标系约定
    ├── linkerhand_o6_right.urdf   # 独立右手 URDF,根 link = hand_base_link
    └── meshes/right_hand/*.STL    # URDF 引用的网格

rbnx-boot/(拉取的包与运行日志)已被 git 忽略。

8. 量纲

所有手部数值都按轴归一化到 [0, 1]:位置 0 = 张开,1 = 闭合;速度与力矩上限 0 = 最小,1 = 最大。O6 固件的 0–255 原始值 —— 以及其位置值反向的极性 —— 都在原语包内部完成换算。

9. 安全

首次运行前先固定好灵巧手;跳舞时五指会同时运动。
首次开合前用 set_joint_torque_limits 降低力矩上限,避免夹伤手指或损坏指节。
每段舞蹈结束时、出错时、以及关停时,手都会被命令到完全张开 —— 绝不会停在半握状态。
栈运行期间,手和物体请远离手指。

10. 常见问题排查

症状	可能原因	处理
init 阶段回读状态失败,手完全不应答	`hand_type` 取错 —— 右手是 CAN id `0x27`,左手 `0x28`	改 `robonix_manifest.yaml` 的 `hand_type`(§4.2)
原语起不来,报接口不存在	`can0` 没拉起	跑 §4.1 的 `ip link set`;用 `ip -br link show can0` 确认已 up
手动作抽搐、或指令时灵时不灵	总线上还有别的写入方(ROS/ROS2 SDK、动捕手套、厂商 GUI)	关掉其余控制器,一条 CAN 总线只留一个写入方
改了包仓代码但行为没变	起来的是 `rbnx-boot/cache/` 里的旧检出	跑 §5.2 的 `rbnx clean --cache` 再 build
pilot 尝试去抓取或搬运东西	`soma.yaml` 的 `cannot_do` 被改动或没生效	本部署没有机械臂和相机;确认 `cannot_do` 仍在

更深入排查看 rbnx-boot/logs/<name>.log —— 每个包的 stdout/stderr 都在那里。

11. 参考资料

URDF 关节树与坐标系约定:urdf/README.md
手部原语:https://github.com/syswonder/primitive-linkerbot-linker_hand_o6-hand-rbnx
手势技能:https://github.com/syswonder/skill-hand-gesture-rbnx
robonix 框架:https://github.com/syswonder/robonix

两个包各自的 README 写了其契约细节与故障模式。哪个包出问题,先看它自己的 README。

12. 许可

MulanPSL-2.0