robonix.robot.qmzs.arm7aix
robot
v0.1.0
qmzs ARM7AIX 七轴机械臂(Damiao 电机 + U2CAN 串口)+ LinkerHand O6 灵巧手 + Orbbec Gemini 336L RGB-D 相机的整机部署:关节/TCP 运动、灵巧手姿态、VLM 辅助抓取放置。
robot-qmzs-arm7aix
qmzs/ARM7AIX 整机部署仓库(Robonix 机器人部署):固定基座七轴机械臂 + LinkerHand O6 灵巧手 + Orbbec Gemini 336L RGB-D 相机。 按 Robonix 规范,本仓库只做组装:原语、服务、技能各自独立成包,这里只保存本体专属的清单、URDF、配置与启动脚本。
- 目录条目:
robonix.robot.qmzs.arm7aix(https://packages.robonix.ai/robots/) - 清单入口:
robonix_manifest.yaml(rbnx boot的入口) - 本体描述:
soma.yaml
硬件与平台
| 项 | 型号 / 规格 |
|---|---|
| 机械臂 | ARM7AIX 七轴,Damiao 电机,U2CAN 串口适配器(/dev/ttyACM0) |
| 末端执行器 | LinkerHand O6 左手(六轴五指),XCAN-USB → SocketCAN can2,1 Mbps |
| 相机 | Orbbec Gemini 336L(固定安装,640×480@15 MJPG,与手眼标定分辨率一致) |
| 计算平台 | Jetson Orin NX(aarch64),Ubuntu 22.04 |
| 软件 | ROS 2 Humble、rmw_zenoh_cpp、Robonix CLI(rbnx) |
支持矩阵
| 项目 | 状态 | 验证日期 | 说明 |
|---|---|---|---|
构建(./build.sh) |
已验证 | 2026-11-05 | 全部包构建通过 |
| 单元测试 | 已验证 | 2026-11-05 | 9 项通过 |
| 整机 boot(8 个包全部拉起) | 已验证 | 2026-11-05 | atlas/soma/executor/pilot/liaison + 4 原语 + 2 服务 + 2 技能,日志见 logs/rbnx.log |
rbnx chat 工具调用 |
已验证 | 2026-11-05 | get_state / snapshot / detect_object / pick 实机可用 |
真机抓取(qmzs_grasp pick) |
已验证 | 2026-11-05 | 固定相机 + 桌面标定面抓绿色方块成功(23 s 录像留存) |
home 复位 |
已验证 | 2026-11-05 | 未配置 home_joints 时 Robonix 自动解析为零点位姿(初始状态) |
| place / release | 未验证 | — | O6 手部为开环控制,现场低速试跑 |
详细证据见 docs/validation.md。
仓库结构
robonix_manifest.yaml # 整机清单:catalog 元数据 / system / primitive / service / skill
soma.yaml # 本体描述:arm + hand + camera 三个部件与对外能力
urdf/ # 唯一完整 URDF 与网格(arm7aix.urdf + meshes/)
config/ # 本体专属配置(目前只有手眼标定产物目录,运行时生成、不入库)
services/ # 两个 MCP 服务:arm7aix_control / linker_hand_control(随本仓库发布)
assets/ # 目录页展示图(可选;promo/01.jpg 1600×1000)
docs/ # 标定说明、验收记录
build.sh start.sh setup.sh ros2_env.sh # 便捷入口
.env.example # VLM 凭据模板(.env 不入库)
LICENSE # MulanPSL-2.0
包与依赖
| 组件 | 来源 | 角色 |
|---|---|---|
robot_description |
https://github.com/syswonder/primitive-robot-description-rbnx | 机器人描述原语 |
arm7aix_controller |
https://github.com/syswonder/primitive-qmzs-arm7aix-rbnx | 七轴臂原语(ROS 2 话题:joint_states/end_pose/joint_command/pos_command/enable/disable) |
o6_hand |
https://github.com/syswonder/primitive-linkerbot-linker_hand_o6-hand-rbnx | O6 灵巧手原语(CAN 直连,hand/* gRPC 契约) |
orbbec_camera |
https://github.com/syswonder/primitive-orbbec-camera-rbnx | Gemini 336L RGB-D 原语(camera/*) |
arm7aix_control |
本仓库 services/arm7aix_control |
MCP 服务:move_joint / move_pose / enable_joints / disable_joints / get_state |
linker_hand_control |
本仓库 services/linker_hand_control |
MCP 服务:手部 fist / open 预设 |
hand_gesture |
https://github.com/syswonder/skill-hand-gesture-rbnx | 技能:手势动画 |
qmzs_grasp |
https://github.com/syswonder/skill-qmzs-grasp-rbnx(v0.1.3) |
技能:抓取/放置/复位、像素→基座定位、VLM 目标检测 |
两个服务随本仓库发布(清单里用 path: 引用);原语与技能用 url: + branch 引用,换版本只改清单。
环境要求
- Ubuntu 22.04 / aarch64(x86 亦可,需自备 CAN 与串口适配器)
- ROS 2 Humble(含
rmw_zenoh_cpp) - Robonix CLI:完成
rbnx setup /path/to/robonix,并把rbnx放进 PATH - Python 3.10+(用系统 Python 建 venv,
--system-site-packages复用 rclpy)
安装
git clone https://github.com/syswonder/robot-qmzs-arm7aix
cd robot-qmzs-arm7aix
./setup.sh # 建 .venv、装 requirements、检查 ROS 2 与 Robonix
cp .env.example .env # 填 VLM_BASE_URL / VLM_API_KEY / VLM_MODEL(可留空)
sudo usermod -aG dialout "$USER" # 串口权限(重新登录生效)
拉起 CAN(每次上电后执行,接口名与清单 can_iface 保持一致):
sudo ip link set can2 type can bitrate 1000000
sudo ip link set can2 up
ip -details link show can2
构建
./build.sh
首次会 clone 原语/技能到 rbnx-boot/cache/,并 colcon 编译 vendored OrbbecSDK_ROS2,耗时较长(一次即可)。
构建失败常见原因:rbnx 不在 PATH、ROS 2 未 source、网络无法访问 GitHub。
手眼标定(必做,产物不入库)
抓取技能需要 config/handeye/calibration.json(桌面单应:去畸变像素 → base_link XY)与
config/handeye/grasp_orientation.json(目标法兰 Z + 四元数)。这两份文件每台机器现场生成,
不随仓库发布(config/handeye/*.json、*.npy 已被 .gitignore 忽略)。
- 用 handeye-calibration 完成相机内参与桌面标定,分辨率必须是 640×480@15 MJPG(与清单里的相机配置一致);
- 导出
calibration.json、image_to_robot_xy.npy、grasp_orientation.json,拷入config/handeye/; - 未标定时:
detect_object/snapshot/calibration_status可用,pixel_to_pose、pick会报错。
启动
./start.sh
脚本会加载 .env、source ROS 2、预检串口与 CAN、必要时拉起 rmw_zenohd,然后 rbnx boot。
三项设备都只能有一个进程持有(U2CAN 串口、CAN 接口、Orbbec 相机):先停掉手眼标定网页、厂商 GUI、
其他相机驱动,再 boot。确认安全时可 SKIP_DEVICE_PREFLIGHT=1 ./start.sh 跳过占用检查。
验收
rbnx chat # 另开终端(与 boot 同一环境)
建议顺序:
get_state读关节状态(确认七轴有反馈,不运动);snapshot+detect_object确认相机画面与检测框(qmzs_grasp默认dry_run: true,只算不发);- 核对
pixel_to_pose的 XY 与标注图,再把清单里qmzs_grasp.config.dry_run改成false重 boot; - 真机抓放:
pick/place/release/home,从空载、低速开始。
记录验收证据(日志、截图、提交号)到 docs/validation.md。
已知限制
- 固定基座,无移动底盘;抓取 Z 依赖标定高度,只适用于标定平面附近。
- 灵巧手是六轴结构,Soma 不提供开合聚合快照(读
hand/get_state)。 - 不通过 Robonix 暴露 MIT 力矩模式。
qmzs_grasp的grab需要grasp_pose(默认留空,按现场补);home不需要配置:未填home_joints时 Robonix 自动解析为零点位姿(初始状态)。
许可与维护
- 许可:MulanPSL-2.0(见
LICENSE)。 - 维护者:
Joker.Yun <2353493891@qq.com>。 - 原语/技能的代码问题请提到各自仓库;本机的本体参数、清单与启动脚本问题提到本仓库。
