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：

sudo apt update
sudo apt install pigpio
sudo systemctl enable --now pigpiod

安装 Python 依赖：

pip3 install -r requirements.txt

快速开始

克隆仓库后直接运行（需要 root 或 pigpiod 可用）：

sudo python3 fan.py

带参数运行示例：

sudo python3 fan.py --target-temp 60 --duty-min 10 --duty-protect 30 --pwm-pin 18 --tach-pin 23

将程序打包并安装为 systemd 服务（示例脚本）：

./build.sh
sudo ./install_to_systemd.sh

提示：build.sh 脚本会自动创建或激活 Python 虚拟环境并安装 requirements.txt 中的依赖，随后使用 PyInstaller 打包可执行文件。克隆仓库后，只需在项目根目录运行：

./build.sh

install_to_systemd.sh 会把打包后的可执行文件复制到 /opt/Auto_Fan，并使用仓库中的 auto-fan.service 创建 systemd 服务。

运行时状态（/dev/shm/fan_status.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，祝硬件调试顺利！