# 仿真代码

这个目录只放现场部署前使用的仿真验证代码。

仿真阶段要验证三件事：

- Isaac 车间、车辆、传感器和标定靶布置是否合理。
- 车间工控机只能通过 gateway 与“车端电脑”通信，不能直接发布底层执行器命令。
- 仿真车端和未来真实 Windows 车端使用同一套请求/响应边界。

## 环境功能和验收边界

| 组件 | 作用 | 验证什么 |
| --- | --- | --- |
| `isaac_workshop_sim` | 构建标定车间、阿克曼小车、传感器和标定靶 | 验证真值位姿、前视相机、下视相机、3D 雷达、2D 雷达、IMU 是否能从 Isaac 发布出来 |
| `isaac_vehicle_unified_agent_sim.py` | 模拟 Windows 车端电脑统一 WiFi6/TCP 入口 | 验证底盘、运控、外部真值位姿和传感器请求都从同一个车端端口进入 |
| `vehicle_agent_sim` | 独立底盘/运控/外部位姿后端，保留作调试工具 | 验证车端控制逻辑本身，不作为默认一键闭环入口 |
| `vehicle_sensor_agent_sim` | 独立传感器采集后端，保留作调试工具 | 验证车端能订阅 Isaac 传感器，并按传感器 ID 提供最新数据 |
| `vehicle_wifi6_gateway_sim.py` | 旧版分域后端聚合 gateway，保留作兼容工具 | 默认一键闭环不再使用它 |
| `external_pose_wifi6_bridge_sim.py` | 模拟外部真值系统通过 WiFi6 给车端提供定位 | 验证车端使用外部真值位姿，而不是直接订阅 Isaac 内部 topic |
| `workshop_sensor_ingest_sim.py` | 模拟车间侧从车端拉取传感器数据 | 验证车端传感器数据能进入车间工控机侧 ROS topic |
| `smoke_test_workshop_orchestrator.py` | 车间总控端到端验收 | 验证创建 session、阶段调度、WiFi6 预检、阶段结果和报告生成 |

当前 smoke test 的通过条件主要是“进程、接口、通信和编排可用”。它不等价于真实标定算法已经完成：

- 底盘阿克曼算法目前是模板输出，验证的是底盘任务分发和结果回传。
- 运控 Pure Pursuit 阶段会检查控制遥测数量并计算示例误差，但还不是完整参数优化闭环。
- 前视/下视相机内参阶段目前是算法模板，验证的是传感器标定任务调度和 readiness。
- 2D 雷达角落、墙面棋盘格、下视相机 3D 台阶是否产生足够高质量观测，需要后续专门采样质量脚本验证。

## 目录

- `isaac_workshop_sim/`
  Isaac 标定车间构建脚本、仿真车辆 URDF、仿真传感器和场景 manifest。

- `vehicle_agent_sim/`
  仿真车端电脑。它监听与真实 Windows 小车一致的 TCP 端口，并把被接受的动作转换成私有 Isaac 控制话题。

- `legacy_calibration_sim/`
  旧版 Gazebo/ROS 仿真包，先保留作参考。

- `tools/`
  仿真启动和验收工具，包括外部真值位姿 WiFi6/TCP 桥、车间侧传感器 ingest、TCP smoke test。

## 一键生成启动命令

默认读取 `src/deployment/profiles/sim_workshop.yaml`：

```bash
python3 src/simulation/tools/launch_sim_stack.py --dry-run
```

启动完整仿真链路：

```bash
python3 src/simulation/tools/launch_sim_stack.py
```

只启动仿真车端：

```bash
python3 src/simulation/tools/launch_sim_stack.py --component vehicle-agent
```

只启动外部真值位姿桥：

```bash
python3 src/simulation/tools/launch_sim_stack.py --component external-pose-bridge
```

只启动车间侧传感器接入：

```bash
python3 src/simulation/tools/launch_sim_stack.py --component sensor-ingest
```

只启动 Isaac 场景：

```bash
python3 src/simulation/tools/launch_sim_stack.py --component isaac
```

## 推荐测试顺序

1. 清理旧节点：

```bash
./stop_isaac_real_sim_stack.sh --list
./stop_isaac_real_sim_stack.sh --kill
```

2. 启动完整 Isaac 链路并执行默认验收：

```bash
./run_isaac_real_sim_test.sh --headless
```

3. 分阶段定位问题：

```bash
./run_isaac_real_sim_test.sh --headless --tasks external
./run_isaac_real_sim_test.sh --headless --tasks external,chassis
./run_isaac_real_sim_test.sh --headless --tasks external,chassis,control
./run_isaac_real_sim_test.sh --headless --tasks external,chassis,control,sensor_intrinsic
```

## TCP 快速验收

仿真车端启动后，可以先不动车，只检查 readiness 和急停：

```bash
python3 src/simulation/tools/smoke_test_vehicle_agent.py
```

如果需要让车执行一个很短的直线动作：

```bash
python3 src/simulation/tools/smoke_test_vehicle_agent.py --motion
```

验证轨迹跟踪时，外部真值位姿默认通过 `workshop_pc.gateway.vehicle_port` 进入车端统一入口，不再让车端直接订阅 Isaac 位姿 topic：

```bash
python3 src/simulation/tools/smoke_test_vehicle_agent.py --trajectory --fake-telemetry
```

传感器链路验收：

```bash
python3 src/simulation/tools/smoke_test_vehicle_sensor_agent.py --fake-sensors
```

## 边界

共享协议和 ROS 2 contract 不放在这里，而在：

- `src/communication/win_ubuntu_bridge/*_interfaces`
- `src/communication/win_ubuntu_bridge/vehicle_agent_gateway`

核心编排和标定算法不放在这里，而在：

- `src/core/agv_calib_core/workshop_orchestrator`
- `src/core/agv_calib_core/*_calibration_service`

仿真代码不要复制到真实车端部署目录。真实车端只复用接口语义，不复用 Isaac API。
