114 lines
4.1 KiB
Markdown
114 lines
4.1 KiB
Markdown
# Auto_Fan — 树莓派四线风扇 PID 自动控制
|
||
|
||
本项目用于在树莓派上对四线（4-pin）PWM 风扇进行自动控制，基于 PID 算法调速并包含堵转检测（stall detection）。可将风扇作为系统服务运行，实时状态写入内存盘以供其他程序读取。
|
||
|
||
**主要功能**
|
||
|
||
- 基于 PID 的风扇速度控制（见 `fan.py`）。
|
||
- 堵转检测：当占空比超过保护阈值且转速异常低时报警并在状态文件中标记。
|
||
- 将实时状态写入 `/dev/shm/fan_status.json`（包含 `temp`, `rpm`, `pwm`, `is_stalled`）。
|
||
- 提供一个实验性的自适应 PID 示例（`fan_autopid.py`）。
|
||
- 支持通过 `systemd` 安装为服务（`build.sh` + `install_to_systemd.sh` + `auto-fan.service`）。
|
||
|
||
**特性细节**
|
||
|
||
- 默认 GPIO：PWM 使用 `GPIO18`（硬件 PWM），TACH 使用 `GPIO23`（GPIO 引脚可通过命令行参数修改）。
|
||
- 默认 PID 系数位于 `fan.py` 顶部（`Kp`, `Ki`, `Kd`），需要根据实际散热与风扇特性调参。
|
||
- 堵转判定逻辑（`fan.py`）：当 PWM > `DUTY_PROTECT` 且 RPM < 500 时判定可能堵转；同时会在 `/dev/shm/fan_status.json` 中将 `is_stalled` 标记为 `true` 并在控制台打印警告。
|
||
- 温度来源：读取 `/sys/class/thermal/thermal_zone0/temp`（CPU 温度），并对温度做低通滤波以平滑控制。
|
||
|
||
**依赖与前提**
|
||
|
||
- 硬件：树莓派（建议 Pi 3/4），支持 4-pin PWM 风扇（PWM, TACH, +5V, GND）。确保接线正确：PWM 到 `GPIO18`（BCM 编号），TACH 到 `GPIO23`（示例）。
|
||
- 软件：
|
||
- Python 3
|
||
- `pigpio` 库与 `pigpiod` 守护进程（见 `requirements.txt`）。
|
||
|
||
在系统上安装并启动 `pigpiod`：
|
||
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install pigpio
|
||
sudo systemctl enable --now pigpiod
|
||
```
|
||
|
||
安装 Python 依赖：
|
||
|
||
```bash
|
||
pip3 install -r requirements.txt
|
||
```
|
||
|
||
**快速开始**
|
||
|
||
克隆仓库后直接运行（需要 root 或 pigpiod 可用）：
|
||
|
||
```bash
|
||
sudo python3 fan.py
|
||
```
|
||
|
||
带参数运行示例：
|
||
|
||
```bash
|
||
sudo python3 fan.py --target-temp 60 --duty-min 10 --duty-protect 30 --pwm-pin 18 --tach-pin 23
|
||
```
|
||
|
||
将程序打包并安装为 systemd 服务（示例脚本）：
|
||
|
||
```bash
|
||
./build.sh
|
||
sudo ./install_to_systemd.sh
|
||
```
|
||
|
||
提示：`build.sh` 脚本会自动创建或激活 Python 虚拟环境并安装 `requirements.txt` 中的依赖，随后使用 PyInstaller 打包可执行文件。克隆仓库后，只需在项目根目录运行：
|
||
|
||
```bash
|
||
./build.sh
|
||
```
|
||
|
||
`install_to_systemd.sh` 会把打包后的可执行文件复制到 `/opt/Auto_Fan`，并使用仓库中的 `auto-fan.service` 创建 systemd 服务。
|
||
|
||
**运行时状态（/dev/shm/fan_status.json）示例**
|
||
|
||
```json
|
||
{
|
||
"temp": 55.2,
|
||
"rpm": 1200,
|
||
"pwm": 120,
|
||
"is_stalled": false
|
||
}
|
||
```
|
||
|
||
- `temp`: 当前温度（摄氏度）
|
||
- `rpm`: 当前转速（RPM）
|
||
- `pwm`: 当前 PWM 占空比（0-255）
|
||
- `is_stalled`: 是否检测到可能堵转（布尔值）
|
||
|
||
**调整与调试**
|
||
|
||
- PID 参数（`Kp`, `Ki`, `Kd`）可在 `fan.py` 顶部修改，然后重启程序。也可以使用 `fan_autopid.py` 试验自适应调参逻辑。
|
||
- 启动风扇的最小占空比由 `DUTY_MIN` 控制（风扇启动时常需较高占空比才能开始转动）。
|
||
- 堵转保护阈值由 `DUTY_PROTECT` 控制，可通过命令行或修改源码调整。
|
||
- 若无法读取温度或 RPM 为 0，请检查 TACH 接线与 `pigpiod` 状态。
|
||
|
||
**安全与免责声明**
|
||
|
||
- 运行本程序可能需要 root 权限或启用 `pigpiod`，请谨慎授权。
|
||
- 错误接线或不当配置可能损坏风扇或树莓派硬件。务必在断电情况下检查接线并确认接地。
|
||
- 本软件按现状提供，不含任何明示或暗示的担保（参见 GPL-3.0 许可中的免责声明）。
|
||
|
||
**许可（License）**
|
||
|
||
本项目采用 GNU General Public License v3.0（GPL-3.0）许可，详见仓库中的 `LICENSE` 文件。使用或分发本项目时，请遵守 GPL-3.0 的条款。
|
||
|
||
**AI 辅助声明**
|
||
|
||
本仓库的部分内容由 AI 生成。
|
||
|
||
**贡献与联系**
|
||
|
||
欢迎提交 issue 或 PR。如需帮助，可在仓库中打开 issue 或联系维护者。
|
||
|
||
---
|
||
|
||
感谢使用 Auto_Fan，祝硬件调试顺利！
|