Imported Upstream version 3.0.0

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -n
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/custom.css

@@ -0,0 +1,10 @@
+
+/* https://github.com/bitprophet/alabaster/issues/139#issuecomment-450294226 */
+div.body {
+    min-width: auto;
+    max-width: auto;
+}
+
+dl {
+    min-width: 450px;
+}

docs/_static/micro_schematics.svg

@@ -0,0 +1 @@
+../../arduino/micro_schematics.svg

docs/conf.py

@@ -0,0 +1,79 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import subprocess
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+
+def get_metadata_value(property_name):
+    # Requires python >=3.5
+
+    setup_py_dir = os.path.join(os.path.dirname(__file__), "..")
+    setup_py_file = os.path.join(setup_py_dir, "setup.py")
+
+    out = subprocess.run(
+        ["python3", setup_py_file, "-q", "--%s" % property_name],
+        stdout=subprocess.PIPE,
+        cwd=setup_py_dir,
+        check=True,
+    )
+    property_value = out.stdout.decode().strip()
+    return property_value
+
+
+project = get_metadata_value("name")
+author = get_metadata_value("author")
+
+_copyright_year = 2020
+copyright = "%s, %s" % (_copyright_year, author)
+
+# The full version, including alpha/beta/rc tags
+release = get_metadata_value("version")
+# The short X.Y version
+version = release.rsplit(".", 1)[0]  # `1.0.16+g40b2401` -> `1.0`
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+
+master_doc = 'index'

docs/index.rst

@@ -0,0 +1,511 @@
+Welcome to afancontrol's documentation!
+=======================================
+
+:Docs: https://afancontrol.readthedocs.io/
+:Source Code: https://github.com/KostyaEsmukov/afancontrol
+:Issue Tracker: https://github.com/KostyaEsmukov/afancontrol/issues
+:PyPI: https://pypi.org/project/afancontrol/
+
+
+Introduction
+~~~~~~~~~~~~
+
+`afancontrol` stands for "Advanced fancontrol". Think of it as
+`fancontrol <https://github.com/lm-sensors/lm-sensors/blob/master/prog/pwm/fancontrol>`_
+with more advanced configuration abilities.
+
+`afancontrol` measures temperature from the sensors, computes the required
+airflow and sets the PWM fan speeds accordingly.
+
+Key features:
+
+- Configurable temperature sources (currently supported ones are `lm-sensors`
+  temps, `hddtemp` and arbitrary shell commands);
+- Configurable PWM fan implementations (currently supported ones are
+  `lm-sensors` PWM fans, `freeipmi` (readonly) and
+  `a custom Arduino-based solution <index.html#pwm-fans-via-arduino>`_);
+- Configurable mappings between the temp sensors and the fans (e.g. fans
+  would be more sensitive to the closely located sensors than to
+  the farther-located ones);
+- Temperature filters to smoothen fan reactions;
+- Prometheus-compatible metrics exporter;
+- Custom shell commands might be run when temperature reaches configured
+  thresholds;
+- OS-agnostic (`afancontrol` is written in Python3 and might be run on any OS
+  which can run Python).
+
+`afancontrol` might be helpful in the following scenarios:
+
+- You have built a custom PC case with many different heat-generating parts
+  (like HDDs and GPUs) which you want to keep as quiet as possible, yet
+  being kept cool enough when required (at the cost of increased fan noise);
+- You need to control more 4-pin PWM fans than there're connectors
+  available on your motherboard (with an Arduino board
+  connected via USB);
+- You simply want to control a PWM fan with HDD temperatures.
+
+
+How it works
+~~~~~~~~~~~~
+
+`afancontrol` should be run as a background service. Every 5 seconds
+(configurable) a single `tick` is performed. During a `tick`
+the temperatures are gathered and the required fan speeds are calculated
+and set to the fans. Upon receiving a SIGTERM signal the program would
+exit and the fans would be restored to the maximum speeds.
+
+
+PWM Fan Line
+------------
+
+Each PWM fan has a PWM value associated with it which sets the speed of
+the fan, where ``0`` PWM means that the fan is stopped, and ``255`` PWM
+means that the fan is running at full speed.
+
+The correlation between the PWM value and the speed is usually not linear.
+When computing the PWM value from a temperature, `afancontrol` uses
+a specified range of the PWM values where the correlation between speed
+and PWM is close to linear (these are the ``pwm_line_start`` and
+``pwm_line_end`` config params).
+
+The bundled ``afancontrol fantest`` interactive command helps to determine
+that range, which is specific to a pair of a PWM fan and a motherboard.
+Here are some examples to give you an idea of the difference:
+
+1) A Noctua fan connected to an Arduino board. The correct settings in
+this case would be:
+
+- ``pwm_line_start = 40``
+- ``pwm_line_end = 245``
+
+.. image:: ./_static/noctua_arduino.svg
+   :target: ./_static/noctua_arduino.svg
+
+2) The same fan connected to a motherboard. The correct settings in this
+case would be:
+
+- ``pwm_line_start = 110``
+- ``pwm_line_end = 235``
+
+.. image:: ./_static/noctua_motherboard.svg
+   :target: ./_static/noctua_motherboard.svg
+
+3) Another fan connected to the same motherboard. The correct settings
+in this case would be:
+
+- ``pwm_line_start = 70``
+- ``pwm_line_end = 235``
+
+.. image:: ./_static/arctic_motherboard.svg
+   :target: ./_static/arctic_motherboard.svg
+
+
+Mappings
+--------
+
+Consider the following almost typical PC case as an example:
+
+.. image:: ./_static/pc_case_example.svg
+   :target: ./_static/pc_case_example.svg
+
+Assuming that `Intake Fans` share the same PWM wire and are connected to
+a `Fan 2` connector on the motherboard, and `Outtake Fans` share the PWM
+wire of a `Fan 3` motherboard connector, the fans config might look
+like the following:
+
+::
+
+    [fan: intake]
+    type = linux
+    pwm = /sys/class/hwmon/hwmon0/device/pwm2
+    fan_input = /sys/class/hwmon/hwmon0/device/fan2_input
+    pwm_line_start = 100
+    pwm_line_end = 240
+    never_stop = no
+
+    [fan: outtake]
+    type = linux
+    pwm = /sys/class/hwmon/hwmon0/device/pwm3
+    fan_input = /sys/class/hwmon/hwmon0/device/fan3_input
+    pwm_line_start = 100
+    pwm_line_end = 240
+    never_stop = yes
+
+The temperature sensors might look like this:
+
+::
+
+    [temp: cpu]
+    type = file
+    path = /sys/class/hwmon/hwmon1/temp1_input
+    min = 50
+    max = 65
+    panic = 80
+
+    [temp: mobo]
+    type = file
+    path = /sys/class/hwmon/hwmon0/temp1_input
+    min = 55
+    max = 65
+    panic = 80
+
+    [temp: gpu]
+    type = exec
+    command = nvidia-smi --query-gpu=temperature.gpu --format=csv,noheader,nounits -i 0
+    min = 55
+    max = 65
+    panic = 85
+
+    [temp: hdds]
+    type = hdd
+    path = /dev/sd?
+    min = 38
+    max = 45
+    panic = 50
+
+Now we need to create the mappings between the temps and the fans.
+The simplest mapping would be:
+
+::
+
+    [mapping: all]
+    fans = intake, outtake
+    temps = cpu, mobo, gpu, hdds
+
+
+The more fine-grained mappings configuration:
+
+::
+
+    [mapping: hdd]
+    fans = intake, outtake * 0.6
+    temps = hdds
+
+    [mapping: mobo]
+    fans = intake, outtake
+    temps = cpu, mobo, gpu
+
+Fan speeds are calculated as following (this is a simplified
+version for the matter of brevity):
+
+- For each temperature compute a desired `temperature speed` as
+  ``(current_temperature - min) / (max - min)``.
+- For each mapping compute a desired `mapping speed` as a maximum across
+  all of the mapping's `temperature speeds`.
+- For each fan compute a desired `fan speed` as a maximum across
+  all of the `mapping speeds`, multiplied by the fan modifier of that
+  mapping.
+- For each fan apply a PWM value computed roughly
+  as ``max(pwm_line_start, fan_speed * pwm_line_end)``.
+
+If at least one fan reports a zero RPM when non-zero PWM is set (i.e.
+the fan has jammed) or at least one temperature sensor reaches its `panic`
+value, the `panic` mode is activated, which would cause all fans to run
+at full speed until the issue is resolved.
+
+
+Installation
+~~~~~~~~~~~~
+
+Debian package
+--------------
+
+There's a Dockerfile which can be used to build a Debian `.deb` package:
+
+::
+
+    # Build the .deb from the latest PyPI release:
+    git clone https://github.com/KostyaEsmukov/afancontrol.git
+    cd afancontrol
+    make deb-from-pypi
+
+    # Install the package:
+    sudo apt install ./dist/debian/*.deb
+
+Perhaps one day the package might get published to the Debian repos,
+so a simple ``apt install afancontrol`` would work. But for now, given
+that the package is not popular enough yet, I believe it doesn't worth
+the hassle.
+
+To upgrade, the similar steps should be performed on an up to date
+`master` branch.
+
+
+From PyPI
+---------
+
+`afancontrol` might be installed with `pip` like a typical Python package,
+however, some extra steps are required to get the service running.
+
+Note that this section assumes that systemd is used for managing system
+processes. If this is not the case, skip all the commands related to systemd
+and make sure to create a similar service for your init system.
+
+::
+
+    # Install the package:
+    pip install afancontrol
+    # Or, if Arduino or Prometheus support are required:
+    pip install 'afancontrol[arduino,metrics]'
+
+    # To use the motherboard-based sensors and PWM fans on Linux,
+    # install lm-sensors:
+    apt install lm-sensors
+    # To use hddtemp for measuring HDD/SSD temperatures, install it:
+    apt install hddtemp
+
+The stock config and a systemd service files must be copied
+manually:
+
+::
+
+    PYPREFIX=`python3 -c 'import sys; print(sys.prefix)'`
+    # Usually PYPREFIX equals to `/usr/local`.
+
+    sudo mkdir -p /etc/afancontrol/
+    cp "${PYPREFIX}"/etc/afancontrol/afancontrol.conf /etc/afancontrol/
+    cp "${PYPREFIX}"/etc/systemd/system/afancontrol.service /etc/systemd/system/
+
+.. note::
+    Do not edit the files under ``$PYPREFIX``! The ``pip`` command might
+    overwrite these files without asking, so your changes would be lost.
+
+To upgrade, ``pip install --upgrade afancontrol`` and
+``systemctl restart afancontrol`` should be enough.
+
+
+Getting Started
+~~~~~~~~~~~~~~~
+
+The bundled `configuration file`_ is generously annotated, so you could just
+refer to it.
+
+.. _configuration file: https://github.com/KostyaEsmukov/afancontrol/blob/master/pkg/afancontrol.conf
+
+Generally speaking, the following steps are required (assuming that
+the package is already installed):
+
+- `Prepare an Arduino board <index.html#pwm-fans-via-arduino>`_, if
+  extra PWM fan connectors are needed;
+- Prepare and connect the PWM fans and temperature sensors;
+- `Set up lm-sensors <index.html#lm-sensors>`_, if you want to use
+  sensors or fans connected to a motherboard on Linux;
+- Edit the configuration file;
+- Start the daemon and enable autostart on system boot:
+
+::
+
+    sudo systemctl start afancontrol.service
+    sudo systemctl enable afancontrol.service
+
+
+PWM fans via Arduino
+--------------------
+
+An Arduino board might be used to control some PWM fans.
+
+Here is a `firmware`_ and schematics for Arduino Micro:
+
+.. _firmware: https://github.com/KostyaEsmukov/afancontrol/blob/master/arduino/micro.ino
+
+.. image:: ./_static/micro_schematics.svg
+   :target: ./_static/micro_schematics.svg
+
+The given firmware can be flashed as-is on a Genuine Arduino Micro
+without any tweaks. It is important to use Micro, because the firmware
+was designed specifically for it. For other boards you might need to change
+the pins in the firmware. Refer to its code for the hints on the places
+which should be modified.
+
+Once the board is flashed and connected, you may start using its pins
+in `afancontrol` to control the PWM fans connected to the board.
+
+
+lm-sensors
+----------
+
+`lm-sensors` is a Linux package which provides an ability to access and
+control the temperature and PWM fan sensors attached to a motherboard
+in userspace.
+
+Run the following command to make `lm-sensors` detect the available
+sensors hardware:
+
+::
+
+    sudo sensors-detect
+
+Once configured, use the ``sensors`` command to get the current measurements.
+
+Then you'd have to manually map the sensors with their actual physical location.
+
+For example:
+
+::
+
+    $ sensors
+    it8728-isa-0228
+    Adapter: ISA adapter
+    in0:          +0.92 V  (min =  +0.00 V, max =  +3.06 V)
+    in1:          +1.46 V  (min =  +0.00 V, max =  +3.06 V)
+    in2:          +2.03 V  (min =  +0.00 V, max =  +3.06 V)
+    in3:          +2.04 V  (min =  +0.00 V, max =  +3.06 V)
+    in4:          +2.03 V  (min =  +0.00 V, max =  +3.06 V)
+    in5:          +2.22 V  (min =  +0.00 V, max =  +3.06 V)
+    in6:          +2.22 V  (min =  +0.00 V, max =  +3.06 V)
+    3VSB:         +3.34 V  (min =  +0.00 V, max =  +6.12 V)
+    Vbat:         +3.31 V
+    fan1:         571 RPM  (min =    0 RPM)
+    fan2:        1268 RPM  (min =    0 RPM)
+    fan3:           0 RPM  (min =    0 RPM)
+    fan4:           0 RPM  (min =    0 RPM)
+    fan5:           0 RPM  (min =    0 RPM)
+    temp1:        +34.0°C  (low  = +127.0°C, high = +127.0°C)  sensor = thermistor
+    temp2:         -8.0°C  (low  = +127.0°C, high = +127.0°C)  sensor = thermistor
+    temp3:        +16.0°C  (low  = +127.0°C, high = +127.0°C)  sensor = Intel PECI
+
+
+There ``fan1`` corresponds to the CPU fan which is managed by BIOS,
+``fan2`` corresponds to the single PWM fan attached to the motherboard
+(which is typically called a "case" fan), ``temp1`` is a sensor (probably
+in a chipset) yielding reasonable measurements (unlike ``temp2`` and ``temp3``).
+
+So the case fan's settings would be:
+
+- ``pwm = /sys/class/hwmon/hwmon0/pwm2``
+- ``fan_input = /sys/class/hwmon/hwmon0/fan2_input``
+
+The ``temp1`` temperature sensor:
+
+- ``path = /sys/class/hwmon/hwmon0/temp1_input``
+
+This was an old cheap motherboard, so you would probably be more lucky
+and have the sensors which are yielding more trustworthy measurements.
+
+
+Metrics
+-------
+
+`afancontrol` supports exposing some metrics (like PWM, RPM, temperatures,
+etc) via a Prometheus-compatible interface. To enable it,
+the ``exporter_listen_host`` configuration option should be set to
+an address which should be bound for an HTTP server.
+
+The metrics response would look like this:
+
+::
+
+    $ curl http://127.0.0.1:8083/metrics
+    # HELP temperature_threshold The threshold temperature value (in Celsius) for a temperature sensor
+    # TYPE temperature_threshold gauge
+    temperature_threshold{temp_name="mobo"} NaN
+    temperature_threshold{temp_name="hdds"} NaN
+    # HELP fan_pwm Current fan's PWM value (from 0 to 255)
+    # TYPE fan_pwm gauge
+    fan_pwm{fan_name="hdd"} 0.0
+    # HELP fan_rpm Fan speed (in RPM) as reported by the fan
+    # TYPE fan_rpm gauge
+    fan_rpm{fan_name="hdd"} 0.0
+    # HELP temperature_is_threshold Is threshold temperature reached for a temperature sensor
+    # TYPE temperature_is_threshold gauge
+    temperature_is_threshold{temp_name="mobo"} 0.0
+    temperature_is_threshold{temp_name="hdds"} 0.0
+    # HELP is_panic Is in panic mode
+    # TYPE is_panic gauge
+    is_panic 0.0
+    # HELP temperature_current The current temperature value (in Celsius) from a temperature sensor
+    # TYPE temperature_current gauge
+    temperature_current{temp_name="mobo"} 35.0
+    temperature_current{temp_name="hdds"} 38.0
+    # HELP is_threshold Is in threshold mode
+    # TYPE is_threshold gauge
+    is_threshold 0.0
+    # HELP temperature_is_panic Is panic temperature reached for a temperature sensor
+    # TYPE temperature_is_panic gauge
+    temperature_is_panic{temp_name="mobo"} 0.0
+    temperature_is_panic{temp_name="hdds"} 0.0
+    # HELP fan_pwm_normalized Current fan's normalized PWM value (from 0.0 to 1.0, within the `fan_pwm_line_start` and `fan_pwm_line_end` interval)
+    # TYPE fan_pwm_normalized gauge
+    fan_pwm_normalized{fan_name="hdd"} 0.0
+    # HELP process_virtual_memory_bytes Virtual memory size in bytes.
+    # TYPE process_virtual_memory_bytes gauge
+    process_virtual_memory_bytes 227667968.0
+    # HELP process_resident_memory_bytes Resident memory size in bytes.
+    # TYPE process_resident_memory_bytes gauge
+    process_resident_memory_bytes 22659072.0
+    # HELP process_start_time_seconds Start time of the process since unix epoch in seconds.
+    # TYPE process_start_time_seconds gauge
+    process_start_time_seconds 1557312610.7
+    # HELP process_cpu_seconds_total Total user and system CPU time spent in seconds.
+    # TYPE process_cpu_seconds_total counter
+    process_cpu_seconds_total 3850.62
+    # HELP process_open_fds Number of open file descriptors.
+    # TYPE process_open_fds gauge
+    process_open_fds 7.0
+    # HELP process_max_fds Maximum number of open file descriptors.
+    # TYPE process_max_fds gauge
+    process_max_fds 8192.0
+    # HELP fan_pwm_line_start PWM value where a linear correlation with RPM starts for the fan
+    # TYPE fan_pwm_line_start gauge
+    fan_pwm_line_start{fan_name="hdd"} 70.0
+    # HELP tick_duration Duration of a single tick
+    # TYPE tick_duration histogram
+    tick_duration_bucket{le="0.1"} 0.0
+    tick_duration_bucket{le="0.25"} 369134.0
+    tick_duration_bucket{le="0.5"} 532386.0
+    tick_duration_bucket{le="0.75"} 532441.0
+    tick_duration_bucket{le="1.0"} 532458.0
+    tick_duration_bucket{le="2.5"} 532500.0
+    tick_duration_bucket{le="5.0"} 532516.0
+    tick_duration_bucket{le="10.0"} 532516.0
+    tick_duration_bucket{le="+Inf"} 532516.0
+    tick_duration_count 532516.0
+    tick_duration_sum 130972.32457521433
+    # HELP fan_pwm_line_end PWM value where a linear correlation with RPM ends for the fan
+    # TYPE fan_pwm_line_end gauge
+    fan_pwm_line_end{fan_name="hdd"} 235.0
+    # HELP temperature_is_failing The temperature sensor is failing (it isn't returning any data)
+    # TYPE temperature_is_failing gauge
+    temperature_is_failing{temp_name="mobo"} 0.0
+    temperature_is_failing{temp_name="hdds"} 0.0
+    # HELP fan_is_stopped Is PWM fan stopped because the corresponding temperatures are already low
+    # TYPE fan_is_stopped gauge
+    fan_is_stopped{fan_name="hdd"} 1.0
+    # HELP last_metrics_tick_seconds_ago The time in seconds since the last tick (which also updates these metrics)
+    # TYPE last_metrics_tick_seconds_ago gauge
+    last_metrics_tick_seconds_ago 4.541638209018856
+    # HELP fan_is_failing Is PWM fan marked as failing (e.g. because it has jammed)
+    # TYPE fan_is_failing gauge
+    fan_is_failing{fan_name="hdd"} 0.0
+    # HELP arduino_is_connected Is Arduino board connected via Serial
+    # TYPE arduino_is_connected gauge
+    # HELP temperature_min The min temperature value (in Celsius) for a temperature sensor
+    # TYPE temperature_min gauge
+    temperature_min{temp_name="mobo"} 40.0
+    temperature_min{temp_name="hdds"} 38.0
+    # HELP temperature_max The max temperature value (in Celsius) for a temperature sensor
+    # TYPE temperature_max gauge
+    temperature_max{temp_name="mobo"} 50.0
+    temperature_max{temp_name="hdds"} 45.0
+    # HELP temperature_panic The panic temperature value (in Celsius) for a temperature sensor
+    # TYPE temperature_panic gauge
+    temperature_panic{temp_name="mobo"} 60.0
+    temperature_panic{temp_name="hdds"} 50.0
+    # HELP arduino_status_age_seconds Seconds since the last `status` message from the Arduino board (measured at the latest tick)
+    # TYPE arduino_status_age_seconds gauge
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+Table of contents
+=================
+
+.. toctree::
+   :maxdepth: 3
+
+   index