AutoCalib-Workshop/agv_calib_brain/src/README.md

# 🧠 AGV 标定中央大脑

**环境**: Ubuntu 22.04 + ROS 2 Humble | **语言**: C++ | **通信**: gRPC over Wi-Fi 6

> 标定车间的"发令大脑"，通过局域网跨平台遥控 Windows 车端执行动作并拉取遥测数据。

---

## 📋 目录

1. [系统依赖安装](#1-系统依赖一键安装)
2. [VS Code 插件配置](#2-vs-code-核心插件配置)
3. [解决 IntelliSense 报错](#3-解决-vs-code-红色波浪线)
4. [编译与运行](#4-编译与运行)

---

## 1. 系统依赖一键安装

在 Ubuntu 22.04 终端执行以下命令：

```bash
sudo apt update
sudo apt install -y build-essential cmake pkg-config gdb
sudo apt install -y protobuf-compiler-grpc libgrpc++-dev libprotobuf-dev protobuf-compiler
```

> ⚠️ **警告**: 严禁自行去 GitHub 源码编译 gRPC，直接使用 Ubuntu 官方 APT 源即可，避免浪费时间与报错。

---

## 2. VS Code 核心插件配置

打开 VS Code → 扩展商店 (Extensions)，**必须安装**以下 4 个插件：

| 插件名称 | 开发者 | 用途 |
|---------|--------|------|
| **C/C++**    | Microsoft | 代码补全与 GDB 调试 |
| **CMake Tools** | Microsoft | 底部快速构建状态栏 |
| **ROS** | Microsoft | 自动识别 `colcon` 工作空间 |
| **vscode-proto3** | zxh404 | `.proto` 文件语法高亮 |

---

## 3. 解决 VS Code 红色波浪线 (IntelliSense 报错)

**问题原因**: gRPC 生成的 `.pb.h` 文件在 `colcon build` 阶段动态生成于 `build/` 目录，VS Code 初始无法识别。

**修复步骤**:

1. 按 `Ctrl+Shift+P` → 输入 `C/C++: Edit Configurations (JSON)`
2. 确保 `c_cpp_properties.json` 包含以下配置：

```json
{
    "configurations": [
        {
            "name": "ROS2",
            "includePath": [
                "${workspaceFolder}/**",
                "/opt/ros/humble/include/**",
                "${workspaceFolder}/build/agv_calib_brain/grpc_gen/**"
            ],
            "compilerPath": "/usr/bin/gcc",
            "cStandard": "c17",
            "cppStandard": "c++17",
            "intelliSenseMode": "linux-gcc-x64"
        }
    ]
}
```

> 💡 **提示**: `grpc_gen` 是 CMakeLists 中配置的自动生成源码路径，请根据实际情况微调。

---

## 4. 编译与运行 (CMake 自动化)

### 4.0 最小联调闭环

当前仓库已经补齐了一个最小可运行闭环：

- `vehicle_profile_manager`：提供默认车辆画像
- `external_localization_service`：提供外部真值校核的最小执行端
- `workshop_orchestrator_v2`：负责编排会话、计划和报告

启动顺序：

```bash
source /opt/ros/humble/setup.bash
source install/setup.bash
ros2 launch win_ubuntu_bridge minimal_workshop_demo.launch.py
```

如果只想单独跑编排器：

```bash
ros2 launch workshop_orchestrator_v2 workshop_orchestrator_v2.launch.py
```

可先调用这些接口做联调：

- `/vehicle_profile_manager/get_vehicle_profile`
- `/vehicle_profile_manager/evaluate_vehicle_calibration_applicability`
- `/external_localization/get_readiness`
- `/external_localization/execute_task`
- `/workshop_v2/create_session`
- `/workshop_v2/execute_session`
- `/workshop_v2/get_report`

最小会话建议至少包含：

- `session.config.localization_source_id = demo_vehicle_001`
- `session.config.workcell_zone_id = demo_workcell`
- 一个 `requested_tasks`，其中 `stage_type = EXTERNAL_REFERENCE_READY_CHECK_STAGE`
- 该任务的 `task_params` 至少包含：
  - `external.static_sample_count`
  - `external.dynamic_sample_count`
  - `external.max_position_stddev_m`
  - `external.max_yaw_stddev_rad`
  - `external.max_tracking_loss_ratio`
  - `external.max_time_sync_offset_ms`
  - `external.timeout_sec`


> ✨ **无需手动执行 `protoc`** —— CMakeLists.txt 已配置自动化脚本，编译时自动生成 C++ 网络源码。

### 4.1 编译

```bash
# 回到工作空间根目录（如 ~/agv_ws）
source /opt/ros/humble/setup.bash
colcon build --packages-select agv_calib_brain --symlink-install
```

### 4.2 运行

```bash
source install/setup.bash
ros2 run agv_calib_brain brain_node
```