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 | ROSPose与 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:=slcan0MoveIt仿真
demo.launch.py ↓ Xacro + URDF + SRDF ↓ robot_state_publisher ↓ move_group + OMPL + RViz ↓ 虚拟 ros2_control controller视觉抓取
相机帧 → YOLO/颜色检测 → 深度反投影 → 相机坐标 → 手眼变换 → base_link目标位姿 → IK/轨迹 → HardwareManager11. 建议学习顺序
- 先读
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.pyrebotarm_hardware.yamlrebotarm.urdf.xacrojoint_limits.yamlkinematics.yamlros2_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坐标和急停检查。