# embedded-pid-controller **Repository Path**: MagicBude/embedded-pid-controller ## Basic Information - **Project Name**: embedded-pid-controller - **Description**: 通用轻量级嵌入式PID控制器库，纯C实现，核心算法平台无关，接口易于适配各种单片机 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-22 - **Last Updated**: 2026-01-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Embedded PID Controller Library 通用轻量级嵌入式 PID 控制器库，纯 C 实现，核心算法平台无关，接口易于适配各种单片机。 [English](README_EN.md) | 简体中文 ## 特性 - ✅ **纯 C 实现** - 符合 C99 标准，无需 C++ 支持 - ✅ **平台无关** - 核心算法不依赖任何特定平台 - ✅ **轻量级** - 每个 PID 实例占用内存 < 64 字节 - ✅ **易移植** - 清晰的平台适配层接口 - ✅ **功能完整** - 支持位置式和增量式 PID - ✅ **高级特性** - 积分限幅、微分滤波、死区处理、抗积分饱和 - ✅ **易于使用** - 简洁的 API 设计 - ✅ **完整文档** - 从入门到精通的系统性文档 - ✅ **多平台示例** - STM32、ESP32、Arduino 示例代码 ## 快速开始 ### 基本使用 ```c #include "pid.h" /* 创建 PID 实例 */ pid_t pid; /* 初始化：Kp=1.0, Ki=0.1, Kd=0.05 */ pid_init(&pid, 1.0f, 0.1f, 0.05f); /* 设置输出限制 */ pid_set_output_limits(&pid, -100.0f, 100.0f); /* 在控制循环中使用 */ float setpoint = 100.0f; /* 目标值 */ float feedback = 80.0f; /* 当前值 */ float dt = 0.01f; /* 时间间隔（秒） */ float output; pid_compute(&pid, setpoint, feedback, dt, &output); /* 使用 output 控制你的系统 */ ``` ### 编译 ```bash # 使用 CMake mkdir build && cd build cmake .. make # 或使用 Makefile make ``` ## 项目结构 ``` embedded-pid-controller/ ├── include/ │ └── pid.h # 公共 API 头文件 ├── src/ │ ├── core/ │ │ ├── pid_core.h # 核心实现头文件 │ │ └── pid_core.c # 核心实现 │ └── platform/ # 平台适配层（可选） │ ├── template/ # 移植模板 │ ├── stm32/ # STM32 适配 │ ├── esp32/ # ESP32 适配 │ └── arduino/ # Arduino 适配 ├── examples/ │ ├── stm32/ # STM32 示例 │ ├── esp32/ # ESP32 示例 │ ├── arduino/ # Arduino 示例 │ └── simulation/ # PC 仿真示例 ├── docs/ # 详细文档 │ ├── tutorials/ # 教程系列（8篇） │ ├── guides/ # 开发指南 │ ├── reports/ # 测试报告 │ ├── scripts/ # 工具脚本 │ └── images/ # 图片资源 ├── test/ # 测试代码 ├── CMakeLists.txt # CMake 配置 ├── Makefile # Make 配置 ├── LICENSE # MIT 许可证 ├── CHANGELOG.md # 更新日志 ├── CONTRIBUTING.md # 贡献指南 └── README.md # 本文件 ``` ## 文档 详细文档请查看 [docs](docs/) 目录： ### 教程系列 - [PID 控制基础](docs/tutorials/01_PID控制基础.md) - 从零开始学习 PID 控制 - [PID 数学原理详解](docs/tutorials/02_PID数学原理详解.md) - 深入理解 PID 公式和理论 - [离散化实现技术](docs/tutorials/03_离散化实现技术.md) - 如何在单片机上实现 PID - [参数整定方法](docs/tutorials/04_参数整定方法.md) - 系统化的调参技巧 - [高级特性详解](docs/tutorials/05_高级特性详解.md) - 抗饱和、滤波、前馈等高级技术 - [实战案例分析](docs/tutorials/06_实战案例分析.md) - 真实项目经验和案例 - [常见问题诊断](docs/tutorials/07_常见问题诊断.md) - 问题诊断和解决方案 - [工程实践指南](docs/tutorials/08_工程实践指南.md) - 完整的项目开发流程 ### 开发指南 - [编译指南](docs/guides/BUILD.md) - 如何编译和测试 - [故障排除](docs/guides/TROUBLESHOOTING.md) - 常见问题解决 ### 测试报告 - [测试报告](docs/reports/TEST_REPORT.md) - 完整的测试结果 ## API 参考 ### 初始化 ```c pid_error_t pid_init(pid_t *pid, float kp, float ki, float kd); pid_error_t pid_set_gains(pid_t *pid, float kp, float ki, float kd); pid_error_t pid_reset(pid_t *pid); ``` ### 配置 ```c pid_error_t pid_set_output_limits(pid_t *pid, float min, float max); pid_error_t pid_set_integral_limits(pid_t *pid, float min, float max); pid_error_t pid_set_deadband(pid_t *pid, float deadband); pid_error_t pid_set_derivative_filter(pid_t *pid, float filter_coeff); pid_error_t pid_set_anti_windup(pid_t *pid, uint8_t enable); ``` ### 计算 ```c pid_error_t pid_compute(pid_t *pid, float setpoint, float feedback, float dt, float *output); pid_error_t pid_compute_incremental(pid_t *pid, float setpoint, float feedback, float dt, float *delta_output); ``` ### 监控 ```c float pid_get_error(const pid_t *pid, float setpoint, float feedback); float pid_get_integral(const pid_t *pid); float pid_get_last_output(const pid_t *pid); pid_error_t pid_get_terms(const pid_t *pid, float *p_term, float *i_term, float *d_term, float setpoint, float feedback, float dt); ``` ## 应用场景 - 🌡️ **温度控制** - 加热器、恒温箱 - ⚡ **电机控制** - 速度控制、位置控制 - 🚗 **机器人** - 平衡车、轮式机器人 - ✈️ **飞行器** - 姿态控制、高度控制 - 🏭 **工业控制** - 液位控制、压力控制 ## 许可证 MIT License - 详见 [LICENSE](LICENSE) 文件 ## 贡献 欢迎提交 Issue 和 Pull Request！ ## 作者 Embedded PID Controller Library Team ## 致谢 感谢所有为本项目做出贡献的开发者。