# AGV 自动标定车间 - 总述

本项目是 AGV（自动导引车）自动化标定车间的软件系统，用于在车间环境中对 AGV 进行底盘参数标定、运控参数标定、传感器内参/外参标定，以及手眼标定。

## 项目概述

### 核心能力

| 标定类型 | 说明 | 状态 |
|---------|------|------|
| 外部真值接入 | 通过外部定位系统（如 OptiTrack、激光雷达定位）获取车辆位姿真值 | ✅ 已验证 |
| 底盘参数标定 | 标定轮距、轴距、转向角等底盘几何参数 | ✅ 已验证（模板） |
| 运控参数标定 | 标定横向/纵向控制器的 PID/MPC/LQR 参数 | ✅ 已验证（模板） |
| 传感器内参标定 | 相机（前视/下视）、IMU 的内参标定 | ✅ 已验证（模板） |
| 传感器外参标定 | 相机、雷达等传感器相对于车体坐标系的外参标定 | 🚧 待完善 |
| 手眼标定 | 机械臂与相机之间的变换关系标定 | 🚧 待开发 |

### 技术架构

```
┌─────────────────────────────────────────────────────────────────┐
│                         车间工控机（Ubuntu）                      │
│  ┌─────────────────┐  ┌──────────────┐  ┌─────────────────────┐ │
│  │ workshop_       │  │ 底盘标定服务  │  │ 传感器标定服务       │ │
│  │ orchestrator_v2 │  │ chassis_     │  │ sensor_calibration_ │ │
│  │    (总控)       │  │ calibration  │  │     service         │ │
│  └────────┬────────┘  └──────────────┘  └─────────────────────┘ │
│           │                                                      │
│  ┌────────▼────────┐  ┌──────────────┐  ┌─────────────────────┐ │
│  │ vehicle_agent_  │  │ 运控标定服务  │  │ 外部位姿服务         │ │
│  │    gateway      │  │ control_     │  │ external_           │ │
│  │  (WiFi6/TCP网关) │  │ calibration  │  │ localization_       │ │
│  └─────────────────┘  └──────────────┘    └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │ WiFi6/TCP
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         车端电脑（Windows/Linux）                │
│  ┌─────────────────┐  ┌──────────────┐  ┌─────────────────────┐ │
│  │   车端 Agent     │  │  底盘控制器   │  │    传感器驱动        │ │
│  │ (TCP<->CAN/PLC) │  │   (CAN/PLC)  │  │  (相机/雷达/IMU)     │ │
│  └─────────────────┘  └──────────────┘  └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## 目录结构

```
agv_calib_brain/
├── src/
│   ├── core/              # 核心标定逻辑
│   │   ├── workshop_orchestrator/      # 车间总控编排器
│   │   ├── chassis_calibration_service/ # 底盘标定服务
│   │   ├── control_calibration_service/ # 运控标定服务
│   │   ├── sensor_calibration_service/  # 传感器标定服务
│   │   ├── external_localization_service/ # 外部位姿服务
│   │   └── vehicle_profile_manager/    # 车辆画像管理
│   │
│   ├── communication/     # 通信层
│   │   ├── win_ubuntu_bridge/          # 车间<->车端通信桥
│   │   └── interfaces/                 # ROS2 接口定义
│   │
│   ├── simulation/        # 仿真验证
│   │   ├── isaac_workshop_sim/         # Isaac Sim 标定车间
│   │   ├── vehicle_agent_sim/          # 仿真车端 Agent
│   │   ├── vehicle_sensor_agent_sim/   # 仿真传感器 Agent
│   │   └── tools/                      # 仿真工具脚本
│   │
│   ├── deployment/        # 部署配置
│   │   └── profiles/                   # 仿真/部署配置文件
│   │
│   ├── site_deployment/   # 真实现场部署
│   │   └── (真实车辆 SDK、PLC/CAN 适配)
│   │
│   └── apps/              # 操作员工具
│
├── run_isaac_real_sim_test.sh    # 一键启动 Isaac 仿真测试
├── stop_isaac_real_sim_stack.sh  # 停止仿真栈
├── SIMULATION_GUIDE.md           # 仿真环境启动指南
└── README.md                     # 本文件
```

## 快速开始

### 1. 编译

```bash
cd /home/nvidia/study/AutoCalib-Workshop/agv_calib_brain
colcon build
source install/setup.bash
```

### 2. 一键启动完整仿真

```bash
# 启动 Isaac + 车端 Agent + 车间总控 + 执行验收
./run_isaac_real_sim_test.sh --headless
```

### 3. 查看详细指南

- **仿真启动指南**: [SIMULATION_GUIDE.md](./SIMULATION_GUIDE.md) - 如何单独启动各组件
- **源码目录说明**: [src/README.md](./src/README.md) - 源码组织结构

## 主要验证场景

| 场景 | 启动方式 | 验证内容 |
|------|---------|---------|
| 快速闭环验证 | `launch_sim_stack.py --component vehicle-agent` + `minimal_workshop_demo.launch.py` | 车间总控能创建 session、生成阶段计划、调用车端接口 |
| Isaac topic 检查 | `run_isaac_real_sim_test.sh --headless`（前半段） | Isaac 能发布传感器和真值 topic |
| 完整 Isaac 仿真闭环 | `run_isaac_real_sim_test.sh --headless` | 场景、agent、桥接、总控一起运行 |
| 传感器转发链路 | `--component vehicle-agent,sensor-ingest` | 车端能订阅 Isaac topic，车间端能拉取数据 |

## 四条核心通信链路

| 链路 | 方向 | 功能 | 组件 |
|------|------|------|------|
| 外部真值链路 | 外部系统 → 车端 | 位姿、速度、时间戳 | `external-pose-bridge` |
| 底盘链路 | 车间 → 车端 | 下发标定动作、读取遥测 | `vehicle-agent-gateway` |
| 运控链路 | 车间 → 车端 | 下发控制任务、读取误差 | `vehicle-agent-gateway` |
| 传感器链路 | 车端 → 车间 | 相机、雷达、IMU 数据 | `sensor-ingest` |

## 开发状态

- ✅ **已完成**: 车间总控编排器、四类标定服务框架、车辆画像管理、Isaac 仿真环境、WiFi6/TCP 通信链路、端到端验收脚本
- 🚧 **进行中**: 传感器外参标定采样链路、真实算法参数收敛
- ⏳ **待开发**: 手眼标定、真实现场部署验证

## 关键设计原则

1. **主控只编排流程** - `workshop_orchestrator_v2` 负责阶段调度，具体标定由独立 ROS2 包实现
2. **仿真与现场分离** - Isaac 代码只在 `simulation/`，真实车辆代码只在 `site_deployment/`
3. **统一通信协议** - 车间与车端通过 WiFi6/TCP 通信，协议由 `communication/` 定义
4. **车辆画像驱动** - 车辆能力、传感器配置通过 `vehicle_profile` 描述，支持多车型