https://github.com/zay002/arachne
Arachne：ROS2 mobile manipulation workspace for 松灵机器人（AgileX Scout 2.0）+ 遨博（Aubo i5）+ 易爪机器人 / 大寰机器人（Yizhua Robot / DH-Robotics）AG95 grippers, with unified URDF/Xacro, RViz/Gazebo simulation, real-robot control, Nintendo Switch teleop, and extensible VLA/WAM integration.
https://github.com/zay002/arachne
agilex gazebo-ros godot4 grippers manipulator-robotics robot-system robotic-arm robotics ros2-humble ros2-jazzy scout2
Last synced: 12 days ago
JSON representation
Arachne：ROS2 mobile manipulation workspace for 松灵机器人（AgileX Scout 2.0）+ 遨博（Aubo i5）+ 易爪机器人 / 大寰机器人（Yizhua Robot / DH-Robotics）AG95 grippers, with unified URDF/Xacro, RViz/Gazebo simulation, real-robot control, Nintendo Switch teleop, and extensible VLA/WAM integration.
- Host: GitHub
- URL: https://github.com/zay002/arachne
- Owner: zay002
- License: mit
- Created: 2026-05-24T10:28:50.000Z (24 days ago)
- Default Branch: main
- Last Pushed: 2026-06-02T13:58:43.000Z (15 days ago)
- Last Synced: 2026-06-02T15:18:47.698Z (15 days ago)
- Topics: agilex, gazebo-ros, godot4, grippers, manipulator-robotics, robot-system, robotic-arm, robotics, ros2-humble, ros2-jazzy, scout2
- Language: Python
- Homepage:
- Size: 31 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Arachne
[English](README.en.md) · [快速启动](#快速启动) · [真机接口](#真机接口) · [文档](#文档)
Arachne 是一个面向移动操作机器人的 ROS 2 workspace。默认机器人由 Scout 2.0 移动底盘、Aubo i5 机械臂和易爪机器人 MS42DC 二指柔性伺服电机夹爪组成；AG95 作为可切换夹爪模型保留。
项目目标是提供一套可复现的研发基线：统一机器人模型、RViz/Gazebo/Godot 演示、MoveIt2/Nav2/ros2_control 起步配置，以及面向真机的 ROS 接口。
## 特性
- 统一 URDF/Xacro：Scout 2.0、Aubo i5、MS42DC、AG95、传感器和安装坐标系位于同一 TF 树。
- 可切换夹爪：MS42DC 使用项目作者手动拆分的可动 CAD 部件；AG95 保留为开源对照模型。
- 仿真与展示：RViz 模型检查、Gazebo 手柄 demo、自主拾取验证，以及 Godot 高帧率展示前端。
- 控制骨架：MoveIt2、Nav2、ros2_control、sequence executor 和 VLA/WAM action chunk translator。
- 真机接口：Scout 2.0、MS42DC、Aubo i5 均通过 ROS 话题、launch 和安全检查脚本接入。
## 快速启动
支持 Ubuntu 24.04 + ROS 2 Jazzy，兼容 Ubuntu 22.04 + ROS 2 Humble。
```bash
git clone https://github.com/zay002/Arachne.git
cd Arachne
./scripts/setup_ubuntu.sh
./scripts/fetch_third_party.sh
source scripts/arachne_env.sh
./scripts/build_workspace.sh
./scripts/view_model.sh
```
仓库随附可直接运行的第三方最小集合：Aubo i5 必要模型、Scout ROS2、UGV SDK 源码、Aubo ROS2 driver、AG95 描述和 MS42DC ROS2 示例。大型资料如完整 Aubo 全系列模型、厂家视频/安装包、UGV 大 PDF、Godot 外部素材包仍由脚本或链接下载。`fetch_third_party.sh` 默认复用随仓库携带的内容并建立符号链接；如需重新拉取固定版本完整上游，可运行 `ARACHNE_REFRESH_THIRD_PARTY=true ./scripts/fetch_third_party.sh`。
`arachne_env.sh` 会把当前 shell 固定到 ROS 使用的系统 Python，例如 Ubuntu 24.04 + Jazzy 下的 `/usr/bin/python3.12`，避免 conda/pyenv 的 Python 3.13 抢走 ROS Python 模块。
`view_model.sh` 会启动默认 MS42DC 模型、底盘遥控 GUI、Aubo 关节滑条和夹爪 Open/Close 控制窗。
推荐始终通过 `./scripts/view_model.sh` 查看模型；脚本会自动加载 ROS 和 workspace 环境。若手动运行 `ros2 launch` 或直接打开 RViz，必须先执行：
```bash
source scripts/arachne_env.sh
source install/setup.bash
```
否则 RViz 的 `package://...` mesh 路径可能解析失败，表现为白模、部件堆叠或材质丢失。
## 常用入口
| 目标 | 命令 |
| --- | --- |
| 查看默认 MS42DC 模型 | `./scripts/view_model.sh` |
| 查看 AG95 模型 | `./scripts/use_gripper.sh ag95 view` |
| 检查 URDF 和基础接口 | `./scripts/check_workspace.sh` |
| Gazebo 手柄 demo | `./scripts/switch_demo.sh` |
| Gazebo 自主拾取验证 | `./scripts/gazebo_autopick_demo.sh` |
| Godot 展示前端 | `./scripts/godot_showcase.sh` |
| 真机环境检查 | `./scripts/check_real_hardware_env.sh` |
| 真机一键 bringup | `./scripts/real_bringup.sh` |
| 真机示教演示 | `./scripts/real_teach_demo.sh` |
| Aubo 只读连通探测 | `./scripts/real_aubo_probe.sh` |
| Aubo 启动状态确认 | `./scripts/real_aubo_prepare.sh` |
| Aubo 真机 driver 启动 | `ARACHNE_CONFIRM_AUBO_DRIVER=YES ./scripts/real_aubo_bringup.sh` |
| Aubo 阻塞远程启动 | `ARACHNE_CONFIRM_AUBO_REMOTE_START=YES ./scripts/real_aubo_remote_start.sh` |
| Aubo 小幅 Z 向测试 | `ARACHNE_CONFIRM_REAL_MOTION=YES ./scripts/real_aubo_z_test.sh` |
| 真机示教与回放面板 | `./scripts/teach_panel.sh` |
## 真机接口
Arachne 的真机层尽量复用官方或厂家 ROS 路线，并在本仓库内维护当前硬件需要的集成节点。
| 设备 | 默认接口 | 说明 |
| --- | --- | --- |
| Scout 2.0 | `scout_waveshare_serial_driver` | `/cmd_vel` 到 Scout v2 CAN 帧；Waveshare USB-CAN-A，CH340 串口，默认 `/dev/serial/by-id/usb-1a86_USB_Serial-if00-port0` |
| MS42DC | `ms42dc_direct_serial_driver` | `/arachne/gripper/command` 到 Type-C 串口帧；夹具控制板为 CH91xx/CH343 系列，当前实机按 CH9012 路线处理，推荐别名 `/dev/motor_serial` |
| Aubo i5 | `AuboRobot/aubo_ros2_driver` | TCP/IP + ros2_control，按机器人 IP 启动 |
准备真机相关 ROS 包：
```bash
./scripts/prepare_real_hardware_ros.sh
./scripts/real_aubo_probe.sh
./scripts/real_aubo_prepare.sh
```
Aubo 推荐优先在示教器/控制柜上完成“连接 -> 上电 -> 启动”。如果需要从 ROS 侧远程启动，只使用阻塞式脚本：它会先确认 controller active、读取当前关节角并发送 hold-position，再按“上电 -> Aubo `RobotManage.startup` 完整启动 -> Running 后稳定与保持校验”的顺序执行。脚本不会直接调用 `releaseRobotBrake`；任何保护状态、超时或 controller 异常都会退出。
远程启动需要两个终端：
```bash
# 终端 1：启动 driver，并允许上电前激活 controller
ARACHNE_CONFIRM_AUBO_DRIVER=YES ARACHNE_AUBO_ALLOW_PRESTART=YES ./scripts/real_aubo_bringup.sh
# 终端 2：执行阻塞式远程启动状态机
ARACHNE_CONFIRM_AUBO_REMOTE_START=YES AUBO_ROBOT_IP=192.168.127.128 ./scripts/real_aubo_remote_start.sh
```
日常真机启动优先使用自动入口。脚本会自动选择 Scout 和 MS42DC 的 `/dev/serial/by-id` 串口，检查 Aubo 是否处于 Running / Normal，然后启动完整 bringup：
```bash
./scripts/real_bringup.sh
```
WSL2 用户推荐使用 [hurry-porter](https://github.com/zay002/hurry-porter) 辅助 USB 透传、串口扫描和 Waveshare USB-CAN-A 诊断。`real_bringup.sh` 找不到串口时会先尝试自动 attach CH9102/CH340 设备；如果 Windows 侧还没有共享设备，再按脚本提示手动 attach。
```bash
hurry scan
hurry waveshare-can-a recv \
--port /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0 \
--can-bitrate 500000 \
--frame-type standard \
--duration 2
```
真机运动测试默认 dry-run。确认电源、急停和空间安全后再显式允许运动：
```bash
./scripts/real_hardware_acceptance_test.sh
./scripts/real_aubo_z_test.sh
ARACHNE_CONFIRM_REAL_MOTION=YES ./scripts/real_hardware_acceptance_test.sh
```
示教演示可直接一键启动：
```bash
./scripts/real_teach_demo.sh
```
它会启动真机 bringup，等待 `/odom`、`/joint_states`、Aubo trajectory action 和夹具状态可用后打开示教面板；关闭面板时会自动停止 bringup。面板可以手动控制底盘、Aubo 末端和 MS42DC，支持 Aubo Teach On/Off、RX/RY/RZ 腕部微调、底盘长按松开后自动记录相对移动段、等待步骤、单点更新和 waypoint 复用，并将记录保存到本地 `recordings/teach/` 后一键回放。
## 项目结构
| 路径 | 内容 |
| --- | --- |
| `src/arachne_description` | 统一机器人模型、RViz 配置、夹爪变体和传感器坐标系 |
| `src/arachne_demo` | Switch Pro 手柄、Gazebo 展厅、自主拾取验证 |
| `src/arachne_hardware` | 真机 bringup、Scout/MS42DC wrapper、安全状态和命令门控 |
| `src/arachne_control` | ros2_control 控制器命名、mock 控制器和硬件 profile |
| `src/arachne_moveit_config` | Aubo i5 + MS42DC/AG95 的 MoveIt2 起步配置 |
| `src/arachne_nav` | Scout Nav2 起步配置 |
| `src/arachne_operator` | 操作员面板、sequence executor、VLA/WAM action chunk translator |
| `godot/arachne_showcase` | Godot 4.x 第三人称展示前端 |
| `docs` | 建模、控制、硬件、标定和参考资料 |
## 文档
- [建模](docs/modeling.zh-CN.md)
- [控制](docs/control.zh-CN.md)
- [硬件](docs/hardware.zh-CN.md)
- [标定](docs/calibration.zh-CN.md)
- [参考资料](docs/references.zh-CN.md)
英文版本位于同名文档，例如 [docs/hardware.md](docs/hardware.md)。
## Roadmap
- 完成 Aubo i5 真机 TCP/IP 与 ros2_control 验证。
- 将 Scout、Aubo、MS42DC 的联合 bringup 固化为安全流程。
- 用 MoveIt2 和 ros2_control 替换 Gazebo 自主拾取验证中的轻量规划器。
- 基于真实里程计、定位和传感器继续完善 Nav2。
- 将 Godot 前端通过 ROS 2 bridge 连接到真实或仿真后端。
## License
本仓库代码使用 [MIT License](LICENSE)。第三方模型、CAD、SDK 和说明书遵循各自来源许可证；来源记录见 [third_party/README.md](third_party/README.md) 和 [docs/references.zh-CN.md](docs/references.zh-CN.md)。