Arachne 是一个面向深度强化学习联合控制的移动操作机器人 ROS 2 workspace。默认硬件由 Scout 2.0 移动底盘、Aubo i5 机械臂、MS42DC 二指柔性伺服电机夹爪、Gemini335 RGB-D 相机、镭神智能 C16 雷达、车头吊篮和后置传感器架组成；AG95 作为可切换夹爪模型保留。
项目最终目标是形成一台能在真实场景中执行精密装配、测量和移动操作任务的联合控制小车：底盘、机械臂、夹具和视觉/雷达传感器共享状态表示，在安全约束内由传统控制、示教数据、视觉感知和深度强化学习策略逐步融合。当前 jetson 路线优先打牢真机流式控制、感知数据采集、可视化示教、数字孪生和边缘推理链路；早期任务线包括垃圾识别拾取入篮，以及充电枪识别、对准、拔出和插入。
- 统一数字孪生：Scout 2.0、Aubo i5、MS42DC、AG95、Gemini335、镭神智能 C16、后置架和车头吊篮位于同一 TF/URDF 树。
- 真机流式控制：底盘长按控制、Aubo SDK 速度控制、MS42DC 串口控制、Aubo 远程上电/启动和载荷配置均固化为脚本化流程。
- 感知与边缘推理：Gemini335 RGB-D 采集、镭神智能 C16 环境感知、YOLO26/TensorRT 工作区、实时标注窗口和 INT8 校准目录已独立组织。
- 示教与数据闭环：窗口化示教面板支持 home/install 位姿、本地配置、长按控制、示教记录和回放，为后续 imitation/RL 数据采集服务。
- 仿真与展示：RViz 模型检查、Gazebo 验证环境、Godot 高帧率展示前端，以及后续强化学习仿真接口。
- 控制骨架：MoveIt2、Nav2、ros2_control、sequence executor、VLA/WAM action chunk translator 和未来 DRL policy 节点共存。
支持 Ubuntu 24.04 + ROS 2 Jazzy，兼容 Ubuntu 22.04 + ROS 2 Humble。
git clone https://github.com/zay002/Arachne.git
cd Arachne
./scripts/build/setup_ubuntu.sh
./scripts/hardware/fetch_third_party.sh
source scripts/env/arachne_env.sh
./scripts/build/build_workspace.sh
./scripts/model/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/hardware/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/model/view_model.sh 查看模型；脚本会自动加载 ROS 和 workspace 环境。若手动运行 ros2 launch 或直接打开 RViz，必须先执行：
source scripts/env/arachne_env.sh
source install/setup.bash否则 RViz 的 package://... mesh 路径可能解析失败，表现为白模、部件堆叠或材质丢失。
日常开发按“模型/仿真先验证，真机从施教器进入”的顺序走：
./scripts/model/view_model.sh检查 URDF/TF/mesh 是否正常。./scripts/sim/urban_trash_sorting_demo.sh在 RViz 里复现道路垃圾巡检、识别、点云、抓取和投篮流程。./scripts/hardware/real_grasp_console.sh --yes --quick打开真机施教器总控。- 在施教器里用
Visual Grasp做单次视觉抓取；用Road Start做道路垃圾巡检分拣，测试中可随时点Road Pause暂停，点Return按已完成底盘段反向返航。
真机道路任务复用同一套 grasp_server：空闲时 YOLO-SEG 持续发布 /arachne/perception/taco_instances，检测到带 3D 位姿的可达目标后 road_cleanup_task_server 停车并调用 /arachne/grasp_task/start。当前默认只接受 base_link 下 x=0.25~1.03 m、水平半径 <=1.03 m、|y|<=0.60 m、z>=-0.18 m、深度不超过 0.85 m 的候选；2D-only 或过远目标只记录为 ignored，不触发机械臂。这个半径来自实机手动摆到最远抓取位姿后的 FK 标定，记录在 config/real_road_demo_grasp.yaml。施教器默认给 road demo 使用快速抓取 profile：本地 IK、只保留 grasp,basket_over 关键点、低碰撞采样、6 秒本地规划硬时限、单次抓取尝试和 25 秒 road 侧超时，避免完整调试规划拖慢道路演示。道路巡检默认按仿真 box_entry 路径：入口 0.3 m 后进入 1.0 m x 1.2 m 矩形环绕，活动范围不再是旧版 2 m 直线往返。底盘转弯由 grasp server 的 replay_segments 执行，默认 yaw 容差 0.5 deg、角速度 0.18 rad/s，优先保证 90 度转角准确。当前默认权重是 yolo_workspace/weights/yolo26n_seg_taco_best.pt，缺失时不会自动下载官方 YOLO 权重。
| 目标 | 命令 |
|---|---|
| 查看默认 MS42DC 模型 | ./scripts/model/view_model.sh |
| 查看 AG95 模型 | ./scripts/model/use_gripper.sh ag95 view |
| 检查 URDF 和基础接口 | ./scripts/build/check_workspace.sh |
| Gazebo 手柄 demo | ./scripts/sim/switch_demo.sh |
| Gazebo 自主拾取验证 | ./scripts/sim/gazebo_autopick_demo.sh |
| Godot 展示前端 | ./scripts/godot/godot_showcase.sh |
| 道路垃圾分拣 RViz demo | ./scripts/sim/urban_trash_sorting_demo.sh |
| Gemini335 YOLO 实时标注 | ./scripts/vision/gemini_yolo_live.sh |
| C16 雷达驱动 | ros2 launch lslidar_driver lslidar_cx_launch.py |
| C16 + 整车融合 RViz | rviz2 -d src/arachne_description/rviz/arachne_lidar_fusion.rviz |
| Trash 分割抓取入篮预览 | ./scripts/vision/grasp_preview.sh |
| 真机姿态同步抓取预览 | ./scripts/vision/grasp_preview_real_sync.sh |
| 真机同步并执行抓取 | ARACHNE_CONFIRM_GRASP_EXECUTE_REAL=YES ./scripts/vision/grasp_preview_real_sync.sh --execute-real |
| 真机抓取/施教总控 console（本机规划/调试） | ./scripts/hardware/real_grasp_console.sh --yes --quick |
| 真机抓取/施教总控 console（远端规划） | ./scripts/hardware/real_grasp_console_remote.sh |
| 抓取任务服务器（底层调试） | ./scripts/vision/grasp_task_server.sh |
| 道路巡检任务服务器（底层调试） | ./scripts/vision/road_cleanup_task_server.sh |
| Road cleanup mock 回归 | python3 scripts/vision/mock_road_cleanup_task_test.py |
| AprilTag 手眼交互标定 | ./scripts/vision/apriltag_hand_eye_interactive.sh |
| 服务器 MoveIt 规划栈 | ./scripts/remote/remote_moveit_planner_stack.sh restart |
| Agent Bridge | ./scripts/agent/agent_bridge.sh |
| 真机环境检查 | ./scripts/hardware/check_real_hardware_env.sh |
| 真机一键 bringup | ./scripts/hardware/real_bringup.sh |
| 真机示教演示 | ./scripts/hardware/real_teach_demo.sh |
| Aubo 只读连通探测 | ./scripts/hardware/real_aubo_probe.sh |
| Aubo 启动状态确认 | ./scripts/hardware/real_aubo_prepare.sh |
| Aubo 真机 driver 启动 | ARACHNE_CONFIRM_AUBO_DRIVER=YES ./scripts/hardware/real_aubo_bringup.sh |
| Aubo 阻塞远程启动 | ARACHNE_CONFIRM_AUBO_REMOTE_START=YES ./scripts/hardware/real_aubo_remote_start.sh |
| Aubo 小幅 Z 向测试 | ARACHNE_CONFIRM_REAL_MOTION=YES ./scripts/hardware/real_aubo_z_test.sh |
| 真机示教与回放面板 | ./scripts/operator/teach_panel.sh |
Arachne 的真机层尽量复用官方或厂家 ROS 路线，并在本仓库内维护当前硬件需要的集成节点。
Arachne 默认遵循 ROS 车体坐标约定：base_link 的 +X 指向小车前方，+Y 指向小车左侧，+Z 向上。odom -> base_link 来自底盘里程计，map -> odom 属于后续定位系统，不写进 URDF。机械臂链路挂在车体上：base_link -> aubo_base_link -> ... -> aubo_wrist3_Link -> tool0；实际末端支架挂在 aubo_wrist3_Link 下方，链路为 aubo_wrist3_Link -> ee_camera_support_link -> ms42dc_base_link -> grasp_frame，相机链路为 ee_camera_support_link -> ee_camera_link。其中 aubo_base_link 是 Aubo 底座坐标，tool0 是法兰中心，grasp_frame 是夹具中心/抓取 TCP。RGB-D ROI 点先在相机深度 frame 中按深度投影得到，再经 TF 转成 base_link 下的抓取目标。抓取预览的补偿量 ARACHNE_GRASP_BASE_OFFSET 是 base_link 下的 (x,y,z) 米制偏置，默认 0,0,0；长期偏差应通过 scripts/vision/apriltag_hand_eye_calibration.sh 求真实手眼外参。真机抓取执行默认在投放开爪后回到 scripts/env/arachne_real_defaults.sh 中的 home 姿态。
| 设备 | 默认接口 | 说明 |
|---|---|---|
| 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 启动 |
| Gemini335 | arachne_sensors |
末端 RGB-D 相机，用于目标分割、mask/depth ROI、抓取位姿估计和示教观测 |
| 镭神智能 C16 | third_party/Lslidar_ROS2_driver_C16_V4 + arachne_description |
官方 C16_V4 驱动，UDP 2368/2369，默认设备 IP 192.168.1.200；点云发布到 /lslidar_point_cloud，frame 为 lidar_link，融合 RViz 使用 lidar_link 作为固定坐标，当前 distance_unit=0.4 |
准备真机相关 ROS 包：
./scripts/hardware/prepare_real_hardware_ros.sh
./scripts/hardware/real_aubo_probe.sh
./scripts/hardware/real_aubo_prepare.shAubo 推荐优先在示教器/控制柜上完成“连接 -> 上电 -> 启动”。如果需要从 ROS 侧远程启动，只使用阻塞式脚本：它会先确认 controller active、读取当前关节角并发送 hold-position，再按“上电 -> Aubo RobotManage.startup 完整启动 -> Running 后稳定与保持校验”的顺序执行。脚本不会直接调用 releaseRobotBrake；任何保护状态、超时或 controller 异常都会退出。
远程启动需要两个终端：
# 终端 1：启动 driver，并允许上电前激活 controller
ARACHNE_CONFIRM_AUBO_DRIVER=YES ARACHNE_AUBO_ALLOW_PRESTART=YES ./scripts/hardware/real_aubo_bringup.sh
# 终端 2：执行阻塞式远程启动状态机
ARACHNE_CONFIRM_AUBO_REMOTE_START=YES AUBO_ROBOT_IP=192.168.127.128 ./scripts/hardware/real_aubo_remote_start.sh日常真机启动优先使用施教器总控。它会先打开施教器和 RViz，不要求 Aubo 已经 Running；Aubo 上电/启动、Gemini 相机、2D raw 画面、Localization/Nav 和 grasp server 都可以在施教器里开关。视觉抓取优先点 Visual Grasp，它会自动启动 Camera、2D raw view 和 grasp server，并等待 preflight 通过后再开始任务；默认会按“娃娃机式垂直逼近”抓取，夹爪反馈判断为空抓时会重新拍摄并最多重试 3 次。Grasp Start 只作为底层调试入口。console 默认彩色流为 320x240、深度为 640x480，优先保证远程观察流畅。Gemini335 彩色流按 YUYV 读取，避免旧版 v4l2 配置输出污染导致紫绿偏色；当前 camera_color_optical_frame 和 camera_depth_optical_frame 挂在模型里的 ee_camera_link 下，避免 RViz 点云和相机模型分离。tool0 是法兰中心，不是相机原点。没有新鲜 /joint_states 时，施教器可视化节点会只读轮询 Aubo SDK 当前关节，避免 TF 回落到默认机械臂姿态。
已完成的教室地图保存在 src/arachne_nav/maps/road_lab_apriltag.yaml。AprilTag/H12 仅用于一次性建图初始朝向和手眼标定，不属于正常 road_clean 启动流程；后续默认通过已有地图和定位链路同步 RViz 位姿。为降低 Jetson 负载，真机施教器正常启动时不自动打开 topdown 导航 RViz；需要定位/Nav 时再从面板或脚本显式启动。Localization/Nav 会启动 C16 点云转 /scan、AMCL/Nav2 和定位相关节点：
./scripts/hardware/real_grasp_console.sh --yes --quick如果需要服务器上的 MoveIt 2/OMPL 规划，用同一个施教器总控的远端包装入口：
./scripts/hardware/real_grasp_console_remote.sh底层 real_bringup.sh、grasp_task_server.sh 仍保留用于单独调试，不作为日常主入口。
WSL2 用户推荐使用 hurry-porter 辅助 USB 透传、串口扫描和 Waveshare USB-CAN-A 诊断。real_bringup.sh 找不到串口时会先尝试自动 attach CH9102/CH340 设备；如果 Windows 侧还没有共享设备，再按脚本提示手动 attach。
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。确认电源、急停和空间安全后再显式允许运动：
./scripts/hardware/real_hardware_acceptance_test.sh
./scripts/hardware/real_aubo_z_test.sh
ARACHNE_CONFIRM_REAL_MOTION=YES ./scripts/hardware/real_hardware_acceptance_test.sh旧版示教演示仍保留用于回归，但日常请优先使用 real_grasp_console.sh：
./scripts/hardware/real_teach_demo.sh它会启动真机 bringup，等待 /odom、/joint_states、Aubo trajectory action 和夹具状态可用后打开示教面板；不适合作为当前抓取/SLAM/相机联调主入口。
| 路径 | 内容 |
|---|---|
src/arachne_description |
统一机器人模型、RViz 配置、夹爪变体和传感器坐标系 |
src/arachne_sensors |
Gemini335 RGB-D 相机节点和传感器 launch |
third_party/Lslidar_ROS2_driver_C16_V4 |
镭神官方 C16_V4 ROS2 驱动，按 lidar_link、/lslidar_point_cloud、distance_unit=0.4 接入 |
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 |
操作员面板、grasp task server、sequence executor、VLA/WAM action chunk translator |
src/arachne_agent_bridge |
外部 Agent 的安全工具白名单、示教式控制桥和状态快照 |
scripts/env / scripts/build |
ROS 环境和 colcon 构建入口 |
scripts/hardware / scripts/operator |
真机 bringup、验收、Aubo 辅助脚本和示教入口 |
scripts/vision |
Gemini335、YOLO26 segmentation、TensorRT、INT8 校准和实时分割入口 |
scripts/model / scripts/sim / scripts/godot |
模型检查、仿真演示和 Godot 展示脚本 |
yolo_workspace |
YOLO 专用 venv、权重、engine、数据集和校准图片目录 |
godot/arachne_showcase |
Godot 4.x 第三人称展示前端 |
docs |
建模、控制、硬件、标定和参考资料 |
scripts/ 根目录不再放置旧式兼容脚本；请直接使用分类路径，例如 ./scripts/hardware/real_grasp_console.sh --yes --quick 和 source scripts/env/arachne_env.sh。
英文版本位于同名文档，例如 docs/hardware.md。
- 真机可靠性层：继续稳定 Scout、Aubo、MS42DC、Gemini335 和镭神智能 C16 的一键 bringup、远程上电、载荷配置、流式速度控制和安全停止。
- 感知与任务层：采集 Gemini335 RGB-D 与 C16 雷达数据，微调 YOLO26 垃圾/工件/充电枪分割模型，建立 INT8 TensorRT、mask/depth ROI 定位、抓取任务服务器和本地数据集闭环。
- 静态操作任务：在底盘静止时并行推进两条任务线：垃圾识别、抓取、放入车头吊篮；充电枪识别、精密对准、拔出和插入。随后扩展到工件识别、测量点定位和简单装配位姿生成。
- 移动操作任务：将底盘定位、机械臂可达性、车体姿态、视觉观测和 C16 环境信息统一到任务状态，做移动后停车、观察、抓取、充电枪拔插和测量的闭环流程。
- 深度强化学习联合控制：在仿真和真实示教数据上训练底盘-机械臂-夹具联合策略，优先覆盖精密对位、充电枪拔插、装配和测量任务，再逐步迁移到真机。
- 评测与安全：建立任务成功率、轨迹平滑度、定位误差、接触力/抖动、安全区违规和恢复策略等指标，形成可重复验收流程。
本仓库代码使用 MIT License。第三方模型、CAD、SDK 和说明书遵循各自来源许可证；来源记录见 third_party/README.md 和 docs/references.zh-CN.md。