# 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