Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jamsinclair/opifancontrol
A simple PWM fan controller for Orange Pi boards
https://github.com/jamsinclair/opifancontrol
orange-pi orangepi orangepi-5-plus orangepi5 pwm-fan
Last synced: about 2 months ago
JSON representation
A simple PWM fan controller for Orange Pi boards
- Host: GitHub
- URL: https://github.com/jamsinclair/opifancontrol
- Owner: jamsinclair
- License: mit
- Created: 2024-01-03T17:15:41.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2024-08-05T04:32:18.000Z (5 months ago)
- Last Synced: 2024-10-11T15:10:58.842Z (2 months ago)
- Topics: orange-pi, orangepi, orangepi-5-plus, orangepi5, pwm-fan
- Language: Shell
- Homepage:
- Size: 2.62 MB
- Stars: 14
- Watchers: 2
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# opifancontrol
A simple PWM fan controller for Orange Pi boards using GPIO pins (Only tested on an Orange Pi 5 and Orange Pi 5 Plus).
ℹ️ The SoC processor used by Orange Pi 5 and Orange Pi 5 Plus also supports built-in fan control that can be updated with UEFI firmware. This project is focused on a providing a simple solution without updating firmware. For more information see [UEFI Fan Control](#uefi-fan-control).
## Features
- Runs as a systemd service
- Automatically control the speed of a PWM fan based on the temperature of the CPU
- Configurable thresholds for fan speed and temperature
- Ramp up and ramp down delays to avoid rapid on/off switching of the fan
# Setup
## Hardware Setup
### Orange Pi 5
Needed parts:
- Orange Pi 5
- [Noctua NF-A4x10 5V PWM](https://noctua.at/en/nf-a4x10-5v-pwm) note that only the `5V PWM` is supported, other voltages or non `PWM` variants are not.
Connect the 3 fan wires.
1. What matters the most is the $\mathbf{\color{blue}{blue\quad PWM}}$ wire matches the software configuration.
On the board use the physical pin `7` (`wPi` pin `2`) on the GPIO header to use the default software configuration without any change.
If for whatever reason you are forced to use another pin, then you will have to change the `FAN_GPIO_PIN`.
To do that see the [configuration](#configuration) section.
2. For the $\mathbf{\color{yellow}{yellow\quad 5V}}$ you have 2 options physical pins `2` and `4`.
3. For the $\mathbf{\color{black}{black\quad GND}}$ you have 3 options physical pins `6`, `14` and `20`.
We recommend to use the pins that are closest to each other, therfore physical pins `4` for `5V`, `6` for `GND` and `7` for `PWM` marked below:
### Orange Pi 5 Plus
I am currently using:
- Orange Pi 5 Plus
- [GeeekPi PWM Controllable Fan 40x40x10mm](https://www.amazon.co.jp/gp/product/B092VRPC8H)
For the Orange Pi 5 Plus, I connect the fan to the 5V and GND pins and the PWM wire to the physical pin 5 (wPi pin 2) on the GPIO header
## Software Installation & Updates
### Prerequisites
Installed the [wiringOP](https://github.com/orangepi-xunlong/wiringOP) library. Check the [installation instructions](https://github.com/orangepi-xunlong/wiringOP#how-to-download-wiringop).
### Install or Update via script
Run the following command to install or update the fan controller:
```bash
# Run again with sudo if you get permission errors
curl -sSL https://raw.githubusercontent.com/jamsinclair/opifancontrol/main/install.sh | bash
```
### Install manually
Install the fan controller manually.
1. Copy the `opifancontrol.sh` script to `/usr/local/bin/` and make it executable:
```bash
cp opifancontrol.sh /usr/local/bin/opifancontrol.sh
chmod +x /usr/local/bin/opifancontrol.sh
```
2. Copy the `opifancontrol.conf` file to `/etc/`:
```bash
cp opifancontrol.conf /etc/
```
3. Copy the `opifancontrol.service` file to `/etc/systemd/system/`:
```bash
cp opifancontrol.service /etc/systemd/system/
```
4. Enable the service:
```bash
systemctl enable opifancontrol.service
```
## Configuration
The configuration file is located at `/etc/opifancontrol.conf`. The default configuration is:
```bash
# The GPIO pin to use for the fan. This is the wPi pin number, not the physical pin number.
# You can find the wPi pin number by running `gpio readall` on the Orange Pi.
FAN_GPIO_PIN=2
# TEMP_LOW, TEMP_MED, TEMP_HIGH are in degrees Celsius
# FAN_LOW, FAN_MED, FAN_HIGH are in percent of max fan speed, max 100.
# The fan will only be turned on if the temperature is above TEMP_LOW.
TEMP_LOW=55
FAN_LOW=50
TEMP_MED=65
FAN_MED=75
TEMP_HIGH=70
FAN_HIGH=100
# How frequently, in seconds, to poll the temperature data
TEMP_POLL_SECONDS=2
# To avoid rapid on/off switching, the fan will delay switching back on if it was recently turned off.
RAMP_UP_DELAY_SECONDS=15
# The ramp down delay is how long the fan will stay on after the temperature drops below the threshold.
RAMP_DOWN_DELAY_SECONDS=60
# The PWM range and clock are used to control the fan speed. You shouldn't need to change these unless you know what you're doing.
# Assumes the CPU fan runs at 25kHz.
PWM_RANGE=192
PWM_CLOCK=4
# Set to true to enable debug logging of fan speed changes.
DEBUG=false
```
## Debugging
Update the config file with your editor of choice (vim, nano etc.)
1. `nano /etc/opifancontrol.conf`
2. Add the line `DEBUG=true` or update the existing line to match.
The debugging information can be printed out with `journalctl`
1. `journalctl -u opifancontrol`
This will output information of the current settings and changes to fan speed.
## Uninstallation
To uninstall the fan controller, first stop and disable the service:
```bash
systemctl stop opifancontrol.service
systemctl disable opifancontrol.service
```
Then remove the files:
```bash
rm /usr/local/bin/opifancontrol.sh
rm /etc/opifancontrol.conf
rm /etc/systemd/system/opifancontrol.service
```
## UEFI Fan Control
The Orange Pi 5 and Orange Pi 5 Plus also have a dedicated fan header and fan control. This is supported by the Rockchip UEFI firmware and can be updated to select the pins, temperature thresholds and fan speeds for fan control without the need for this project.
For more information on how to update the UEFI firmware, see the [EDK2 UEFI firmware for Rockchip](https://github.com/edk2-porting/edk2-rk3588) or your Orange Pi manual. This project will not be updated to support the UEFI firmware fan control and aims to keep things simple.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.