# AGV 路径跟踪项目

AGV（自动导引车）路径跟踪控制系统，包含路径规划、轨迹跟踪和 CAN 通信功能。

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

## 🚀 快速开始

### 新手入门
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) 编译项目

### CAN 通信示例
```bash
# 编译
./build_can.sh        # Linux/MSYS2
build_can.bat         # Windows

# 运行
cd build
./can_demo.exe
```

## 📂 项目结构

```
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++11 或更高版本
- MinGW-w64 (Windows) 或 GCC (Linux)
- CMake 3.10+ （可选）

### 编译 CAN 模块
```bash
# Windows
build_can.bat

# Linux/MSYS2
chmod +x build_can.sh
./build_can.sh
```

### 编译主程序
```bash
chmod +x build.sh
./build.sh
```

详细说明: [docs/guides/BUILD_INSTRUCTIONS.md](docs/guides/BUILD_INSTRUCTIONS.md)

## 📖 文档导航

### 🎯 快速参考
- [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) - 归档工具使用指南 ⭐

### 📘 使用指南
- [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) - 编译说明

### 🔌 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 协议规范

### 🛠️ 修复记录
- [docs/fixes/ALL_FIXES_SUMMARY.md](docs/fixes/ALL_FIXES_SUMMARY.md) - 所有修复总结
- [docs/fixes/FINAL_REPORT.md](docs/fixes/FINAL_REPORT.md) - 最终报告

### 🎨 自定义路径
- [docs/custom_path/README.md](docs/custom_path/README.md) - 自定义路径文档
- [docs/custom_path/QUICKSTART_CUSTOM_PATH.md](docs/custom_path/QUICKSTART_CUSTOM_PATH.md) - 快速开始

## 🎯 常见任务

### 运行 CAN 示例
```bash
cd build
./can_demo.exe

# 选择示例：
# 1. 基本 CAN 通信测试
# 2. AGV 速度控制
# 3. CAN 总线监控
# 4. 周期性发送和接收
```

### AGV 速度控制示例
```cpp
#include "can/CANController.h"

CANController can;
can.Initialize(0x00, 0x1C, 0);  // 500Kbps

// 发送速度控制命令
BYTE data[8] = {0x10, 0, 100, 0, 100, 0, 0, 0};  // 左右轮 100 RPM
can.SendStandardFrame(0x200, data, 8);
```

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

std::vector<VCI_CAN_OBJ> frames;
while (running) {
    can.Receive(frames, 100);
    // 处理接收到的数据
}
```

## 📊 项目统计

- **源代码文件**: 10+ 个 C++ 源文件
- **文档文件**: 30+ 个 Markdown/文本文档
- **模块数量**: 3 个主要模块（路径跟踪、CAN 通信、自定义路径）
- **示例程序**: 4+ 个完整示例

## 🔗 相关链接

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

## 📝 更新日志

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

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

### 之前更新
- ✅ 实现 CAN 通信模块
- ✅ 添加 AGV 控制示例
- ✅ 修复路径跟踪问题
- ✅ 添加自定义路径功能

详细修复记录: [docs/fixes/](docs/fixes/)

## 🤝 贡献

欢迎贡献代码和文档！

## 📄 许可证

本项目仅供学习和研究使用。

---

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

**快速参考**:
- 📖 [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
- 📁 [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)
- 🚀 [docs/guides/QUICK_START.md](docs/guides/QUICK_START.md)
