# AGV 路径跟踪与控制系统

一个完整的 AGV（自动导引车）路径跟踪与控制系统，提供路径规划、轨迹跟踪、Curtis 电机控制和 Qt 可视化界面。

## 项目概述

本项目实现了一套完整的 AGV 控制系统，包括：
- **路径规划**：支持圆形、直线和自定义路径
- **轨迹跟踪**：Pure Pursuit 和 Stanley 算法
- **硬件控制**：Curtis 电机控制器 CAN 通信
- **可视化**：Qt6 图形界面和控制台界面

## 主要功能

### 1. 路径生成
- **预定义路径**：圆形路径、直线路径
- **自定义路径**：通过 CSV 文件导入任意路径点
- **平滑路径**：使用三次样条插值生成平滑轨迹

### 2. 路径跟踪算法
- **Pure Pursuit**：前视距离控制，适合平滑路径
- **Stanley**：横向误差与航向误差结合，适合精确跟踪

### 3. Curtis 电机控制
- **CAN 通信**：支持 USB-CAN 设备（USBCAN-2A/2C、CANalyst-II）
- **速度控制**：前进/后退速度控制
- **转向控制**：左转/右转控制
- **安全保护**：紧急停止和安全限制

### 4. 可视化界面
- **Qt6 GUI**：实时路径和轨迹可视化
- **参数调节**：动态调整控制参数
- **数据分析**：跟踪误差和控制输出显示

## 项目结构

```
agv-control-slam/
├── include/              # 头文件
│   ├── agv_model.h       # AGV 运动模型
│   ├── path_curve.h      # 路径曲线
│   ├── path_tracker.h    # 路径跟踪器
│   ├── control_generator.h  # 控制生成器
│   └── can/              # CAN 控制相关
│       ├── CANController.h
│       └── CurtisMotorController.h
├── src/                  # 源文件
│   └── control/          # 控制算法实现
│       ├── agv_model.cpp
│       ├── path_curve.cpp
│       ├── path_curve_custom.cpp
│       ├── path_tracker.cpp
│       ├── control_generator.cpp
│       └── can/          # CAN 通信实现
├── examples/             # 示例程序
│   ├── demo.cpp          # 基本演示
│   ├── gui_demo.cpp      # 控制台 GUI
│   ├── qt_gui_demo.cpp   # Qt 图形界面
│   ├── curtis_demo.cpp   # Curtis 键盘控制
│   ├── curtis_path_tracking_demo.cpp  # Curtis 路径跟踪
│   ├── generate_data.cpp      # 数据生成工具
│   └── generate_smooth_path.cpp  # 平滑路径生成
├── lib/                  # 第三方库
│   └── ControlCAN.lib/dll  # USB-CAN 接口库
├── scripts/              # 工具脚本
├── build.sh              # Linux/MSYS2 构建脚本
└── deploy_windows.sh     # Windows 部署脚本
```

## 快速开始

### 环境要求

- **编译器**：GCC 7.0+ 或 MSVC 2017+ 或 MinGW-w64
- **CMake**：3.10 或更高版本
- **Qt6**：6.0 或更高版本（用于 GUI）
- **Python 3**：用于可视化工具（可选）

### Windows 编译（推荐）

使用 MSYS2/MinGW-w64 环境：

```bash
# 1. 安装依赖
pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-gcc mingw-w64-x86_64-qt6

# 2. 构建项目
./build.sh

# 3. 运行示例
cd build
./agv_demo.exe              # 基本演示
./agv_gui.exe               # 控制台 GUI
./agv_qt_gui.exe            # Qt 图形界面
```

### 部署可执行程序

```bash
# 打包 Qt 应用及其依赖
./deploy_windows.sh

# 可执行文件将在 release_package/ 目录中
cd release_package
./agv_qt_gui.exe
```

### Linux 编译

```bash
# 1. 安装依赖
sudo apt-get install cmake g++ qt6-base-dev

# 2. 构建项目
mkdir build && cd build
cmake ..
make

# 3. 运行示例
./agv_demo
./agv_qt_gui
```

## 使用示例

### 1. 基本路径跟踪

```cpp
#include "path_tracker.h"

// 创建 AGV 模型
AGVModel model(2.0, 1.0);  // 轴距 2.0m, 最大转向角 1.0 rad

// 创建路径跟踪器
PathTracker tracker(model);

// 生成圆形路径
PathCurve path = PathCurve::generateCircularPath(5.0, 100);
tracker.setReferencePath(path);

// 设置初始状态
AGVModel::State initial_state(0, -5, M_PI/2, 0);
tracker.setInitialState(initial_state);

// 生成控制序列
tracker.generateControlSequence("pure_pursuit", 0.1, 10.0, 1.0);

// 导出结果
tracker.exportToCSV("output.csv");
```

### 2. 自定义路径跟踪

```cpp
// 从 CSV 文件加载路径
PathCurve custom_path = PathCurve::loadFromCSV("custom_path.csv");
tracker.setReferencePath(custom_path);

// 使用 Stanley 算法
tracker.generateControlSequence("stanley", 0.1, 10.0, 1.0);
```

### 3. Curtis 电机控制

```cpp
#include "can/CurtisMotorController.h"

// 初始化控制器
CurtisMotorController controller;
controller.initialize(0, 0, 0, 500000);  // CAN0, 500kbps

// 控制车辆
controller.forward(30);      // 前进，速度 30%
controller.turnLeft(50);     // 左转，转向 50%
controller.brake();          // 刹车
controller.emergencyStop();  // 紧急停止
```

## 核心算法

### Pure Pursuit 算法
- **前视距离**：根据速度动态调整
- **转向计算**：基于前视点的几何关系
- **适用场景**：平滑路径跟踪

### Stanley 算法
- **横向误差**：垂直于路径的偏差
- **航向误差**：车辆朝向与路径切线的偏差
- **适用场景**：精确路径跟踪和低速场景

## 可视化工具

### Qt GUI 界面
- 实时路径和轨迹显示
- 参数动态调整
- CSV 文件导入/导出
- 动画播放控制

### Python 可视化

```bash
python visualize.py output.csv
```

## CAN 通信配置

### 硬件支持
- USBCAN-2A/2C
- CANalyst-II
- MiniPCIe-CAN

### 库文件配置
将 `ControlCAN.dll` 和 `ControlCAN.lib` 放置在 `lib/` 目录。详见 `lib/README.md`。

## 开发文档

详细的开发文档和 API 参考，请查看 `docs/` 目录：
- API 参考手册
- 开发指南
- 算法说明

## 更新日志

### 2025-11-27
- 项目文档重新整理
- 清理过时文档
- 更新项目结构说明

### 2025-11-27（早期）
- Qt6 升级完成
- 部署脚本优化
- 构建系统改进

## 许可证

本项目采用 MIT 许可证。

## 贡献

欢迎提交 Issue 和 Pull Request。

## 作者

AGV 控制系统开发团队

---

**最后更新**: 2025-11-27
**项目状态**: 活跃开发中