542 lines
9.0 KiB
Markdown
542 lines
9.0 KiB
Markdown
# 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
|