robot-descriptions-common¶

共享夹爪、灵巧手、传感器模型，以及 robot_common_launch。在 robot_descriptions 伞形仓下，本仓是 common 子模块。

仓库： fiveages-sim/robot-descriptions-common

权威来源

仓库： fiveages-sim/robot-descriptions-common
末端 / type 行为依据 robot_common_launch/README.md。没有 gripper:= launch 参数。
仓库： fiveages-sim/robot-descriptions-common
main 上没有 .cursor/skills。包名就是该 README / 仓库树里的目录。

没有 gripper:= 启动参数。用 type / left_type / right_type 挂末端（见下）。

布局¶

main 上的目录（浏览仓库）：

common/                          # umbrella checkout path
├── gripper/                     # one ROS package per brand
├── dexhands/
├── sensor_models/               # single package: meshes + URDF
├── component_models/            # single package: meshes + xacro (not tabulated in the README)
└── robot_common_launch/
    ├── config/                  # RViz, Nav2, …
    ├── launch/
    ├── worlds/
    └── xacro/

README 的包结构树还在 dexhands/ 下列了 xhand1_description（灵巧手表里没有）。

夹爪（`gripper/`）¶

仓库： fiveages-sim/robot-descriptions-common

品牌	软件包	型号
ChangingTek	`gripper/changingtek_description`	AG2F90-C、AG2F120S
DH	`gripper/dh_description`	PGC_140_50
Robotiq	`gripper/robotiq_description`	2F-85
因时	`gripper/inspire_description`	EG2-4C2（灵巧手 RH56E2 / RH56F2 也在这个包）
Jodell	`gripper/jodell_description`	RG75-300
Hitbot	`gripper/hitbot_description`	Z-EFG-100
Eincinx	`gripper/eincinx_description`	EPGI180
含义	`gripper/marvin_gripper_description`	marvin_gripper、marvin_gripper45

README：每个夹爪包含 URDF/xacro、网格、ros2_control 配置和安装位姿。

灵巧手（`dexhands/`）¶

品牌	软件包	型号
BrainCo	`dexhands/brainco_description`	REVO1、REVO2
LinkerHand	`dexhands/linkerhand_description`	O6、O7、L6、L10
因时	`gripper/inspire_description`	RH56E2、RH56F2
YAML 段	`dexhands/oymotion_description`	RoHand Gen2
FreeDom	`dexhands/freedom_description`	V1、V2
TheoHand	`dexhands/theohand_description`	STD16A
舞肌	`dexhands/wuji_description`	Hand2、Beta2

传感器（`sensor_models/`）¶

README 列出的 URDF + 网格：

Intel RealSense D405
Intel RealSense D435
Orbbec Dabai
Livox Mid-360

在 xacro 里引用组件¶

README 示例（Robotiq）。从真实 {robot}_description 复制已有 include：

<xacro:include filename="$(find robotiq_description)/xacro/gripper.xacro"/>

<xacro:robotiq_gripper
  parent="arm_link_6"
  name="gripper">
  <origin xyz="0 0 0" rpy="0 0 0"/>
</xacro:robotiq_gripper>

`spawn_robot.launch.py`¶

跨机器人 launch 入口、xacro 映射，以及 machine profile YAML（robot_profile:=）。下游可视化 / controller_manager / 控制器包通过这套 API 生成 robot_description 和规划 URDF。

含义

robot_profile:=/path/to/profile.yaml → load_robot_profile / normalize_robot_profile → build_xacro_mappings（或 build_visualization_xacro_mappings）→ xacro → robot_description / 规划 URDF。

实现：launch_arg_utils.py。任何转发 robot_profile 的 launch（例如 create_robot_profile_launch_arguments()）都走同一条路径。

合并优先级¶

Launch CLI > robot_profile YAML > xacro 默认值

YAML 段	设置 `robot_profile:=` 时	说明
`platform`	始终	底盘 / 双臂套件 / `variant` / `chassis_joints_movable` → xacro
`defaults.end_effectors`	仅当 `use_profile_eef:=true`（默认）	末端键；关掉后改用命令行 `type` / `left_type` / `right_type`
`defaults.ft`	始终	力传感器；不受 `use_profile_eef` 门控
`defaults.tcp_offset`	始终	虚拟 tip 偏移；写入 mappings 前求值表达式
`hardware`	仅 `hardware:=real`	真机 xacro（串口、`arm_ctrl_mode` 等）
`control.patch`	始终	加入 ros2_control 配置

Profile schema（README）：

platform:
  chassis: <key>
  arms: <key>                 # dual-arm kit; {key}_description or a _vN suffix
  variant: <key>
  chassis_joints_movable: "true"|"false"

defaults:
  end_effectors:
    type: <eef_key>            # symmetric; or write left / right

末端执行器（`type` / `left_type` / `right_type`）¶

参数	含义
`type`	对称末端键，或臂拓扑 `left` / `right` / `dual`。拓扑不会展开成 `left_type` / `right_type`。
`left_type` / `right_type`	分侧末端键。`create_eef_side_launch_arguments()` 列出的示例键为 `rg75`、`ag2f90_c`、`linkerhand_o7`。左右不同时一起使用；此时不要再传 `type:=`。
`use_profile_eef`	应用 profile 的 `defaults.end_effectors`（默认 `true`）
`robot_profile`	整机 profile YAML 路径

默认：use_profile_eef:=true → 应用 profile 的 defaults.end_effectors。
设 use_profile_eef:=false 可忽略该段，强制使用命令行 type / left_type / right_type。profile 中的 platform、ft、tcp_offset 仍然生效。

README 示例（命令行指定末端，其余仍可用 profile）：

ros2 launch <pkg> <file>.launch.py \
  robot_profile:=/path/to/machine_profile.yaml \
  use_profile_eef:=false \
  left_type:=rg75 right_type:=linkerhand_o7

力/力矩¶

不受 use_profile_eef 控制。

参数	含义
`ft` / `left_ft` / `right_ft`	力传感器键；覆盖 profile 的 `defaults.ft`
`tcp_offset_xyz` / `tcp_offset_rpy`	对称 TCP 偏移
`left_tcp_offset_` / `right_tcp_offset_`	分侧 TCP 偏移

Profile 的 defaults.ft.type：none | kwr75_485 | kwr75_usb（或 left / right）。end_effectors / ft / tcp_offset 都支持对称键并展开到左右；缺侧回退对称值。

TCP 字符串在写入 xacro 之前求值（${PI/2}、pi/2、radians(90)、纯数字）。求值失败会报错，不会静默写入。选用虚拟 tip 时，还需在 control.patch（或控制器参数）中设置 left_ee_frame / right_ee_frame（例如 left_tcp_offset）。

ros2 launch robot_common_launch humanoid.launch.py robot:=<robot_name> \
  robot_profile:=/path/to/machine_profile.yaml \
  ft:=kwr75_485 \
  tcp_offset_rpy:="0 0 ${PI/2}"

平台槽位（`chassis` / `arms` / `variant` / `chassis_joints_movable`）¶

摘自 robot_common_launch README（平台槽位）。解析顺序：CLI > profile platform.* > 该机 xacro/robot.xacro 默认值。空字符串表示不向 xacro 传该参数。

参数	作用
`chassis`	底盘型号（机型相关）
`arms`	可换双臂套件。不会合并 `config/ros2_control/{arms}.yaml`（那是 `variant` 的 overlay）
`variant`	机型变体（外观、立柱等）。若文件存在，可合并 `config/ros2_control/{variant}.yaml`
`chassis_joints_movable`	底盘关节是否可动（`true` / `false`）

create_platform_launch_arguments() 在人形 / component 以及 OCS2 full_body / split_body / demo 上声明 chassis / arms / chassis_joints_movable。独立机械臂 launch 不挂这组。variant 由 create_robot_profile_launch_arguments() 声明。

README 示例：

ros2 launch robot_common_launch humanoid.launch.py robot:=fiveages_w1 arms:=ar5_ccs
ros2 launch robot_common_launch humanoid.launch.py robot:=fiveages_w2r arms:=ar5_srs

加入 ros2_control 配置¶

末端 / type 行为依据 robot_common_launch/README.md。没有 gripper:= launch 参数。

common.yaml
  → <type>.yaml / ros2_controllers.yaml
  → {variant}.yaml          # opt-in: config/ros2_control/<variant>.yaml
  → {hardware}.yaml         # opt-in: config/ros2_control/<hardware>.yaml
  → EEF compose (if any)
  → control.patch (profile)

<type>.yaml 如何选定（resolve_compose_type_key / _generate_progressive_type_candidates）：

对称末端（只设 type，或 left_type 等于 right_type）：按去掉 _ 后缀做渐进匹配。辅助函数文档示例：ccs_left_rg75 → ccs_left → ccs。第一个存在的 {candidate}.yaml 生效；否则用 ros2_controllers.yaml。
非对称（left_type ≠ right_type）：跳过渐进 type YAML。基底文件是 ros2_controllers.yaml，再按 eef_control_registry.yaml 与分侧模板做 EEF compose（control_compose.py）。

该 README 里的 hardware:= 取值：mock_components / gz / isaac / real。overlay YAML 仅当文件存在时才合并。Profile YAML 的 hardware:（串口、arm_ctrl_mode）是另一层，只在 hardware:=real 时生效。

Launch 入口（README）¶

仓库 README（路径在 robot_common_launch/launch/ 下）：

类别	Profile schema（README）：
RViz 可视化	`visualize.launch.py` / `humanoid.launch.py` / `manipulator.launch.py`
`control.patch`	`control/controller_manager.launch.py`、`control/diff_drive.launch.py`、`control/hardware_visualize.launch.py`
RViz 可视化	`manipulation/manipulator_ocs2.launch.py`
导航	`navigation/navigation.launch.py`、`navigation/cartographer.launch.py`、`navigation/navigation_slam.launch.py`、`navigation/amr_rctk.launch.py`

main 的 launch/ 下还有这些文件（README 表没点名）：

类别	额外文件
RViz 可视化	`visualize/visualize.launch.py`、`visualize/component.launch.py`（`robot_common_launch` README 调用表有写）
`control.patch`	`control/cartesian_controller.launch.py`
RViz 可视化	`manipulation/humanoid_ocs2.launch.py`
导航	`navigation/navigation_cartographer.launch.py`、`navigation/navigation_isaac_gt.launch.py`

navigation_isaac_gt.launch.py 是 robot_action_composer ROS2_STACK.md 写的默认 Nav2 launch。

robot_common_launch README 的调用表（同一包；先安装）：

colcon build --packages-up-to robot_common_launch --symlink-install
source install/setup.bash

场景	启动
RViz 可视化	`visualize.launch.py` / `humanoid.launch.py` / `manipulator.launch.py`
夹爪	`gripper.launch.py` / `hand.launch.py`
组件	`spawn_robot.launch.py`
控制器管理	`controller_manager.launch.py`
导航	`display.launch.py`

仓库 README 示例：

ros2 launch robot_common_launch gripper.launch.py
ros2 launch robot_common_launch manipulator_ocs2.launch.py
ros2 launch robot_common_launch navigation_slam.launch.py

OCS2 的 demo / split_body / full_body 也通过 create_robot_profile_launch_arguments() / create_platform_launch_arguments() 声明这些一等参数。

GitHub Release `.deb`¶

ros-jazzy-robot-descriptions-common 不在 Debian / ROS apt。工作流：.github/workflows/build-common-deb.yml。规则：README.deb.md。

主路径： 在 open-deploy-ws / fa-deploy-ws 中运行 ./init_repo.sh，给 common 选 d，或 ./scripts/install_core_debs.sh --only common。用菜单 2) 切换模块安装方式 在源码 ↔ deb 之间切换。

README.deb.md 示例：

gh release download pre-release --repo fiveages-sim/robot-descriptions-common --pattern '*_amd64.deb'
sudo dpkg -i ros-jazzy-robot-descriptions-common_*.deb

robot-descriptions-common¶

布局¶

夹爪（gripper/）¶

灵巧手（dexhands/）¶

传感器（sensor_models/）¶