initial

docs/API.md

@@ -0,0 +1,541 @@
+# API 参考手册
+
+本文档提供 AGV 路径跟踪与控制系统的详细 API 说明。
+
+## 目录
+
+- [核心类](#核心类)
+  - [AGVModel](#agvmodel)
+  - [PathCurve](#pathcurve)
+  - [PathTracker](#pathtracker)
+  - [ControlGenerator](#controlgenerator)
+- [CAN 通信](#can-通信)
+  - [CurtisMotorController](#curtismotorcontroller)
+  - [CANController](#cancontroller)
+
+---
+
+## 核心类
+
+### AGVModel
+
+AGV 运动学模型类，实现阿克曼转向模型。
+
+#### 构造函数
+
+```cpp
+AGVModel(double wheelbase, double max_steering_angle)
+```
+
+**参数**：
+- `wheelbase`: 轴距（米）
+- `max_steering_angle`: 最大转向角（弧度）
+
+#### 主要方法
+
+##### setState
+
+```cpp
+void setState(const State& state)
+```
+
+设置 AGV 当前状态。
+
+**参数**：
+- `state`: 包含 x, y, theta, v 的状态结构体
+
+##### step
+
+```cpp
+State step(double v, double delta, double dt) const
+```
+
+执行一步运动学仿真。
+
+**参数**：
+- `v`: 速度（m/s）
+- `delta`: 转向角（弧度）
+- `dt`: 时间步长（秒）
+
+**返回值**：新的状态
+
+#### 状态结构
+
+```cpp
+struct State {
+    double x;      // x 坐标（米）
+    double y;      // y 坐标（米）
+    double theta;  // 航向角（弧度）
+    double v;      // 速度（m/s）
+}
+```
+
+---
+
+### PathCurve
+
+路径曲线类，表示 AGV 需要跟踪的参考路径。
+
+#### 静态工厂方法
+
+##### generateCircularPath
+
+```cpp
+static PathCurve generateCircularPath(double radius, int num_points)
+```
+
+生成圆形路径。
+
+**参数**：
+- `radius`: 半径（米）
+- `num_points`: 路径点数量
+
+**返回值**：PathCurve 对象
+
+##### generateStraightPath
+
+```cpp
+static PathCurve generateStraightPath(
+    double start_x, double start_y,
+    double end_x, double end_y,
+    int num_points
+)
+```
+
+生成直线路径。
+
+##### loadFromCSV
+
+```cpp
+static PathCurve loadFromCSV(const std::string& filename)
+```
+
+从 CSV 文件加载自定义路径。
+
+**CSV 格式**：
+```csv
+x,y
+0.0,0.0
+1.0,0.5
+2.0,1.0
+```
+
+#### 主要方法
+
+##### getPathPoints
+
+```cpp
+const std::vector<PathPoint>& getPathPoints() const
+```
+
+获取路径点列表。
+
+##### getClosestPoint
+
+```cpp
+PathPoint getClosestPoint(double x, double y, size_t& index) const
+```
+
+获取距离给定位置最近的路径点。
+
+**参数**：
+- `x, y`: 查询位置
+- `index`: 输出参数，最近点的索引
+
+**返回值**：最近的路径点
+
+---
+
+### PathTracker
+
+路径跟踪器类，整合模型、路径和控制算法。
+
+#### 构造函数
+
+```cpp
+explicit PathTracker(const AGVModel& model)
+```
+
+**参数**：
+- `model`: AGV 运动学模型
+
+#### 主要方法
+
+##### setReferencePath
+
+```cpp
+void setReferencePath(const PathCurve& path)
+```
+
+设置参考路径。
+
+##### setInitialState
+
+```cpp
+void setInitialState(const AGVModel::State& state)
+```
+
+设置初始状态。
+
+##### generateControlSequence
+
+```cpp
+bool generateControlSequence(
+    const std::string& algorithm = "pure_pursuit",
+    double dt = 0.1,
+    double horizon = 10.0,
+    double desired_velocity = 1.0
+)
+```
+
+生成控制序列。
+
+**参数**：
+- `algorithm`: 算法类型（"pure_pursuit" 或 "stanley"）
+- `dt`: 时间步长（秒）
+- `horizon`: 时域（秒）
+- `desired_velocity`: 期望速度（m/s）
+
+**返回值**：成功返回 true
+
+##### getControlSequence
+
+```cpp
+const ControlSequence& getControlSequence() const
+```
+
+获取生成的控制序列。
+
+##### exportToCSV
+
+```cpp
+void exportToCSV(const std::string& filename) const
+```
+
+导出跟踪结果到 CSV 文件。
+
+---
+
+### ControlGenerator
+
+控制生成器类，实现不同的路径跟踪算法。
+
+#### 主要方法
+
+##### purePursuit
+
+```cpp
+static double purePursuit(
+    const AGVModel::State& state,
+    const PathCurve& path,
+    double lookahead_distance
+)
+```
+
+Pure Pursuit 算法。
+
+**参数**：
+- `state`: 当前状态
+- `path`: 参考路径
+- `lookahead_distance`: 前视距离（米）
+
+**返回值**：转向角（弧度）
+
+##### stanley
+
+```cpp
+static double stanley(
+    const AGVModel::State& state,
+    const PathCurve& path,
+    double k = 1.0
+)
+```
+
+Stanley 算法。
+
+**参数**：
+- `state`: 当前状态
+- `path`: 参考路径
+- `k`: 增益参数
+
+**返回值**：转向角（弧度）
+
+---
+
+## CAN 通信
+
+### CurtisMotorController
+
+Curtis 电机控制器类，通过 CAN 通信控制电机。
+
+#### 主要方法
+
+##### initialize
+
+```cpp
+bool initialize(
+    int device_type,
+    int device_index,
+    int can_index,
+    int baudrate
+)
+```
+
+初始化 CAN 设备。
+
+**参数**：
+- `device_type`: 设备类型（通常为 0）
+- `device_index`: 设备索引（通常为 0）
+- `can_index`: CAN 通道索引（0 或 1）
+- `baudrate`: 波特率（如 500000 表示 500kbps）
+
+**返回值**：成功返回 true
+
+##### forward
+
+```cpp
+void forward(int speed_percentage)
+```
+
+前进控制。
+
+**参数**：
+- `speed_percentage`: 速度百分比（0-100）
+
+##### backward
+
+```cpp
+void backward(int speed_percentage)
+```
+
+后退控制。
+
+**参数**：
+- `speed_percentage`: 速度百分比（0-100）
+
+##### turnLeft
+
+```cpp
+void turnLeft(int angle_percentage)
+```
+
+左转控制。
+
+**参数**：
+- `angle_percentage`: 转向角百分比（0-100）
+
+##### turnRight
+
+```cpp
+void turnRight(int angle_percentage)
+```
+
+右转控制。
+
+**参数**：
+- `angle_percentage`: 转向角百分比（0-100）
+
+##### brake
+
+```cpp
+void brake()
+```
+
+刹车（停止所有运动）。
+
+##### emergencyStop
+
+```cpp
+void emergencyStop()
+```
+
+紧急停止。
+
+##### cleanup
+
+```cpp
+void cleanup()
+```
+
+清理并关闭 CAN 设备。
+
+---
+
+### CANController
+
+底层 CAN 控制器类，提供基本的 CAN 通信功能。
+
+#### 主要方法
+
+##### Initialize
+
+```cpp
+bool Initialize(int device_type, int device_index, int can_index)
+```
+
+初始化 CAN 设备。
+
+##### SendStandardFrame
+
+```cpp
+bool SendStandardFrame(unsigned int id, const BYTE* data, int len)
+```
+
+发送标准帧。
+
+**参数**：
+- `id`: CAN ID
+- `data`: 数据缓冲区
+- `len`: 数据长度（0-8）
+
+##### Receive
+
+```cpp
+int Receive(std::vector<VCI_CAN_OBJ>& frames, int timeout_ms = 100)
+```
+
+接收 CAN 帧。
+
+**参数**：
+- `frames`: 接收缓冲区
+- `timeout_ms`: 超时时间（毫秒）
+
+**返回值**：接收到的帧数量
+
+---
+
+## 数据结构
+
+### ControlSequence
+
+控制序列结构，存储路径跟踪结果。
+
+```cpp
+struct ControlSequence {
+    std::vector<AGVModel::State> predicted_states;  // 预测状态序列
+    std::vector<double> control_velocities;         // 控制速度序列
+    std::vector<double> control_steering;           // 控制转向角序列
+    std::vector<double> tracking_errors;            // 跟踪误差序列
+}
+```
+
+### PathPoint
+
+路径点结构。
+
+```cpp
+struct PathPoint {
+    double x;      // x 坐标
+    double y;      // y 坐标
+    double theta;  // 切线方向
+    double kappa;  // 曲率
+}
+```
+
+---
+
+## 使用示例
+
+### 完整的路径跟踪流程
+
+```cpp
+#include "path_tracker.h"
+#include <iostream>
+
+int main() {
+    // 1. 创建 AGV 模型
+    AGVModel model(2.0, 1.0);
+
+    // 2. 创建路径跟踪器
+    PathTracker tracker(model);
+
+    // 3. 生成或加载路径
+    PathCurve path = PathCurve::generateCircularPath(5.0, 100);
+    // 或从文件加载
+    // PathCurve path = PathCurve::loadFromCSV("path.csv");
+
+    tracker.setReferencePath(path);
+
+    // 4. 设置初始状态
+    AGVModel::State initial(0, -5, M_PI/2, 0);
+    tracker.setInitialState(initial);
+
+    // 5. 生成控制序列
+    if (!tracker.generateControlSequence("pure_pursuit", 0.1, 10.0, 1.0)) {
+        std::cerr << "Failed to generate control sequence" << std::endl;
+        return 1;
+    }
+
+    // 6. 导出结果
+    tracker.exportToCSV("output.csv");
+
+    // 7. 获取结果用于分析
+    const auto& sequence = tracker.getControlSequence();
+    std::cout << "Generated " << sequence.predicted_states.size()
+              << " control steps" << std::endl;
+
+    return 0;
+}
+```
+
+### Curtis 电机控制示例
+
+```cpp
+#include "can/CurtisMotorController.h"
+#include <iostream>
+#include <thread>
+#include <chrono>
+
+int main() {
+    CurtisMotorController controller;
+
+    // 初始化
+    if (!controller.initialize(0, 0, 0, 500000)) {
+        std::cerr << "Failed to initialize CAN" << std::endl;
+        return 1;
+    }
+
+    // 前进
+    controller.forward(30);
+    std::this_thread::sleep_for(std::chrono::seconds(2));
+
+    // 左转
+    controller.turnLeft(50);
+    std::this_thread::sleep_for(std::chrono::seconds(1));
+
+    // 停止
+    controller.brake();
+
+    // 清理
+    controller.cleanup();
+
+    return 0;
+}
+```
+
+---
+
+## 常见问题
+
+### 如何选择合适的算法？
+
+- **Pure Pursuit**：适合高速、平滑路径跟踪
+- **Stanley**：适合低速、高精度路径跟踪
+
+### 如何调整参数？
+
+- **lookahead_distance**：前视距离，通常为速度的 1-2 倍
+- **k（Stanley）**：增益参数，影响横向误差的响应速度
+- **dt**：时间步长，建议 0.05-0.1 秒
+- **desired_velocity**：期望速度，根据实际情况调整
+
+### CAN 通信失败怎么办？
+
+1. 检查硬件连接
+2. 确认 ControlCAN.dll 在正确路径
+3. 验证波特率设置
+4. 检查 CAN 设备驱动
+
+---
+
+**最后更新**: 2025-11-27