reBotArm B601 DM / ROS 2 工程文件架构-拓冰建站

reBotArm B601 DM / ROS 2 工程文件架构（逐文件注释）

本文档按“运行依赖 → ROS 2 包 → 硬件驱动 → 运动学/MoveIt → 示例 → 上位机”的顺序说明工程。实际 ROS 2 工程位于当前工作区中的reBotArmController_ROS2-main/子目录；不要把上层工作区中的 Word、QA 和生成脚本当作机械臂运行时依赖。

1. 运行时总链路

CAN/串口/电机 ↓ reBotArm_control_py（第三方硬件 SDK） ↓ rebotarmcontroller/hardware_manager.py ↓ rebotarm_controller.py ├── /rebotarm/joint_states ├── /rebotarm/arm_status ├── ROS services ├── ROS actions └── low-level command topics ↓ MoveIt 2 / 视觉抓取 / 上位机

最重要的原则：hardware_manager.py是硬件安全边界；ROS、MoveIt、视觉程序都不应该绕过它直接操作电机。

2. 工作区根目录

这些文件位于工程父目录，主要是教程、方案、测试输出和文档生成工具，不参与colcon build。

文件/目录	作用
`reBotArmController_ROS2-main/`	真正的 ROS 2 源码工作区。
`garbage_sorting_dashboard/`	垃圾分拣上位机源码，独立于机械臂 ROS 2 包。
`build_*.py`	生成教程、方案或部署手册的 Python 脚本。
`create_rdkx5_ubuntu_guide.py`	生成 RDK X5 部署指南。
`qa/`	Word/HTML/PDF 渲染和视觉检查产物，不参与机器人运行。
`docx_render/`	文档渲染产生的页面图片和 PDF。
`outputs/`	视觉分拣脚本、配置和方案图片等输出文件。
`tools/`	文档提取、转换、联系图生成等辅助工具。
`*.docx`	学习教程、故障手册、RDK 方案和部署手册。
`*.zip`	已打包的上位机源码，不是 ROS 2 驱动依赖。

3. ROS 2 工作区根文件

目录：reBotArmController_ROS2-main/

文件	注释
`.gitignore`	Git 忽略规则，通常忽略`build/`、`install/`、`log/`等编译产物。
`README.md`	英文项目说明、编译和启动入口。
`README_zh.md`	中文项目说明，适合第一次部署。
`API_zh.md`	ROS 2 topic、service、action、消息类型和参数的接口文档。
`media/rebot_arm_b601.png`	README 使用的机械臂图片，不参与运行。
`src/`	ROS 2 源码包目录。

4.`rebotarm_msgs`：自定义ROS接口包

目录：src/rebotarm_msgs/

这个包只定义通信接口，不负责连接电机。修改.msg、.srv、.action后必须重新colcon build。

包文件

文件	注释
`package.xml`	声明 ROS 2 构建和运行依赖。
`CMakeLists.txt`	使用`rosidl_generate_interfaces`生成 Python/C++ 接口代码。

消息`msg/`

文件	注释
`ArmStatus.msg`	发布整机模式、使能状态、控制循环、状态机和错误码。
`JointMotorState.msg`	发布单个关节/夹爪的位置、速度、力矩和电机状态码。
`JointMitCmd.msg`	单关节或夹爪 MIT 控制命令：位置、速度、Kp、Kd、力矩。
`JointPosVelCmd.msg`	单关节或夹爪位置-速度控制命令。

服务`srv/`

文件	注释
`GripperCommand.srv`	开合夹爪并等待到位，包含位置、超时和反馈。
`MoveToPoseIK.srv`	给定末端 Pose，执行一次 IK，并返回解。
`SetGripper.srv`	直接设置夹爪目标位置。
`SetZero.srv`	设置单个关节或整机零点；必须谨慎使用。

动作`action/`

文件	注释
`MoveToPose.action`	末端位姿轨迹动作，支持反馈、取消和结果。

5.`rebotarmcontroller`：核心硬件控制包

目录：src/rebotarmcontroller/

这是整个机械臂的核心包，职责是：加载硬件配置、创建第三方 SDK 对象、管理控制模式、发布反馈、提供 service/action，并阻止互相冲突的命令。

包装文件

文件	注释
`package.xml`	声明`rclpy`、消息包、控制消息、几何消息等依赖。
`setup.py`	Python 包安装和 console script 入口。
`setup.cfg`	setuptools 安装配置。
`resource/rebotarmcontroller`	ROS 2 Python 包索引资源文件。
`rebotarmcontroller/__init__.py`	Python 包初始化。

核心Python文件

文件	作用
`rebotarm_controller.py`	ROS 2 Node 总入口。创建`HardwareManager`、发布器、服务、动作和底层命令订阅器。
`hardware_manager.py`	硬件安全边界。封装`RebotArm`、arm/gripper group、连接、使能、失能、归位、轨迹、IK、MIT、PosVel、重力补偿和状态机。
`hardware_config.py`	找到第三方 SDK、加载 SDK YAML，并把 ROS 选择的`model/channel`覆盖到最终硬件配置。
`conversions.py`	ROS`Pose`与 XYZ/RPY、旋转矩阵、四元数之间的转换。
`ros_publishers.py`	定时发布`/rebotarm/joint_states`、每关节状态、夹爪状态和锁存的`/rebotarm/arm_status`。
`ros_services.py`	注册 enable、disable、safe_home、set_zero、IK、夹爪和重力补偿等 service。
`ros_actions.py`	注册 MoveToPose、FollowJointTrajectory、GripperCommand action，并处理反馈、取消、超时。
`motor_passthrough.py`	订阅低层 MIT/PosVel topic，把指定关节的低层命令转给硬件，同时执行命令仲裁。

`rebotarmcontroller/examples/`

文件	注释
`move_to.py`	关节空间目标示例，输入六个关节角和持续时间。
`move_to_pose.py`	末端位姿目标示例，调用 MoveToPose 服务或动作。
`gripper_control.py`	交互式打开、闭合和退出夹爪示例。
`gravity_compensation.py`	启动和停止重力补偿的示例。
`__init__.py`	示例脚本目录初始化。

6.`rebotarm_bringup`：启动、配置和模型资源包

目录：src/rebotarm_bringup/

这个包负责把控制节点、机器人描述、RViz 和参数组合成可启动的系统。

包文件

文件	注释
`package.xml`	声明启动文件、描述文件和运行时依赖。
`setup.py`	安装 Python launch 文件、配置、描述和 RViz 资源。
`setup.cfg`	setuptools 配置。
`resource/rebotarm_bringup`	ROS 2 包索引资源。

配置`config/`

文件	注释
`rebotarm_hardware.yaml`	DM/RS 型号、通信通道、关节组、夹爪范围、控制模式、MIT 增益、重力补偿参数。
`driver_params.yaml`	ROS 控制节点参数示例，例如发布频率、命名空间、QoS相关设置。

DM B601 的关键配置通常包括：

default_model:dmchannel:/dev/ttyACM0groups:arm:joints:[joint1,joint2,joint3,joint4,joint5,joint6]gripper:joints:[gripper]

启动文件`launch/`

文件	注释
`driver.launch.py`	主要启动文件，只启动机械臂控制器。真实硬件测试优先使用它。
`bringup.launch.py`	更完整的启动入口，可同时启动机器人描述、状态发布器、控制器和可选 RViz。

机器人描述`description/urdf/`

文件	注释
`reBot-DevArm_fixend.urdf`	DM 机械臂主体和末端固定结构的 URDF。
`reBot_B601_DM_with_gripper.urdf`	B601 DM 机械臂加夹爪的完整 URDF，仿真和显示常用。
`00-arm-rs_asm-v3.urdf`	RS 版本机械臂的 URDF。

DM模型网格`description/meshes/`

文件	注释
`base_link.STL`	底座外观/碰撞网格。
`link1.STL`～`link6.STL`	六个机械臂连杆的网格。
`end_link.STL`	DM 末端连接件网格。

B601夹爪网格`description/meshes_b601_gripper/`

文件	注释
`base_link.STL`	夹爪安装底座。
`link1.STL`～`link6.STL`	夹爪内部联动结构网格。
`gripper_link.STL`	夹爪主体。
`gripper_left.STL`	左指。
`gripper_right.STL`	右指。

RS模型网格`description/meshes_rs/`

文件	注释
`base_link.STL`	RS底座。
`link1.STL`～`link6.STL`	RS六个连杆。
`motor_2_3.STL`、`motor_4.STL`、`motor_5.STL`、`motor_6.STL`、`motor_7.STL`	RS各电机外观。
`cnc2.STL`、`cnc3.STL`、`cnc4.STL`、`cnc5.STL`、`cnc7.STL`	RS加工件。
`gripper_end.STL`	RS末端连接件。
`gripper_left.STL`、`gripper_right.STL`	RS夹爪指。
`pla2_black.STL`、`pla2_green.STL`、`pla3_black.STL`、`pla3_green.STL`、`pla5_green.STL`、`pla7_green.STL`	RS塑料外壳。
`pla_left.STL`、`pla_right.STL`	RS夹爪塑料件。

RViz

文件	注释
`rviz/rebotarm.rviz`	机器人状态和TF可视化配置。

7.`rebotarm_moveit_config`：MoveIt 2配置包

目录：src/rebotarm_moveit_config/

这个包负责运动规划、IK、碰撞检测、规划组和轨迹控制器配置。它不直接实现电机通信。

包和元文件

文件	注释
`package.xml`	MoveIt、ros2_control、TF、Xacro等依赖。
`CMakeLists.txt`	安装配置、URDF/Xacro和MoveIt资源。
`.setup_assistant`	MoveIt Setup Assistant 生成的配置记录。

`config/`

文件	注释
`rebotarm.urdf.xacro`	DM版本机器人模型入口，通常引用bringup中的URDF/网格。
`rebotarm_rs.urdf.xacro`	RS版本模型入口。
`rebotarm.srdf`	DM的MoveIt planning group、末端执行器和默认状态。
`rebotarm_rs.srdf`	RS的SRDF配置。
`rebotarm.ros2_control.xacro`	DM的ros2_control虚拟/硬件控制接口。
`rebotarm_rs.ros2_control.xacro`	RS的ros2_control接口。
`kinematics.yaml`	MoveIt IK求解器配置。
`joint_limits.yaml`	MoveIt使用的关节速度、加速度和角度限制。
`initial_positions.yaml`	仿真控制器初始关节位置。
`ros2_controllers.yaml`	仿真或控制器管理器中的joint/gripper controller。
`moveit_controllers.yaml`	MoveIt轨迹执行器与ROS控制器的映射。
`moveit_hardware_controllers.yaml`	连接真实控制节点时使用的MoveIt控制器映射。
`ompl_planning.yaml`	OMPL规划器、采样和规划时间参数。

`launch/`

文件	注释
`demo.launch.py`	启动MoveIt仿真环境、move_group、RViz和虚拟控制器。
`hardware.launch.py`	在真实机械臂控制器已经启动后连接MoveIt。
`moveit_launch_common.py`	两个launch文件共用的参数、robot description和MoveIt构造逻辑。
`demo_view.rviz`	MoveIt仿真界面配置。
`moveit.rviz`	MoveIt规划界面配置。

8.`rebotarm_moveit_demos`：MoveIt示例包

目录：src/rebotarm_moveit_demos/

包文件

文件	注释
`package.xml`	MoveIt demo依赖。
`setup.py`	注册`draw_square`和`pick_place`等Python入口。
`setup.cfg`	setuptools配置。
`resource/rebotarm_moveit_demos`	ROS 2包索引资源。
`rebotarm_moveit_demos/__init__.py`	Python包初始化。

参数`config/`

文件	注释
`draw_square.yaml`	DM画矩形轨迹的起始点、矩形尺寸、TCP姿态和速度参数。
`draw_square_rs.yaml`	RS画矩形轨迹参数。
`pick_place.yaml`	DM固定物体抓取放置参数。
`pick_place_rs.yaml`	RS抓取放置参数。

启动和程序

文件	注释
`launch/draw_square.launch.py`	启动画矩形demo。
`launch/pick_place.launch.py`	启动固定物体pick-place demo。
`rebotarm_moveit_demos/demo_common.py`	两个demo共用的MoveIt连接、规划和执行辅助函数。
`rebotarm_moveit_demos/draw_square.py`	生成矩形四个角点并请求轨迹。
`rebotarm_moveit_demos/pick_place.py`	依次执行预抓取、抓取、抬升、放置和释放。

9. 垃圾分拣上位机

目录：garbage_sorting_dashboard/

它是独立的Python标准库服务，不是ROS 2控制器。默认提供HTTP、SSE、SQLite、CSV导出和可选ROS 2状态桥接。

文件	注释
`README.md`	上位机启动、配置、API和RDK部署说明。
`requirements.txt`	可选依赖说明；基础HTTP/SQLite功能主要使用Python标准库。
`config/dashboard.env.example`	RDK上的环境变量模板。
`dashboard/config.py`	环境变量和服务配置加载。
`dashboard/database.py`	SQLite建表、事件去重、统计、CSV导出和会话管理。
`dashboard/broker.py`	SSE客户端订阅和事件广播。
`dashboard/app.py`	HTTP API路由、事件写入、控制命令和静态文件响应。
`dashboard/server.py`	ThreadingHTTPServer启动入口。
`dashboard/client.py`	上位机客户端事件上报封装。
`dashboard/ros_bridge.py`	可选ROS 2桥接，读取机械臂健康状态和发布分拣控制命令。
`dashboard/__init__.py`	Python包初始化。
`static/index.html`	上位机页面结构。
`static/styles.css`	深色工业风页面样式和响应式布局。
`static/app.js`	SSE实时刷新、统计卡片、事件列表、控制按钮和CSV导出。
`examples/sort_waste_integration.py`	将视觉分拣脚本接入事件上报器的示例。
`examples/publish_demo_events.py`	不接真机时发布演示事件的脚本。
`scripts/run_dashboard.sh`	手动启动上位机服务。
`scripts/install_rdk.sh`	将服务安装到RDK X5的`/opt`、`/var/lib`、`/etc`和systemd。
`systemd/garbage-dashboard.service`	上位机开机自启动服务单元。
`tests/test_database.py`	数据库去重、会话、统计和重试逻辑测试。
`tests/test_http.py`	API、静态页面、SSE、健康状态和控制接口测试。

10. 启动时各文件如何协作

真实硬件

driver.launch.py ↓ reBotArmController ↓ HardwareManager.__init__() ↓ hardware_config.py 找到 SDK 和 YAML ↓ RebotArm.connect() ↓ JointStatePublisher 定时发布反馈 ArmServices 提供 service ArmActions 提供 action MotorPassthrough 接收低层命令

典型命令：

source/opt/ros/humble/setup.bashsource~/rebotarm_ros2/install/setup.bash ros2 launch rebotarm_bringup driver.launch.py model:=dm channel:=slcan0

MoveIt仿真

demo.launch.py ↓ Xacro + URDF + SRDF ↓ robot_state_publisher ↓ move_group + OMPL + RViz ↓ 虚拟 ros2_control controller

视觉抓取

相机帧 → YOLO/颜色检测 → 深度反投影 → 相机坐标 → 手眼变换 → base_link目标位姿 → IK/轨迹 → HardwareManager

11. 建议学习顺序

先读rebotarm_msgs，理解所有ROS接口。
再读hardware_config.py，理解配置如何选择 DM/RS。
重点读hardware_manager.py，理解连接、状态机、模式切换和安全归位。
读ros_publishers.py，确认/joint_states和/arm_status的来源。
读ros_services.py与ros_actions.py，理解上层如何下发命令。
用rebotarm_bringup先运行RViz/MoveIt仿真。
再做真实硬件只读反馈。
最后才测试低速运动、夹爪、视觉和分拣。

12. 不应直接修改的文件

以下文件修改前应先备份：

hardware_manager.py
rebotarm_hardware.yaml
rebotarm.urdf.xacro
joint_limits.yaml
kinematics.yaml
ros2_controllers.yaml

尤其不要为了“让IK成功”随意增大关节限制，也不要为了“让夹爪归位”直接修改零点。应先确认机械零点、坐标系、URDF轴方向和真实硬件反馈。

13. 编译和验证入口

cd~/rebotarm_ros2source/opt/ros/humble/setup.bash colcon build --symlink-installsourceinstall/setup.bash ros2 pkg executables rebotarmcontroller ros2 topic list|greprebotarm ros2servicelist|greprebotarm

真实硬件与仿真必须分开验证。任何真实运动测试前，都应先完成RViz模型、关节限制、TCP坐标和急停检查。