协议与说明

README.md

@@ -0,0 +1,113 @@
+# 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，祝硬件调试顺利！