primitive-linkerbot-linker_hand_o6-hand-rbnx

English

robonix.primitive.linkerbot.linker_hand_o6.hand —— 面向 LinkerBot LinkerHand O6 五指灵巧手 (六轴)的 Robonix 原语。经 SocketCAN 直接驱动灵巧手,不依赖 ROS。

LinkerHand 的 CAN 后端已 vendored 进本包(linkerhand_o6/vendor/,来自官方 linkerhand-python-sdk)。 该 SDK 没有发布到 PyPI,vendoring 让本包自洽,rbnx build 无需联网拉取。复制了 哪些文件、改了什么、如何同步上游,见 linkerhand_o6/vendor/README.md。

能力契约

契约	传输	作用
robonix/primitive/hand/driver	gRPC	生命周期(CMD_INIT / ACTIVATE / DEACTIVATE / SHUTDOWN)
robonix/primitive/hand/info	gRPC	每个控制轴所属手指与类型,供消费者映射手指
robonix/primitive/hand/move_joint	gRPC	轴级位置控制
robonix/primitive/hand/set_joint_speed_limits	gRPC	每轴速度上限
robonix/primitive/hand/set_joint_torque_limits	gRPC	每轴力矩上限
robonix/primitive/hand/get_state	gRPC	读取当前各轴位置

手指级契约(move_finger / set_finger_*)与 state_joint / state_finger 流 (topic_out,需要本部署未运行的 ROS 后端)目前暂未支持。消费者从 info 读取 轴与手指的映射,再驱动 move_joint。

轴布局

六个轴,按固件顺序排列(也就是 info 的返回顺序,以及任何 6 维向量的解释顺序):

#	名称	手指	类型
0	thumb_cmc_pitch	拇指	bend(屈曲)
1	thumb_cmc_yaw	拇指	oppose(对掌)
2	index_mcp_pitch	食指	bend
3	middle_mcp_pitch	中指	bend
4	ring_mcp_pitch	无名指	bend
5	pinky_mcp_pitch	小指	bend

量纲

按 robonix 手部契约,所有跨 gRPC 边界的数值都归一化到 [0, 1]:

• 位置 —— 0 = 张开(伸直),1 = 闭合(屈曲);thumb_cmc_yaw 的 0 = 中立, 1 = 完全对掌。
• 速度 / 力矩上限 —— 0 = 最小,1 = 最大。

O6 固件本身用每轴 0–255 的原始值,而且位置的极性是反的(255 = 完全张开)。 换算只发生在 linkerhand_o6/hand.py 一处,并已对照上游 SDK 自带的预设姿态校验 (其”张开”姿态为全 255)。

配置

字段、单位与默认值见 config.spec。要点:

• hand_type(right | left,默认 right)—— 决定灵巧手的 CAN 仲裁 ID (右手 0x27,左手 0x28)。取错则灵巧手不会应答,init 会在回读状态时失败。
• can_iface(默认 can0)—— 灵巧手接入的 SocketCAN 接口。
• baudrate(默认 1000000)—— CAN 波特率;O6 固件工作在 1 Mbps。

每个字段都可回退到对应的 O6_HAND_* 环境变量。

依赖与权限

• Python 3.8+,需 python-can、numpy 与 robonix_api。

• CAN 权限。原语在 init 时执行 ip link set … 拉起接口。要么事先拉起 ——

  sudo ip link set can0 up type can bitrate 1000000

  —— 要么导出 PREFLIGHT_SUDO_PASS 让内部的 sudo -S 生效。推荐事先拉起:这样 本包完全不需要提权。

  注意与上游 SDK 不同,本包不会从提交进仓的 yaml 文件里读取 sudo 密码。

• scripts/start.sh 默认使用 $HOME/miniconda3/envs/bb_d1_robonix/bin/python3, 可用 LINKERHAND_O6_PYTHON 覆盖。

构建与运行

bash scripts/build.sh      # rbnx codegen,生成 gRPC stub
bash scripts/start.sh      # 或由 rbnx boot 从部署清单启动
rbnx caps -v | grep hand   # 确认 6 个能力已注册且 provider 处于 ACTIVE

关停由 Driver 的 CMD_SHUTDOWN 处理(on_shutdown 张开灵巧手并释放 CAN 句柄), 除此之外没有额外清理,因此不提供 scripts/stop.sh。关停时有意保持 CAN 接口 处于 up —— 总线上可能还挂着别的设备。

安全

• 先做只读检查(info / get_state),再下发 move_joint。
• 首次开合前用 set_joint_torque_limits 降低上限,避免夹伤手指或损坏指节。
• 启动本原语前,关掉其他一切控制器(LinkerHand 的 ROS/ROS2 SDK、动捕手套、厂商 GUI)—— 同一条 CAN 总线上两个写入方会互相抢手。
• Provider 在输入超时、进程退出或 CMD_SHUTDOWN 时停止硬件输出。

目录结构

package_manifest.yaml   config.spec   README.md   README_CN.md
scripts/{build.sh, start.sh}
linkerhand_o6/
  __init__.py   main.py            # robonix 契约层
  hand.py                          # 归一化 [0,1] 封装
  vendor/                          # vendored LinkerHand SDK —— 见其 README
    linker_hand_o6_can.py  color_msg.py  can_iface.py  UPSTREAM_COMMIT

许可

MulanPSL-2.0。vendored 文件保留其上游许可 —— 见 linkerhand_o6/vendor/README.md。