initial

2025-11-27 15:20:21 +08:00
parent 3e2884ea53
commit 7b6c956b6a
49 changed files with 2042 additions and 10294 deletions
--- a/README.md
+++ b/README.md
@@ -1,247 +1,249 @@
-# AGV 路径跟踪项目
+# AGV 路径跟踪与控制系统

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

-> **📁 项目已重新整理！** 所有文件已按模块分类到合理的目录结构中。
->
-> - 📂 **源代码** → `src/`
-> - 📂 **文档** → `docs/`
-> - 📂 **头文件** → `include/`
-> - 📂 **库文件** → `lib/`
->
-> 详细信息请查看 [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) 或 [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
+## 项目概述

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

-### 新手入门
-1. 📖 阅读 [docs/guides/START_HERE.txt](docs/guides/START_HERE.txt)
-2. 📖 查看 [docs/guides/QUICK_START.md](docs/guides/QUICK_START.md)
-3. 🔧 按照 [docs/guides/BUILD_INSTRUCTIONS.md](docs/guides/BUILD_INSTRUCTIONS.md) 编译项目
+## 主要功能
+
+### 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 环境：

-### CAN 通信示例
 ```bash
-# 编译
-./build_can.sh        # Linux/MSYS2
-build_can.bat         # Windows
+# 1. 安装依赖
+pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-gcc mingw-w64-x86_64-qt6

-# 运行
+# 2. 构建项目
+./build.sh
+
+# 3. 运行示例
 cd build
-./can_demo.exe
+./agv_demo.exe              # 基本演示
+./agv_gui.exe               # 控制台 GUI
+./agv_qt_gui.exe            # Qt 图形界面
 ```

-## 📂 项目结构
+### 部署可执行程序

-```
-agv_path_tracking/
-├── src/              # 源代码
-│   ├── can/         # CAN 通信模块
-│   └── tests/       # 测试代码
-├── include/          # 头文件
-│   └── can/         # CAN 头文件
-├── docs/            # 文档
-│   ├── can/         # CAN 文档
-│   ├── guides/      # 使用指南
-│   ├── fixes/       # 修复记录
-│   └── protocol/    # 协议文档
-├── lib/             # 库文件
-└── build/           # 构建输出
-```
-
-详细结构请查看 [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)
-
-## 📚 主要功能
-
-### 1. CAN 通信模块
- ✅ CAN 设备控制（USBCAN-2A/2C）
- ✅ 数据收发管理
- ✅ AGV 速度控制
- ✅ 多种工作模式（正常/只听/自发自收）
-
-**文档**: [docs/can/CAN_README.md](docs/can/CAN_README.md)
-
-### 2. 路径跟踪系统
- ✅ 路径曲线生成
- ✅ 轨迹跟踪算法
- ✅ AGV 运动学模型
- ✅ 控制量生成
-
-**文档**: [docs/guides/TRACKING_TEST_GUIDE.md](docs/guides/TRACKING_TEST_GUIDE.md)
-
-### 3. 自定义路径
- ✅ CSV 路径加载
- ✅ 平滑路径生成
- ✅ QT 图形界面
-
-**文档**: [docs/guides/CUSTOM_PATH_README.md](docs/guides/CUSTOM_PATH_README.md)
-
-## 🔧 编译说明
-
-### 系统要求
- C++17 或更高版本
- MinGW-w64 (Windows) 或 GCC (Linux)
- CMake 3.10+
- Qt6 6.x (用于 GUI 程序)
-
-### Qt6 GUI 编译（推荐）
 ```bash
-# 1. 清理构建目录
-cd build && rm -rf *
+# 打包 Qt 应用及其依赖
+./deploy_windows.sh

-# 2. 配置 CMake（使用 MinGW + Qt6）
-cmake -G "MinGW Makefiles" \
-  -DCMAKE_PREFIX_PATH=C:/Qt/6.10.1/mingw_64 \
-  -DCMAKE_C_COMPILER=C:/Qt/Tools/mingw1310_64/bin/gcc.exe \
-  -DCMAKE_CXX_COMPILER=C:/Qt/Tools/mingw1310_64/bin/g++.exe \
-  -DCMAKE_MAKE_PROGRAM=C:/Qt/Tools/mingw1310_64/bin/mingw32-make.exe ..
-
-# 3. 编译
-cmake --build . -j4
-
-# 4. 运行 GUI
+# 可执行文件将在 release_package/ 目录中
+cd release_package
 ./agv_qt_gui.exe
 ```

-### 编译 CAN 模块
+### Linux 编译
+
 ```bash
-# Windows
-build_can.bat
+# 1. 安装依赖
+sudo apt-get install cmake g++ qt6-base-dev

-# Linux/MSYS2
-chmod +x build_can.sh
-./build_can.sh
+# 2. 构建项目
+mkdir build && cd build
+cmake ..
+make
+
+# 3. 运行示例
+./agv_demo
+./agv_qt_gui
 ```

-详细说明: [docs/guides/BUILD_INSTRUCTIONS.md](docs/guides/BUILD_INSTRUCTIONS.md)
+## 使用示例

-### Qt6 部署
-部署 Qt6 GUI 应用程序到其他计算机: [docs/guides/QT6_DEPLOYMENT_GUIDE.md](docs/guides/QT6_DEPLOYMENT_GUIDE.md)
+### 1. 基本路径跟踪

-## 📖 文档导航
+```cpp
+#include "path_tracker.h"

-### 🎯 快速参考
- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - 快速参考指南
- [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) - 完整项目结构
- [FILE_ORGANIZATION.md](FILE_ORGANIZATION.md) - 文件组织规范 ⭐
- [ARCHIVE_USAGE_GUIDE.md](ARCHIVE_USAGE_GUIDE.md) - 归档工具使用指南 ⭐
+// 创建 AGV 模型
+AGVModel model(2.0, 1.0);  // 轴距 2.0m, 最大转向角 1.0 rad

-### 📘 使用指南
- [docs/guides/START_HERE.txt](docs/guides/START_HERE.txt) - 新手入门
- [docs/guides/QUICK_START.md](docs/guides/QUICK_START.md) - 快速开始
- [docs/guides/BUILD_INSTRUCTIONS.md](docs/guides/BUILD_INSTRUCTIONS.md) - 编译说明
- [docs/guides/QT6_DEPLOYMENT_GUIDE.md](docs/guides/QT6_DEPLOYMENT_GUIDE.md) - Qt6 部署指南 ⭐
- [docs/QT6_UPGRADE_SUMMARY.md](docs/QT6_UPGRADE_SUMMARY.md) - Qt6 升级总结 ⭐
+// 创建路径跟踪器
+PathTracker tracker(model);

-### 🔌 CAN 通信
- [docs/can/CAN_README.md](docs/can/CAN_README.md) - CAN 使用说明
- [docs/can/CAN_API_Reference.cpp](docs/can/CAN_API_Reference.cpp) - API 快速参考
- [docs/protocol/CAN_Protocol.pdf](docs/protocol/CAN_Protocol.pdf) - CAN 协议规范
+// 生成圆形路径
+PathCurve path = PathCurve::generateCircularPath(5.0, 100);
+tracker.setReferencePath(path);

-### 🛠️ 修复记录
- [docs/fixes/ALL_FIXES_SUMMARY.md](docs/fixes/ALL_FIXES_SUMMARY.md) - 所有修复总结
- [docs/fixes/FINAL_REPORT.md](docs/fixes/FINAL_REPORT.md) - 最终报告
+// 设置初始状态
+AGVModel::State initial_state(0, -5, M_PI/2, 0);
+tracker.setInitialState(initial_state);

-### 🎨 自定义路径
- [docs/custom_path/README.md](docs/custom_path/README.md) - 自定义路径文档
- [docs/custom_path/QUICKSTART_CUSTOM_PATH.md](docs/custom_path/QUICKSTART_CUSTOM_PATH.md) - 快速开始
+// 生成控制序列
+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 可视化

-### 运行 CAN 示例
 ```bash
-cd build
-./can_demo.exe
-
-# 选择示例：
-# 1. 基本 CAN 通信测试
-# 2. AGV 速度控制
-# 3. CAN 总线监控
-# 4. 周期性发送和接收
+python visualize.py output.csv
 ```

-### AGV 速度控制示例
-```cpp
-#include "can/CANController.h"
+## CAN 通信配置

-CANController can;
-can.Initialize(0x00, 0x1C, 0);  // 500Kbps
+### 硬件支持
+- USBCAN-2A/2C
+- CANalyst-II
+- MiniPCIe-CAN

-// 发送速度控制命令
-BYTE data[8] = {0x10, 0, 100, 0, 100, 0, 0, 0};  // 左右轮 100 RPM
-can.SendStandardFrame(0x200, data, 8);
-```
+### 库文件配置
+将 `ControlCAN.dll` 和 `ControlCAN.lib` 放置在 `lib/` 目录。详见 `lib/README.md`。

-### 监控 CAN 总线
-```cpp
-// 只听模式（不影响总线）
-can.Initialize(0x00, 0x1C, 1);
+## 开发文档

-std::vector<VCI_CAN_OBJ> frames;
-while (running) {
-    can.Receive(frames, 100);
-    // 处理接收到的数据
-}
-```
+详细的开发文档和 API 参考，请查看 `docs/` 目录：
+- API 参考手册
+- 开发指南
+- 算法说明

-## 📊 项目统计
+## 更新日志

- **源代码文件**: 10+ 个 C++ 源文件
- **文档文件**: 30+ 个 Markdown/文本文档
- **模块数量**: 3 个主要模块（路径跟踪、CAN 通信、自定义路径）
- **示例程序**: 4+ 个完整示例
+### 2025-11-27
+- 项目文档重新整理
+- 清理过时文档
+- 更新项目结构说明

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

- CAN 设备驱动: ControlCAN (USBCAN-2A/2C)
- 编译工具: MinGW-w64, GCC
- 构建系统: CMake, Shell Scripts
+## 许可证

-## 📝 更新日志
+本项目采用 MIT 许可证。

-### 2025-11-27 - Qt6 升级
- ✅ 从 Qt5 升级到 Qt6.10.1
- ✅ 更新 CMakeLists.txt 配置
- ✅ 配置 MinGW 13.1.0 编译器
- ✅ 更新所有相关文档
- ✅ 创建 Qt6 部署指南
+## 贡献

-### 2025-11-15 - 文件组织规范
- ✅ 创建文件组织和归档配置系统
- ✅ 添加Bug修复归档脚本
- ✅ 添加功能更新归档脚本
- ✅ 添加版本发布脚本
- ✅ 创建文档模板系统
- ✅ 编写详细的使用指南
+欢迎提交 Issue 和 Pull Request。

-### 2025-11-14 - 项目重组
- ✅ 重新组织项目文件结构
- ✅ 文档归类到 `docs/` 目录
- ✅ 代码归类到 `src/` 目录
- ✅ 头文件复制到 `include/` 目录
- ✅ 更新所有编译脚本
- ✅ 创建项目结构文档
+## 作者

-### 之前更新
- ✅ 实现 CAN 通信模块
- ✅ 添加 AGV 控制示例
- ✅ 修复路径跟踪问题
- ✅ 添加自定义路径功能
-
-详细修复记录: [docs/fixes/](docs/fixes/)
-
-## 🤝 贡献
-
-欢迎贡献代码和文档！
-
-## 📄 许可证
-
-本项目仅供学习和研究使用。
+AGV 控制系统开发团队

 ---

-**最后更新**: 2025-11-14
+**最后更新**: 2025-11-27
 **项目状态**: 活跃开发中
-
-**快速参考**:
- 📖 [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
- 📁 [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)
- 🚀 [docs/guides/QUICK_START.md](docs/guides/QUICK_START.md)