# 🚙 AGV 车端底层执行代理

**系统**: Windows 原生 C++ | **通信**: gRPC Server over Wi-Fi 6 | **工作流**: VS Code + CMake + vcpkg

> 运行在 AGV 车端 Windows 系统，作为 gRPC Server 监听外部指令，开放底层电机控制权并高频上报遥测数据。

**核心理念**: 全面摒弃臃肿的 Visual Studio IDE，采用 **VS Code + CMake Tools + vcpkg** 轻量化工作流。

---

## 📋 目录

1. [环境准备 (vcpkg)](#1-环境准备-极度重要基于-vcpkg)
2. [VS Code 配置](#2-vs-code-核心插件与-cmake-绑定)
3. [手动翻译 .proto 文件](#3-手动翻译-proto-源码保持工程整洁)
4. [编译与运行](#4-编译与运行)
5. [⚠️ 跨平台联调深坑](#️-5-跨平台-wi-fi-6-联调两大夺命深坑实车联调必看)

---

## 1. 环境准备 (极度重要：基于 vcpkg！)

> ⚠️ **警告**: Windows 下强行源码编译 gRPC 极其痛苦（无尽的 OpenSSL/zlib 冲突），**必须使用微软官方 `vcpkg` 包管理器！**

### 1.1 前置安装

| 工具 | 安装要求 |
|-----|---------|
| **CMake for Windows** | 安装时务必勾选 "Add CMake to the system PATH" |
| **Visual Studio Build Tools** | 仅勾选 **"使用 C++ 的桌面开发"** 工作负载，获取 `cl.exe` 即可<br>❌ 不要安装完整的 VS IDE |

### 1.2 安装 vcpkg 与 gRPC

以**管理员身份**打开 PowerShell（建议在 `C:\` 根目录操作，路径避免中文和空格）：

```powershell
cd C:\
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

# 一键编译安装 64 位 Windows 版 gRPC 和 Protobuf
# (需从源码编译底层依赖，视 CPU 性能约 15~30 分钟，请耐心等待)
.\vcpkg install grpc:x64-windows protobuf:x64-windows
```

---

## 2. VS Code 核心插件与 CMake 绑定

### 2.1 安装插件

在 VS Code 扩展商店安装 2 个核心插件：

| 插件 | 开发者 | 用途 |
|-----|--------|------|
| **C/C++** | Microsoft | IntelliSense 与调试 |
| **CMake Tools** | Microsoft | 构建的灵魂！ |

### 2.2 配置 vcpkg 工具链

在工程根目录新建 `.vscode/settings.json`，注入工具链：

```json
{
    "cmake.configureArgs": [
        "-DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake"
    ]
}
```

> 💡 **注意**: 路径替换为你实际的 vcpkg 位置，**必须使用正斜杠 `/`**。

---

## 3. 手动翻译 `.proto` 源码 (保持工程整洁)

为避免 Windows 端 CMake 路径宏在不同电脑上报错，建议**手动翻译 `.proto` 文件**，将生成的 C++ 源码直接放入代码目录编译。

在存放 `.proto` 文件的目录下执行：

```powershell
$vcpkg = "C:\vcpkg\packages"
$protoc = "$vcpkg\protobuf_x64-windows\tools\protobuf\protoc.exe"
$grpc_plugin = "$vcpkg\grpc_x64-windows\tools\grpc\grpc_cpp_plugin.exe"

# 翻译控制契约
& $protoc -I="." --cpp_out="." --grpc_out="." --plugin=protoc-gen-grpc="$grpc_plugin" agv_calib_control.proto

# 翻译底盘契约
& $protoc -I="." --cpp_out="." --grpc_out="." --plugin=protoc-gen-grpc="$grpc_plugin" agv_calib_chassis.proto
```

**输出文件**: 执行后生成 8 个文件（`.pb.cc` / `.grpc.pb.cc` 及其头文件）。

**工程组织**: 将这些文件与你的 `main.cpp` 放在同一 `src/` 文件夹下，在 `CMakeLists.txt` 中正常 `add_executable` 即可。

---

## 4. 编译与运行

| 步骤 | 操作 | 说明 |
|-----|------|------|
| **1. 选择编译器** | 点击 VS Code 底部 `[No Kit Selected]` | 选择含 **`amd64`** 字样的 Visual Studio Release 编译器（64 位 MSVC） |
| **2. 编译** | 点击底部 **`[Build]`** 或按 `F7` | CMake 自动利用 vcpkg 找到 gRPC 库并编译 |
| **3. 运行** | 点击底部 **`[▶]` (Launch)** | 启动服务端程序，等待 Ubuntu 大脑连接 |

---

## 🚨 5. 跨平台 Wi-Fi 6 联调两大"夺命深坑"（实车联调必看！）

> 若 Ubuntu 端通过 Wi-Fi 连不上 Windows 车端（报错 `RPC Failed 14` 或 `Timeout`），**100% 是以下两个原因，不要怀疑代码！**

### 💣 深坑一：IP 绑定自嗨 (`localhost` 陷阱)

**问题**: `ServerBuilder` 监听地址错误导致外部无法连入。

**解决方案**:

```cpp
// ✅ 正确：允许任何物理网卡的外部网络包连入
builder.AddListeningPort("0.0.0.0:50051", grpc::InsecureServerCredentials());

// ❌ 错误：仅允许本机访问，外部 Linux 物理机永远无法连入
builder.AddListeningPort("127.0.0.1:50051", ...);  // 或 localhost
```

### 💣 深坑二：Windows 防火墙无情拦截

**问题**: Windows Defender 默认丢弃所有来自外部 Wi-Fi 的 TCP 请求。

**解决方案**: 以**管理员权限**打开 PowerShell，添加入站规则：

```powershell
New-NetFirewallRule -DisplayName "AGV_gRPC_Port" -Direction Inbound -LocalPort 50051 -Protocol TCP -Action Allow
```

> 💡 **研发提效建议**: 在封闭车间 Wi-Fi 局域网内实车联调时，建议直接去 Windows 控制面板**彻底关闭"专用网络"和"公用网络"的防火墙**，节约排错时间。