# 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，祝硬件调试顺利！