Loongson_2k0300_SmartCar/2K0300智能车项目代码文档.md

# 2K0300智能车项目代码文档

## 项目概述
该项目是一个智能车控制系统，包含摄像头图像处理、电机控制、编码器反馈、PID 控制、帧缓冲区显示等功能。项目使用 C++ 编写，依赖 OpenCV 库进行图像处理，并通过 CMake 进行构建。

## 目录结构
- **CMakeLists.txt**: 项目的构建配置文件。
- **cross.cmake**: 交叉编译工具链配置文件。
- **src/**: 库文件目录，包含摄像头、电机控制、PID 控制等模块的实现。
- **lib/**: 库文件目录，包含摄像头、电机控制、PID 控制等模块的头文件。
- **main/**: 主程序目录。
- **xx_demo/**: 示例程序目录，包含多个演示程序。

---

## 主要模块介绍

### 1. 摄像头模块 (`camera.cpp`, `camera.h`)
摄像头模块负责初始化摄像头设备、捕获图像并进行处理。主要功能包括：
- **摄像头初始化**: 打开摄像头设备，设置分辨率、帧率等参数。
- **图像捕获**: 通过 OpenCV 捕获摄像头图像，并进行缩放、二值化等处理。
- **帧缓冲区显示**: 将处理后的图像显示到帧缓冲区设备（如 LCD 屏幕）。
- **图像保存**: 支持将捕获的图像保存为文件。

#### 关键函数：
- `CameraInit(uint8_t camera_id, double dest_fps, int width, int height)`: 初始化摄像头设备。
- `CameraHandler(void)`: 处理摄像头捕获的图像。
- `streamCapture(void)`: 持续捕获摄像头图像，存储到全局变量`cv::Mat pubframe`中，`std::mutex frameMutex`为互斥锁。
- `cameraDeInit(void)`: 释放摄像头资源。

---

### 2. 电机控制模块 (`MotorController.cpp`, `MotorController.h`)
电机控制模块负责控制智能车的电机，支持 PWM 调速和方向控制。主要功能包括：
- **电机初始化**: 初始化 PWM 控制器和 GPIO 引脚。
- **速度控制**: 通过 PID 控制器调节电机速度。
- **方向控制**: 控制电机的正反转。

#### 关键函数：
- `MotorController(int pwmchip, int pwmnum, int gpioNum, unsigned int period_ns, double kp, double ki, double kd, double targetSpeed, int encoder_pwmNum, int encoder_gpioNum, int encoder_dir_)`: 构造函数，初始化电机控制器，`encoder_dir_`取值为1/-1，在更新速度时自动乘算到编码器速度上。
- `updateSpeed(void)`: 从编码器更新当前速度。
- `updateTarget(int speed)`: 设置目标速度。
- `updateduty(double dutyCycle)`: 设置 PWM 占空比，为负值时反转。

---

### 3. PID 控制模块 (`PIDController.cpp`, `PIDController.h`)
PID 控制模块实现了位置式和增量式 PID 控制器，用于电机速度和舵机角度的精确控制。主要功能包括：
- **PID 参数设置**: 支持动态调整比例、积分、微分参数。
- **控制模式切换**: 支持位置式和增量式 PID 控制。
- **输出限幅**: 防止输出值超出设定范围。
- **积分限幅**：放置积分项超出设定范围。

#### 关键函数：
- `PIDController(double kp, double ki, double kd, double target, PIDMode mode, double output_limit, double integral_limit)`: 构造函数，初始化 PID 参数。
- `update(double measured_value)`: 输入测量值，更新 PID 控制器输出。
- `setTarget(double target)`：设置PID控制器目标值。
- `setPID(double kp, double ki, double kd)`: 设置 PID 参数。
- `setMode(PIDMode mode)`: 设置控制模式（位置式或增量式）。

---

### 4. 编码器模块 (`encoder.cpp`, `encoder.h`)
编码器模块用于读取电机编码器的脉冲信号，计算电机转速。主要功能包括：
- **编码器初始化**: 映射寄存器，初始化编码器设备。
- **脉冲计数**: 读取编码器脉冲信号，计算转速。
- **方向检测**: 通过 GPIO 读取电机方向。

#### 关键函数：
- `ENCODER(int pwmNum, int gpioNum)`: 构造函数，初始化编码器。
- `pulse_counter_update(void)`: 更新脉冲计数并计算转速（单位：rps）。

---

### 5. 帧缓冲区模块 (`frame_buffer.cpp`, `frame_buffer.h`)
帧缓冲区模块负责将 OpenCV 图像转换为 RGB565 格式并显示到帧缓冲区设备（如 LCD 屏幕）。主要功能包括：
- **图像格式转换**: 将 OpenCV 的 RGB888 图像转换为 RGB565 格式。
- **帧缓冲区写入**: 将转换后的图像写入帧缓冲区设备。

#### 关键函数：
- `convertMatToRGB565(const cv::Mat &frame, uint16_t *buffer, int width, int height)`: 将 OpenCV 图像转换为 RGB565 格式，写入到buffer中。
- `convertRGBToRGB565(uint8_t r, uint8_t g, uint8_t b)`: 将 RGB888 颜色值转换为 RGB565 格式。

---

### 6. GPIO 模块 (`GPIO.cpp`, `GPIO.h`)
GPIO 模块用于控制 GPIO 引脚，支持方向设置、值读取和写入。主要功能包括：
- **GPIO 初始化**: 导出 GPIO 引脚并设置方向。
- **值读写**: 读取或写入 GPIO 引脚的值。

#### 关键函数：
- `GPIO(int gpioNum)`: 构造函数，初始化 GPIO 引脚。
- `setDirection(const std::string &direction)`: 设置 GPIO 引脚方向。
- `setValue(bool value)`: 设置 GPIO 引脚值。
- `readValue(void)`: 读取 GPIO 引脚值。

---

### 7. PWM 控制模块 (`PwmController.cpp`, `PwmController.h`)
PWM 控制模块用于生成 PWM 信号，控制电机速度和舵机角度。主要功能包括：
- **PWM 初始化**: 初始化 PWM 设备。
- **周期和占空比设置**: 设置 PWM 信号的周期和占空比。
- **PWM 启用/禁用**: 控制 PWM 信号的输出。

#### 关键函数：
- `PwmController(int pwmchip, int pwmnum)`: 构造函数，初始化 PWM 设备。
- `setPeriod(unsigned int period_ns)`: 设置 PWM 周期。
- `setDutyCycle(unsigned int duty_cycle_ns)`: 设置 PWM 占空比。
- `enable(void)`: 启用 PWM 输出。
- `disable(void)`: 禁用 PWM 输出。

---

### 8. 图像处理模块 (`image_cv.cpp`, `image_cv.h`)
图像处理模块负责对摄像头捕获的图像进行处理，提取赛道边缘和中线。主要功能包括：
- **图像缩放**: 将图像缩放到指定大小。
- **二值化处理**: 将图像转换为二值图像。
- **边缘提取**: 提取赛道的左右边缘和中线。

#### 关键函数：
- `image_main(void)`: 主图像处理函数，执行缩放、二值化和边缘提取。

---

### 9. 全局变量模块 (`global.cpp`, `global.h`)
全局变量模块定义了项目中使用的全局变量和工具函数。主要功能包括：
- **文件读取**: 从文件中读取双精度值和标志。
- **全局变量**: 定义 PID 参数、目标速度等全局变量。

#### 关键函数：
- `readDoubleFromFile(const std::string &filename)`: 从文件中读取双精度值。
- `readFlag(const std::string &filename)`: 从文件中读取标志。

---

### 10. 定时器模块 (`Timer.cpp`, `Timer.h`)
定时器模块用于创建定时任务，定期执行指定函数。主要功能包括：
- **定时任务创建**: 创建定时任务并启动。
- **定时任务停止**: 停止定时任务。

#### 关键函数：
- `Timer(int interval_ms, std::function<void()> task)`: 构造函数，初始化定时器。
- `start(void)`: 启动定时任务。
- `stop(void)`: 停止定时任务。

---

## 示例程序

### 1. 编码器测试程序 (`encoder_demo.cpp`)
该程序用于测试编码器模块，读取编码器脉冲信号并输出转速。

### 2. 帧缓冲区测试程序 (`framebuffer_demo.cpp`)
该程序用于测试帧缓冲区模块，绘制图形并显示到帧缓冲区设备。

### 3. OpenCV 测试程序 (`opencv_demo1.cpp`, `opencv_demo2.cpp`, `opencv_demo3.cpp`)
这些程序用于测试 OpenCV 图像处理功能，分别为显示摄像头图像、显示旋转立方体、目标匹配。
- `opencv_demo3.cpp`在运行时依赖`opencv/share/opencv4/haarcascades/haarcascade_frontalface_default.xml`，需要在`opencv`文件夹同一目录下运行。

### 4. 遥控车演示程序 (`demo1.cpp`)
该程序通过键盘控制智能车的运动，支持前进、后退、左转、右转。

---

## 构建项目
使用 CMake 构建项目：
```bash
mkdir build
cd build
cmake ..
make
```