URDF 与 Xacro：给机器人造一份数字骨架

节选自 car1.urdf 开头（robot 标签横跨全文到文件末尾）
<?xml version="1.0" encoding="utf-8"?>
<robot name="car1">
  <!-- 空 link：没有几何也没有质量，只当坐标系用——base_footprint 是整车"落地点" -->
  <link name="base_footprint" />
  <!-- 同款空 link 还有 tcp_link（末端工具点）、camera_depth_optical_frame（相机光轴系）…全文十几处 -->
</robot>

读法：name="car1" 就是 check_urdf 第一行 robot name is: car1 的出处；空 link 不显示任何东西，只为给 TF 树提供一个原点。

节选自 car1.urdf 的 base_link（惯性矩阵共 9 个数，此处原样摘录）
<link name="base_link">
  <!-- inertial：动力学读它——质量 1.97 kg + SolidWorks 算好的 3×3 惯性矩阵 -->
  <inertial>
    <origin xyz="0.00119523538791205 0.00195957701632652 0.0457542650231294" rpy="0 0 0"/>
    <mass value="1.97049077979221"/>
    <inertia ixx="0.00486152635724755" ixy="2.00512337711509E-06" ixz="0.000162020407436135"
             iyy="0.00915836901735741" iyz="2.72820673876569E-06" izz="0.0130028044572217"/>
  </inertial>
  <!-- visual：RViz2 读它——STL 网格 + 颜色（rgba 值域是 [0,1]，不是 0~255） -->
  <visual>
    <origin xyz="0 0 0" rpy="0 0 0"/>
    <geometry><mesh filename="package://car1_description/meshes/base_link.STL"/></geometry>
    <material name=""><color rgba="1 1 1 1"/></material>
  </visual>
  <!-- collision：Gazebo 碰撞检测读它，这里直接复用同一 STL（真实工程可简化成包围盒） -->
  <collision>
    <origin xyz="0 0 0" rpy="0 0 0"/>
    <geometry><mesh filename="package://car1_description/meshes/base_link.STL"/></geometry>
  </collision>
</link>

读法：三块内容消费方各不相同——渲染吃 visual、碰撞吃 collision、动力学吃 inertial；package:// 是"包内相对路径"，装到哪台机器都能找到网格。三属性的完整作用表在 03 节。

节选自 car1.urdf：base_footprint 与 base_link 之间的"垫高"关节
<joint name="base_joint" type="fixed">
  <origin xyz="0 0 0.029" rpy="0 0 0"/>  <!-- 子 link 相对父 link：仅沿 Z 抬高 2.9 cm -->
  <parent link="base_footprint"/>
  <child link="base_link"/>
</joint>

读法：fixed = 0 自由度、焊死不能动，只负责定安装位姿；xyz 三个数是平移（米），遵循 REP-103（X 前 / Y 左 / Z 上）。激光雷达 laser_joint 的 xyz="0.146 0 0.087" 同理——"往前 14.6 cm、往上 8.7 cm"装雷达。

节选自 car1.urdf：深度相机末端的光学坐标系关节
<joint name="camera_depth_optical_joint" type="fixed">
  <origin xyz="0 0.01655 0"
          rpy="-1.57079633 0 -1.57079633"/>  <!-- -π/2 ≈ -1.5708，两个 90° 把车体系掰成相机光学系约定 -->
  <parent link="camera_depth_link"/>
  <child link="camera_depth_optical_frame"/>
</joint>

读法：rpy 三个数 = 绕 X、Y、Z 的旋转弧度（roll / pitch / yaw），求值先 rpy 旋转、再 xyz 平移；±1.5708 就是 90°。joint 里的 origin = 子 link 相对父 link 的位姿——与 link 内 visual 下的 origin（几何体对自己的偏移）语义完全不同，详见 03 节。

节选自 car1.urdf：左前驱动轮（其余三个轮同构，仅 name/xyz 不同）
<joint name="wheel_lf_joint" type="continuous">
  <origin xyz="0.097300000000001 0.105834744636228 0.0195000000000009" rpy="0 0 0"/>
  <parent link="base_link"/>
  <child link="wheel_lf_link"/>
  <axis xyz="0 1 0"/>  <!-- 轮轴沿 Y（车宽方向）——绕它一直转 -->
</joint>

读法：continuous = 一直转动，无限转圈，因此没有也不允许 <limit>；只要给 axis（转轴方向）。拖滑块时轮子转不到"头"——这正是它和例 6 的分界。

节选自 car1.urdf：机械臂第一轴（arm_joint2~5、夹爪诸关节同款写法）
<joint name="arm_joint1" type="revolute">
  <origin xyz="0.0100000000000003 0 0.0434999999999999" rpy="0 0 0"/>
  <parent link="arm_base_link"/>
  <child link="arm_link1"/>
  <axis xyz="0 0 1"/>  <!-- 绕 Z 转（肩关节回转） -->
  <limit lower="-3.14" upper="3.14" effort="100" velocity="1"/>  <!-- 有限转动，四件套写全 -->
</joint>

读法：revolute = 有限转动，角度被 limit 锁死在 −3.14 ~ +3.14 rad（±180°）；effort=100 最大力矩、velocity=1 最大角速度。拖滑块到头即停、check_urdf 缺 limit 直接报错——revolute 的 limit 是必填项。

节选自 car1.urdf：左外指关节，从动于右关节
<joint name="l_joint" type="revolute">
  <origin xyz="0.01900706 0.01375021 0.0025" rpy="0 0 0"/>
  <parent link="arm_link6"/>
  <child link="l_link"/>
  <axis xyz="0 0 -1"/>
  <limit lower="-3.14" upper="3.14" effort="100" velocity="1"/>
  <mimic joint="r_joint" multiplier="-1" offset="0"/>  <!-- 跟随 r_joint：角度 ×(-1) 反向联动 -->
</joint>

读法：mimic 让本关节成为从动关节——只驱动 r_joint，l_joint 按 multiplier 自动反向跟动（夹爪对开就是这么省出来的）。这是 car1 文件里除 fixed / continuous / revolute 之外的又一种分类。

• 绕一根轴不停旋转，没有转角限制，可以转很多圈
• 不需要 <limit> 标签
• 示例：小车轮子，向前向后无限滚（car1 四个驱动轮，原文见 02 节例 5）

<joint name="wheel_joint" type="continuous">
  <parent link="base_link"/>
  <child link="wheel_link"/>
  <axis xyz="0 1 0"/>  <!-- 只给转轴，不写 limit —— 它可以一直转 -->
</joint>

• 也是绕轴旋转，但是有最大、最小角度，到角度就卡住
• 必须写 <limit lower upper effort velocity/> —— 角度单位是弧度 rad（check_urdf 缺了直接报错）
• 示例：机械臂关节、舵机，只能 0~90° 来回摆，不能一直转

# car1 机械臂第一轴的原值四件套（02 节例 6 同款）
<joint name="arm_joint1" type="revolute">
  <parent link="arm_base_link"/>
  <child link="arm_link1"/>
  <axis xyz="0 0 1"/>
  <limit lower="-3.14" upper="3.14" effort="100" velocity="1"/>  <!-- 弧度限位 + 最大力矩 + 最大角速度 -->
</joint>

• 不是转，是沿着一根轴直线推拉滑动（滑轨、丝杆、气缸的动作）
• 带位置限位，单位是米 m（不是弧度）
• 示例：升降杆、伸缩夹爪、升降滑台（car1 本车未用，属通用写法）

<joint name="lift_joint" type="prismatic">
  <parent link="base_link"/>
  <child link="lift_link"/>
  <axis xyz="0 0 1"/>  <!-- 沿 Z 直线推 -->
  <limit lower="0" upper="0.3" effort="50" velocity="0.2"/>  <!-- 行程 0~0.3 m，单位是米！ -->
</joint>

• 没有任何相对运动，父子连杆焊死在一起，相对位置姿态永久不变
• 不需要 axis、limit、dynamics
• 你前面那张 TF 图里 base_footprint → base_link 就是 fixed（02 节例 3 原文：xyz="0 0 0.029"）
• 作用：把雷达、相机、外壳固定到底盘上，只用来传递静态 TF

<robot xmlns:xacro="http://ros.org/wiki/xacro">
    <!-- Gazebo 物理参数宏：params="name" 声明形参，${name} 是调用处传入的实参 -->
    <xacro:macro name="gazebo_link" params="name">
        <gazebo reference="${name}">
            <kp>0</kp><kd>0</kd>
            <mu1>1</mu1><mu2>1</mu2>  <!-- 摩擦系数 -->
            <material>Gazebo/White</material>
        </gazebo>
    </xacro:macro>

    <!-- 夹爪换高刚度宏：kp=1e15 抓得稳、kd=1e13 减震——换个宏名即换整套参数 -->
    <xacro:macro name="gazebo_gripper" params="name">
        <gazebo reference="${name}">
            <kp>1e15</kp><kd>1e13</kd>
            <mu1>1.0</mu1><mu2>1.0</mu2>
            <material>Gazebo/Black</material>
        </gazebo>
    </xacro:macro>

    <!-- 宏调用：像普通标签一样使用；${prefix} 拼在每个名字前，多车不撞名 -->
    <xacro:macro name="car1_gazebo" params="prefix">
        <xacro:gazebo_link name="${prefix}arm_base_link"/>
        <xacro:gazebo_link name="${prefix}arm_link1"/>  …（7 节臂各一行）
        <xacro:gazebo_gripper name="${prefix}r_link"/>  …（6 个夹爪件）
        <xacro:gazebo_link name="${prefix}base_link"/>
    </xacro:macro>
</robot>

读法：宏 = 带参数的 XML 模板——定义一次，car1_gazebo 里连调十几行；${name}、${prefix}arm_link1 在展开时做字符串替换，${} 里也可以写算式（如 ${wheel_radius/2 + 0.01}，property 收编变量的完整流程即图 20-4）。忘写 xmlns:xacro，这些标签全部失效（05 节坑条）。

<robot name="car1" xmlns:xacro="http://ros.org/wiki/xacro">
    <!-- 命令行/launch 可传参数：$(arg prefix) 逐处取值 -->
    <xacro:arg name="prefix" default=""/>

    <!-- 兼容实锤：include 的目标是一份普通 .urdf 文件，原样引入、一行不改 -->
    <xacro:include filename="$(find car1_description)/urdf/car1.urdf"/>

    <!-- 再叠加物理、传动、硬件接口三份宏文件 -->
    <xacro:include filename="$(find car1_description)/gazebo/car1.gazebo.xacro"/>
    <xacro:include filename="$(find car1_description)/gazebo/car1.transmission.xacro"/>
    <xacro:include filename="$(find car1_gazebo)/urdf/car1.gazebo.ros2_control.xacro"/>

    <!-- 宏调用：把物理参数/传动/硬件刷到每个 link、joint 上 -->
    <xacro:car1_gazebo prefix="$(arg prefix)"/>
    <xacro:car1_transmission prefix="$(arg prefix)"/>
    <xacro:car1_gazebo_ros2_control name="GazeboSimSystem"/>

    …（其后是 Gazebo<plugin>、相机<sensor> 等原生标签，按原样保留到文件尾）…
</robot>

读法：总装文件 = URDF（子集原样合入）+ Xacro 宏调用 + 原生 Gazebo 标签混排；xacro 命令一跑，car1.urdf 的一千二百行原封并入、宏全部替换为普通标签，输出即标准 URDF。URDF 与 Xacro 的双向兼容在此文件里是实锤——加载方法就是 04 节步骤 ② 两段代码。