# devices/sim/gazebo/ —— Gazebo 仿真平台

## 先读这段：当前仿真是假的

**现在项目里的「仿真」并不是 Gazebo。** 实际情况是：

- `src/arm_description/urdf/arm.gazebo.xacro` 是零引用的死文件；
- `arm_bringup/stack.launch.py` 的 `isaac` 分支只有一行日志，没有任何实际动作；
- `run_sim.sh` 走的是 `sim.launch.py`，底层是 **mock 驱动**（`mock_arm_driver.py`），
  即用假数据模拟机器人状态，不是物理仿真；
- Gazebo 从未真正接线。

所以这份文档分两部分：**第一部分是怎么把 Gazebo 真正跑起来**（当前必须做的前置工作），
**第二部分才是日常怎么用**。不要跳过第一部分。

---

## 第一部分：把 Gazebo 真正接起来（前置工作）

要让 Gazebo 跑起来，缺的是这几块，按顺序补齐：

### 1. URDF 加 Gazebo 标签

现有 `arm_description/urdf/arm.gazebo.xacro` 是死文件，需要重写。每个 link 必须补：

```xml
<!-- 视觉碰撞体 -->
<gazebo reference="${prefix}link1">
  <material>Gazebo/Grey</material>
</gazebo>
```

并在 `arm.ros2_control.xacro` 里把 `ros2_control` 标签的 hardware 插件从
`flexiv_hardware/FlexivHardware` 换成 `gazebo_ros2_control/GazeboSystem`。

### 2. 关节传动与控制器

Gazebo 需要 `transmission` 标签把关节映射到 `ros2_control`。控制器配置可以直接复用
`arm_control/config/controllers.yaml` 里的 `rizon_arm_controller`，只需把关节名前缀
从真实 SN（如 `Rizon4-063989_`）换成仿真专用的前缀（如 `sim_`）。

### 3. 传感器插件

| 仿真对象 | 插件 | 对应真实设备 |
|----------|------|--------------|
| 腕部相机 | `libgazebo_ros_camera.so` | D405 |
| 手外相机 | `libgazebo_ros_camera.so` | D435 |
| 深度 | `libgazebo_ros_depth_camera.so` | 对齐深度流 |
| 触觉力 | **需要自己写插件** | Orisys |

**最关键的一条：Orisys 视触觉没有现成的 Gazebo 插件。**
3 路切向力 + 1 路法向力 + 深度图 + 力矢量图 这套数据需要自定义 Gazebo 插件来模拟。
在它做出来之前，仿真里**无法验证通止规装配的力控部分**（S07 接触、S08 拧紧判定）。
建议的自定义插件做法：订阅 Gazebo 的接触传感器数据，按接触深度和相对滑动速度合成
出一组「类触觉」读数，再按真实传感器的量纲（任意单位增量）发布到同样的内部话题上。

### 4. 工件与通止规模型

需要给工件（含 k0 中心孔、k1/k2 螺纹孔）和通止规建简化网格，并保证：

- 工件的 k0/k1/k2 三个点在模型坐标系里的位置与实际一致 —— 否则推理出的坐标映射到仿真里会对不上；
- 螺纹孔要能表达「拧入」的几何阻力，否则 S08 的力反馈无法触发。

---

## 第二部分：日常怎么用

### 放置格式与命名要求

| 类型 | 放哪 | 格式 | 命名要求 |
|------|------|------|----------|
| 世界文件 | `worlds/` | `.world` 或 `.sdf` | `<场景名>.world`，如 `assembly.world` |
| 机器人模型 | `urdf/` | `.urdf` / `.xacro` | 必须以 `sim_` 为关节前缀，与真实臂区分 |
| 工件/夹具网格 | `models/<模型名>/` | `<模型名>.sdf` + `meshes/` | **模型名必须与推理用的类别名一致**，如 `workpiece` |
| 传感器插件 | `sensor_plugins/` | `.so` 源码 + `CMakeLists.txt` | 插件类名以 `Orisys` 开头 |
| 网格文件 | `models/<模型名>/meshes/` | `.stl` / `.dae` | 单位必须是米。用毫米建模的必须先缩放到米 |

### 导入一个新场景

1. 把 `.world` 放进 `worlds/`，网格放进 `models/<模型名>/`
2. 改 `config/site.yaml` 的 `sim.world` 指向该文件
3. 改 `devices/registry.yaml` 的 `sim: gazebo`（通常已是）
4. 启动 `scripts/run_sim.sh`

### 修改哪个配置才会生效

| 想改什么 | 改哪里 |
|----------|--------|
| 用哪个场景 | `site.yaml` → `sim.world` |
| 仿真是否启用物理 | `site.yaml` → `sim.physics_enable` |
| 仿真里的悬高/速度 | **复用真实的那套参数**（`servo.*` / `hole_detect.stage2.*`），不要另建一套，否则仿真调好的值搬到真机不生效 |
| 关节前缀 | `site.yaml` → `sim.joint_prefix`（默认 `sim_`） |

> **设计约束**：仿真与真机必须共用同一套 `site.yaml` 参数。任何「仿真专用参数」都是未来
> 仿真调参搬到真机失效的隐患。只允许物理引擎本身的参数（如重力、步长）放在 `sim.*` 下。