Metadata-Version: 2.4
Name: raspi_fan_control
Version: 0.3.0
Summary: Automated fan control for Raspberry Pi based on native temperature sensors and customizable fan curves
Project-URL: source, https://github.com/naschorr/raspi-fan-control
Author-email: Nick Schorr <naschorr@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: curve,fan,fan control,pwm,raspberry pi,sensor,temperature,temperature sensor
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: confiddle>=0.2.1
Requires-Dist: pydantic>=2.0
Provides-Extra: deploy
Requires-Dist: build>=1.4.4; extra == 'deploy'
Requires-Dist: hatchling>=1.29.0; extra == 'deploy'
Requires-Dist: twine>=6.2.0; extra == 'deploy'
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Description-Content-Type: text/markdown

# raspi-fan-control

Automated PWM fan control for Raspberry Pi. Reads temperature from the CPU thermal zone and drives one or more fans along a configurable curve.

## Requirements

- Raspberry Pi running a Debian-based OS (Raspberry Pi OS, Ubuntu, etc.)
- Python 3.11+
- A properly wired up PWM fan:
    - The fan's PWM pin should be wired to [GPIO pin 18](https://pinout.xyz/pinout/pin12_gpio18/) (or any other pin that supports PWM)
    - The fan's RPM pin should be wired to [GPIO pin 15](https://pinout.xyz/pinout/pin10_gpio15/).
    - The fan's power and ground pins connected to the power supply (technically the Raspberry Pi will power a fan, but it's not ideal and you'll be required to use a 5V fan)
- Root access for installation

Note that the default configuration is set up for a Noctua PWM fan, so by using GPIO pins 18 and 15 this is basically plug and play! However, tweaking the configuration for other fans should be easy.

## Installation

### 1. Create a virtual environment

```bash
sudo python3 -m venv /opt/raspi-fan-control
```

### 2. Install the package

Install directly from PyPI:

```bash
sudo /opt/raspi-fan-control/bin/pip install raspi-fan-control
```

### 3. Run the install script

The install script writes the systemd service file, enables it, and starts the service:

```bash
sudo /opt/raspi-fan-control/bin/raspi-fan-control-install
```

The service file is written to `/etc/systemd/system/raspi-fan-control.service`. Need to update something? No worries, make the change to the template (see [Configuration](#configuration) below), then re-run the install script to apply changes.

## Configuration

All configuration is supplied as `Environment=` entries in the systemd service file at `/etc/systemd/system/raspi-fan-control.service`. The prefix `RFC__` maps to the top-level config, and double underscores (`__`) delimit nesting.

After editing the service file, apply changes with:

```bash
sudo raspi-fan-control-install
```

### Top-level

| Variable | Description | Example |
|---|---|---|
| `RFC__POLLING_INTERVAL_MS` | How often to poll temperature sensors (ms) | `1000` |

### Fan (`RFC__FANS__<index>__...`)

| Variable | Description | Example |
|---|---|---|
| `RFC__FANS__0__ID` | Unique fan identifier | `primary` |
| `RFC__FANS__0__NAME` | Fan display name | `Noctua` |

#### PWM (`RFC__FANS__<index>__PWM__...`)

| Variable | Description | Example |
|---|---|---|
| `RFC__FANS__0__PWM__PIN__NUMBER` | GPIO pin number | `18` |
| `RFC__FANS__0__PWM__PIN__MODE` | Pin numbering mode (`gpio` or `wpi`) | `gpio` |
| `RFC__FANS__0__PWM__FREQUENCY_HZ` | PWM frequency in Hz | `25000` |
| `RFC__FANS__0__PWM__DATA_RANGE` | PWM value range | `1024` |

#### RPM (`RFC__FANS__<index>__RPM__...`)

| Variable | Description | Example |
|---|---|---|
| `RFC__FANS__0__RPM__PIN__NUMBER` | Tachometer GPIO pin number | `15` |
| `RFC__FANS__0__RPM__PIN__MODE` | Pin numbering mode (`gpio` or `wpi`) | `gpio` |
| `RFC__FANS__0__RPM__PIN__USE_INTERNAL_PULLDOWN` | Enable internal pull-down resistor | `true` |
| `RFC__FANS__0__RPM__RPM_MAX` | Maximum fan RPM | `5000` |
| `RFC__FANS__0__RPM__PULSES_PER_REVOLUTION` | Tachometer pulses per revolution | `2` |

#### Fan curve (`RFC__FANS__<index>__CURVE__POINTS__<index>__...`)

The curve maps a normalized temperature (0.0-1.0) to a normalized duty cycle (0.0-1.0). Add as many points as needed; they are interpolated linearly. By default it will use a simple linear fan curve from (0.0, 0.0) to (1.0, 1.0).

| Variable | Description | Example |
|---|---|---|
| `RFC__FANS__0__CURVE__POINTS__0__INPUT_X` | Normalized temperature input | `0.0` |
| `RFC__FANS__0__CURVE__POINTS__0__OUTPUT_Y` | Normalized duty cycle output | `0.0` |

### Temperature sensor (`RFC__TEMPERATURE_SENSORS__<index>__...`)

Note that the `...__TEMPERATURE_MIN_C` and `...__TEMPERATURE_MAX_C` values define the upper and lower bounds that the fan curve will use when determining how fast to spin the fans. Currently the values are sensible defaults for the Raspberry Pi, but you may wish to tweak them for more complex (or non Raspberry Pi based) scenarios.

| Variable | Description | Example |
|---|---|---|
| `RFC__TEMPERATURE_SENSORS__0__ID` | Unique sensor identifier | `cpu` |
| `RFC__TEMPERATURE_SENSORS__0__FLAVOR` | Sensor type (currently `cpu`) | `cpu` |
| `RFC__TEMPERATURE_SENSORS__0__TEMPERATURE_MIN_C` | Temperature at 0% duty cycle (°C) | `40` |
| `RFC__TEMPERATURE_SENSORS__0__TEMPERATURE_MAX_C` | Temperature at 100% duty cycle (°C) | `80` |
| `RFC__TEMPERATURE_SENSORS__0__FANS__0` | Fan ID to control | `primary` |

### Example service file

Check out the [systemd service file](https://github.com/naschorr/raspi-fan-control/blob/main/install/raspi-fan-control.service).

## Managing the service

It's a systemd service so it can be managed via `systemctl` like any other, but here's a couple handy scripts:

```bash
# Restart after config changes
sudo raspi-fan-control-install

# View logs
sudo journalctl -u raspi-fan-control -f
```