From 52743be71d0cd0aba006eba5c8950870644cc0af Mon Sep 17 00:00:00 2001 From: desbma Date: Fri, 19 Sep 2014 23:50:54 +0200 Subject: [PATCH] Add README.md --- README.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..7ab3a83 --- /dev/null +++ b/README.md @@ -0,0 +1,149 @@ +HDD Fan control +=============== + +HDD Fan control is a tool to dynamically control fan speed according to hard drive temperature on Linux. + +This has 3 benefits: + +* it allows maintaining you hard drives in the ideal temperature range to have maximum longevity and avoid overheating + +Because fans will slow down or stop when not needed: + +* it minimizes noise generated by the fans +* it also minimizes power consumption at the same time + + +## When is this useful? + +HDD Fan control is useful when you have one or several hard drives with one or several fans close to them, and do not want to let the motherboard control the fan speed, because it does so either statically, or using a temperature sensor unrelated to the real drive temperature (either on the CPU or on some other place on the motherboard). + +The ideal use case is for a NAS with several hard drives, a low power CPU (ie. ARM or Intel Atom) with passive cooling (no fans), and a chassis with fans close to the hard drive. It that case the CPU will generate less heat than the hard drives and it makes sense to control fan speed according to the main heat source. + + +## Features + +* Can be started in deamon mode +* Can control several fans and/or several drives with a single invocation +* Can automatically spin down drives after a customizable period of inactivity +* Can adapt to different fan caracteristics +* Can be set to stop fans or run them at full speed at customizable temperatures +* Can be configured to never set the fans below a certain speed (useful if the fans controlled by HDD Fan control are the only ones available in the chassis) + + +## Prerequisities + +* A Linux distribution +* A least one SATA hard drive, that supports: + * Temperature querying + * Power state querying +* A motherboard which: + * exposes to the OS a PWM to control fan speed + * exposes to the OS a sensor to query fan speed + +Most motherboards and SATA drives fit these requirements. + + +## Installation + +HDD Fan control needs Python >= 3.4. It probably works with Python 3.3 with minimum efforts, or even previous 3.x versions, but I have not tested it. + +1. Clone this repository +2. If you don't have it, [install pip](http://www.pip-installer.org/en/latest/installing.html) for Python3 (may not be needed with Python >= 3.4). +On Ubuntu and other Debian derivatives, you can install with `sudo apt-get install python3-pip` +3. Install Python dependencies: `pip3 install -r requirements.txt` +4. Install [hdparm](http://sourceforge.net/projects/hdparm/) and [hddtemp](http://www.guzu.net/linux/hddtemp.php). +On Ubuntu and other Debian derivatives: `sudo apt-get install hdparm hddtemp`. + +To query fan caracteristic, you may also need pwmconfig. On Ubuntu and other Debian derivatives, it is part of the fancontrol package, that you can install with `sudo apt-get install fancontrol`. HDD fancontrol and fancontrol are unrelated. The fancontrol daemon is **not** needed fot HDD fan control to operate. If you use both fancontrol and HDD fancontrol, be careful not to make them control the same fans. + + +## Usage + +### A word of caution + +The default parameters will run fans at 100% speed at temperatures > 50°C, and run then a 20% speed if < 30°C, which corresponds to the usual recommended drive operating temperature. If you are sure that there are no other components in your system that generate significant heat, if you have other fans to cool down youy system, or if you have a case optimized for passive cooling, you can set minimum speed to 0%, which will stop the fans if temperature is below the minimum threshold. + +**Be aware that a misconfiguration of this tool can lead to a failure to cool down your system properly which can damage components or reduce their lifetime.** + +Before using HDD Fan control unmonitored for long period of time, I recommend keeping a minimum fan speed for security, and checking that the temperature of your system stays in reasonable range as expected. + + +### Fan configuration + +To get the value for the `--pwm`, `--pwm-start-value` and `--pwm-stop-value` parameters, use the [pwmconfig tool](http://www.lm-sensors.org/wiki/man/pwmconfig). + + +### Drive auto spin down + +SATA drives can be configured to automatically spin down after a certain period of inactivity, which saves power. If your drives are configured to do so, you may notice that they do not spin down when HDD Fan control is running. +This is due to the fact that HDD Fan control will query temperature at fixed interval, which the drive will consider an activity and reset the spin down timeout. +To fix that, you can either: + +* use a value for the `--interval` parameter higher than your SATA spin down time (not recommended unless your spin down time is very low, ie < 2 min) +* use the `--spin-down-time` parameter that will monitor drive activity and spin it down if inactive, independantly of the SATA feature (recommended) + +**Keep in mind that spinning down and up a drive repeatedly wears a it prematurly, so unless you are in a power constrained environement (ie. laptop), do not set the spin down time too low.** + +Reading temperature while a drive is in low power state will make it spin up, so HDD Fan control will stop querying temperature in that case, and wait for the drive (which will be cooling down in low power state anyway) to spin up. + +Some Hitachi (now HGST) drives support a special way of querying temperature that does not spin up drives, which HDD Fan control will detect and use, however it still prevents them from spinning down, so the above instructions still apply. + + +## Command line reference + + usage: hdd_fancontrol.py [-h] -d DRIVE_FILEPATHS [DRIVE_FILEPATHS ...] -p + FAN_PWM_FILEPATH [FAN_PWM_FILEPATH ...] + --pwm-start-value FAN_START_VALUE + [FAN_START_VALUE ...] --pwm-stop-value FAN_STOP_VALUE + [FAN_STOP_VALUE ...] [--min-temp MIN_TEMP] + [--max-temp MAX_TEMP] + [--min-fan-speed-prct MIN_FAN_SPEED_PRCT] + [-i INTERVAL_S] --stat-files STAT_FILEPATHS + [STAT_FILEPATHS ...] + [--spin-down-time SPIN_DOWN_TIME_S] + [-v {warning,normal,debug}] [-b] [-l LOG_FILEPATH] + [--pid-file PID_FILEPATH] + + Dynamically control fan speed according to hard drive temperature. + + optional arguments: + -h, --help show this help message and exit + -d DRIVE_FILEPATHS [DRIVE_FILEPATHS ...], --drives DRIVE_FILEPATHS [DRIVE_FILEPATHS ...] + Drive(s) to get temperature from (ie. /dev/sdX) + -p FAN_PWM_FILEPATH [FAN_PWM_FILEPATH ...], --pwm FAN_PWM_FILEPATH [FAN_PWM_FILEPATH ...] + PWM filepath(s) to control fan speed (under /sys) + --pwm-start-value FAN_START_VALUE [FAN_START_VALUE ...] + PWM value (0-255), at which the fan starts moving. Run + pwmconfig to find this value. + --pwm-stop-value FAN_STOP_VALUE [FAN_STOP_VALUE ...] + PWM value (0-255), at which the fan stop moving. Run + pwmconfig to find this value. Often 20-40 lower than + start speed. + --min-temp MIN_TEMP Temperature in Celcius at which the fan(s) will be set + to minimum speed. + --max-temp MAX_TEMP Temperature in Celcius at which the fan(s) will be set + to maximum speed. + --min-fan-speed-prct MIN_FAN_SPEED_PRCT + Minimum percentage of full fan speed to set the fan + to. Never set to 0 unless you have other fans to cool + down your system, or a case specially designed for + passive cooling. + -i INTERVAL_S, --interval INTERVAL_S + Interval in seconds to check temperature and adjust + fan speed. + --stat-files STAT_FILEPATHS [STAT_FILEPATHS ...] + Filepath of drive stats file (ie. /sys/block/sdX/stat) + --spin-down-time SPIN_DOWN_TIME_S + Interval in seconds after which inactive drives will + be put to standby state. + -v {warning,normal,debug}, --verbosity {warning,normal,debug} + Level of output to display + -b, --background Daemonize process + -l LOG_FILEPATH, --log-file LOG_FILEPATH + Filepath for log output when using deamon mode + --pid-file PID_FILEPATH + Filepath for lock file when using deamon mode + +## License + +[GPLv3](https://www.gnu.org/licenses/gpl-3.0-standalone.html)