KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #ai-agents #dsh-plugin #codex #developer-tools #claude-code #windows #desktop-app #typescript #rust #ai-agent #cli

nbfc-linux

★ 772 Open GitHub ↗

NoteBook FanControl ported to Linux

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

NoteBook FanControl
===================

This is a C port of [Stefan Hirschmann's](https://github.com/hirschmann) [NoteBook FanControl](https://github.com/hirschmann/nbfc).

It provides the same utilities with the same interfaces as the original NBFC, although the implementation differs.

To check if your laptop is supported, use the [Configuration Search](https://nbfc-linux.github.io/configs/).

If you want to write a configuration for your laptop model, see [Configuration HowTo](https://nbfc-linux.github.io/creating-config/).

I regularly purchase laptops to create configuration files, analyze their ACPI firmware, and gain a deeper understanding of how these systems work. The knowledge gained through this process is documented and preserved in the tutorial to help others understand and work with similar hardware.

If you find my work helpful, you can show your appreciation by [buying me a coffee](https://paypal.me/BenjaminAbendroth).

Table of Contents
-----------------

- [Comparison of NBFC C# and NBFC Linux](#comparison-of-nbfc-c-and-nbfc-linux)
- [Installation](#installation)
- [Getting started with the GUI](#getting-started-with-the-gui)
- [Getting started without the GUI](#getting-started-without-the-gui)
- [Advanced configuration](#advanced-configuration)
- [Differences in detail](#differences-in-detail)
- [Troubleshooting](#troubleshooting)
- [Advanced Compilation](#advanced-compilation)
- [Shell autocompletion](#shell-autocompletion)
- [Contributing](#contributing)

Comparison of NBFC C# and NBFC Linux
------------------------------------

|What                             | NBFC Mono                             | NBFC Linux                                  |
|---------------------------------|---------------------------------------|----------------------------------------------
|Portability                      | Crossplatform                         | Linux                                       |
|Runtime                          | Mono                                  | Native                                      |
|Memory Consumption (ps\_mem)     | ~50MB                                 | ~230KB                                      |
|Model Configuration Files        | [XML](https://github.com/hirschmann/nbfc/tree/master/Configs) (210 files) | [JSON](share/nbfc/configs) (312 files) |
|Model Compatibility Database     | No                                    | [Yes](share/nbfc/model_support.json)        |
|Fan Control Rights               | Any user                              | Any user                                    |
|Service Control Rights           | Any user                              | Only root                                   |
|ACPI Method Support              | No                                    | Yes (via `acpi_call` kernel module)         |
|Fail-Safe Runtime Design         | No (not OOM-safe)                     | Yes                                         |
|IPC Concept                      | TCP/IP                                | Unix sockets                                |
|IPC Protocol                     | Binary                                | JSON                                        |
|Graphical User Interface         | Windows only                          | Linux only                                  |

The [service](doc/nbfc_service.1.md), the [client](doc/nbfc.1.md) and the [probing tool](doc/ec_probe.1.md) are written in C.

Installation
------------

### Packages

| Operating System      | Download                       | Command                                        |
|-----------------------|--------------------------------|-------------------------------------------------
| Arch Linux            | [0.5.3](https://github.com/nbfc-linux/nbfc-linux/releases/download/0.5.3/arch-linux-nbfc-linux-git-0.5.3-1-x86_64.pkg.tar.zst)       | `sudo pacman -U ./arch-linux-nbfc-linux-git-0.5.3-1-x86_64.pkg.tar.zst`         |
| Debian Trixie         | [0.5.3](https://github.com/nbfc-linux/nbfc-linux/releases/download/0.5.3/debian-trixie-nbfc-linux_0.5.3_amd64.deb)   | `sudo apt install ./debian-trixie-nbfc-linux_0.5.3_amd64.deb`   |
| Debian Bookworm       | [0.5.3](https://github.com/nbfc-linux/nbfc-linux/releases/download/0.5.3/debian-bookworm-nbfc-linux_0.5.3_amd64.deb) | `sudo apt install ./debian-bookworm-nbfc-linux_0.5.3_amd64.deb` |
| Ubuntu Resolute       | [0.5.3](https://github.com/nbfc-linux/nbfc-linux/releases/download/0.5.3/ubuntu-resolute-nbfc-linux_0.5.3_amd64.deb) | `sudo apt install ./ubuntu-resolute-nbfc-linux_0.5.3_amd64.deb` |
| Ubuntu Noble          | [0.5.3](https://github.com/nbfc-linux/nbfc-linux/releases/download/0.5.3/ubuntu-noble-nbfc-linux_0.5.3_amd64.deb)    | `sudo apt install ./ubuntu-noble-nbfc-linux_0.5.3_amd64.deb`    |
| Ubuntu Jammy          | [0.5.3](https://github.com/nbfc-linux/nbfc-linux/releases/download/0.5.3/ubuntu-jammy-nbfc-linux_0.5.3_amd64.deb)    | `sudo apt install ./ubuntu-jammy-nbfc-linux_0.5.3_amd64.deb`    |
| Linux Mint 22         | [0.5.3](https://github.com/nbfc-linux/nbfc-linux/releases/download/0.5.3/linux-mint-22-nbfc-linux_0.5.3_amd64.deb)   | `sudo apt install ./linux-mint-22-nbfc-linux_0.5.3_amd64.deb`   |
| Linux Mint 21         | [0.5.3](https://github.com/nbfc-linux/nbfc-linux/releases/download/0.5.3/linux-mint-21-nbfc-linux_0.5.3_amd64.deb)   | `sudo apt install ./linux-mint-21-nbfc-linux_0.5.3_amd64.deb`   |
| Fedora 44             | [0.5.3](https://github.com/nbfc-linux/nbfc-linux/releases/download/0.5.3/fedora-44-nbfc-linux-0.5.3-1.x86_64.rpm)       | `sudo dnf install ./fedora-44-nbfc-linux-0.5.3-1.x86_64.rpm`       |
| Fedora 43             | [0.5.3](https://github.com/nbfc-linux/nbfc-linux/releases/download/0.5.3/fedora-43-nbfc-linux-0.5.3-1.x86_64.rpm)       | `sudo dnf install ./fedora-43-nbfc-linux-0.5.3-1.x86_64.rpm`       |
| OpenSuse (Tumbleweed) | [0.5.3](https://github.com/nbfc-linux/nbfc-linux/releases/download/0.5.3/opensuse-nbfc-linux-0.5.3-1.x86_64.rpm)        | `sudo zypper install ./opensuse-nbfc-linux-0.5.3-1.x86_64.rpm`     |

### Alternative Installation Methods

- Arch Linux:
  - Via AUR (`yay -S nbfc-linux`)
  - Via PKGBUILD [nbfc-linux-git](pkgbuilds/nbfc-linux-git/PKGBUILD)

- NixOS:
  - [Declaratively](nixos-installation-new.md)
  - [Imperatively](nixos-installation.md) (with `nix profile install` or `nix-env -if .`)

- Fedora - this will not build the current working directory, but downloads a source archive from chosen release on github and builds an installable rpm:
  - ensure, that podman is installed
    - docker should work also, but is currently not tested
  - edit [pkgbuilds/rpm/nbfc-linux.spec](./pkgbuilds/rpm/nbfc-linux.spec) and
    - set wanted Version (e.g. 0.5.3)
    - set wanted Releasenumber (e.g. 1%{?dist} or 2%{?dist})
  - `./pkgbuilds/rpm/buildNBFC-LINUX`
  - the resulting rpm can be found in [pkgbuilds directory](./pkgbuilds/)

- In general:
  - `./autogen.sh && ./configure --prefix=/usr --sysconfdir=/etc && make && sudo make install`

- For systems with OpenRC (gentoo):
  - `./autogen.sh && ./configure --prefix=/usr --sysconfdir=/etc --with-init-system=openrc && make && sudo make install`

- For systems with System-V-Init:
  - `./autogen.sh && ./configure --prefix=/usr --sysconfdir=/etc --with-init-system=systemv && make && sudo make install`

Getting started with the GUI
----------------------------

Graphical User Interfaces are available as separate projects.

Currently there are three GUI implementations:

- [NBFC-Qt](https://github.com/nbfc-linux/nbfc-qt)
  - Simple GUI written in Python based on Qt5/Qt6
  - Comes with an extra tray application for controlling fans

- [NBFC-Gtk](https://github.com/nbfc-linux/nbfc-gtk)
  - Simple GUI written in Python based on Gtk4

- [NBFC-XFCE4-Tray](https://github.com/nbfc-linux/nbfc-xfce4-tray)
  - Simple XFCE4 Panel Plugin (only for controlling the fans)

Getting started without the GUI
-------------------------------

When running NBFC for the first time, you need to give it a configuration file for your laptop model.

Follow the steps below:

1. `sudo nbfc update` will download the latest configuration files from the internet.

2. `sudo nbfc config --set auto` will try to set a configuration automatically.

If this succeeds, skip to *Step 5*.

3. `sudo nbfc rate-config -a` will print out a list of configurations that may work on your notebook.

4. Repeat the following until you found a working configuration:

- `sudo nbfc config --set "MODEL"` -- set a configuration

- `sudo nbfc restart -r` -- (re-)start the service in *read only* mode

- `nbfc status` -- show the fan status

- Let the fan turn up (and down) (e.g. using `stress`) and observe if `nbfc status` shows fan speed changes

- If speeds are reported correctly, the config is likely valid. Proceed to *Step 5*.

5. `sudo nbfc restart` will (re-)start the service in *write mode* (enabling fan control)

6. Test fan control manually

- `nbfc set -s <SPEED>` will set the fan speed. (`0`=off, `100`=full speed)

If this does not work, the specified configuration is invalid. Go back to *Step 4*.

7. `nbfc set --auto` will enable *auto mode* (temperature-based automatic fan speed control as specified in configuration)

8. `sudo systemctl enable nbfc_service` will enable the service to start automatically on boot

Advanced configuration
----------------------

NBFC-Linux allows you to specify which temperature sources to use for controlling fans and the algorithm to compute the temperature.

> NOTE: Since version 0.3.3 NBFC-Linux also allows you to specify sensors in FanConfigurations using the `Sensors` field

> NOTE: The command `nbfc sensors` is available since version 0.3.16. If you are running a previous version, you can still [configure it by hand](doc/advanced_configuration.md).

**Default Configuration**

If no configuration is specified, NBFC uses the "Average" algorithm and utilizes all sensor files named "coretemp", "k10temp", or "zenpower".

**Available Algorithms**

You can choose from three different algorithms to compute the temperature:

- *"Average"*: Computes the average temperature from all specified sources.
- *"Min"*: Selects the lowest temperature among all specified sources.
- *"Max"*: Selects the highest temperature among all specified sources.

**Temperature Sources**

You can specify temperature sources either by a
- *sensor name* (which may result in multiple temperature sources)
- *temperature file*: A file containing the temperature (usually named `temp*_input`)
- *shell command*: A command whose output is used as temperature (the command has to be prefixed by `$`)
- *sensor group*:
  - *@CPU*: Uses all sensors named "coretemp", "k10temp" or "zenpower"
  - *@GPU*: Uses all sensors named "amdgpu", "nvidia", "nouveau" or "radeon"

**Specyfing Temperature Sources**

1. `nbfc sensors list` will output all available sensors

2. `nbfc sensors show` will show all available fans and their configured sensors

3. `sudo nbfc sensors set -f <FAN_INDEX> [-s <SENSOR>...] [-a <ALGORITHM>]` will set the specified sensors and the algorithm for a fan.

**Examples**

- `sudo nbfc sensors set -f 0 -s coretemp -a Min`

*Fan 0* uses the "*Min*" algorithm with all sensors named "*coretemp*".

- `sudo nbfc sensors set -f 0 -s /sys/class/hwmon/hwmon4/temp1_input -s /sys/class/hwmon/hwmon4/temp2_input`

*Fan 0* uses the default algorithm with the specific *sensor file paths*.

- `sudo nbfc sensors set -f 0 -s '$ echo 42'`

*Fan 0* uses the output of *echo 42* as temperature

- `sudo nbfc sensors set -f 1 -s @GPU`

*Fan 1* uses all sensors in the `@GPU` group ("amdgpu", "nvidia", "nouveau", "radeon")

Differences in detail
---------------------

|Files                            | NBFC Mono                             | NBFC Linux                                  |
|---------------------------------|---------------------------------------|----------------------------------------------
|Systemd service file             | nbfc.service                          | nbfc\_service.service                       |
|EC Probing tool                  | ec-probe                              | ec\_probe                                   |
|Notebook configuration files     | /opt/nbfc/Configs/\*.xml              | /usr/share/nbfc/configs/\*.json             |
|Service binary                   | /opt/nbfc/nbfcservice.sh              | /bin/nbfc\_service                          |
|PID File                         | /run/nbfc.pid                         | /run/nbfc\_service.pid                      |
|Config file                      | ?                                     | /etc/nbfc/nbfc.json                         |

- NBFC-Linux is engineered to be rock solid. It explicitly protects itself from the Linux OOM killer by setting `/proc/self/oom_score_adj` to `-1000`. Additionally, all necessary memory allocations are completed at startup, ensuring that the process cannot run out of memory during runtime. Once running, the program's memory usage is fully deterministic. These stability guarantees are not present in the original NBFC project.

- The original NBFC service adjusts the fan speeds in intervals of `EcPollIntervall` according to `TemperatureThresholds`. - NBFC Linux directly sets the fan speed (also according to `TemperatureThresholds`).

- The original NBFC service selects a TemperatureThreshold and applies its `FanSpeed` when the temperature exceeds its `UpThreshold`. In contrast, NBFC Linux will select the *next* TemperatureThreshold and apply its `FanSpeed` when the temperature exceeds the *current* `UpThreshold`. The provided config files have been reconfigured to account for this change, so that they provide the same behaviour as the original NBFC service. If you have a custom config file that works well with the original service, you can port it to NBFC Linux using `nbfc xml2json`.

- NBFC Linux dropped the `Autostart` option, since it relies on the systemd service file only.

Troubleshooting
---------------

The preferred way of running nbfc is using the `ECSysLinux` implementation, which depends on the `ec_sys` kernel module.
There is also an alternative implementation which uses `/dev/port`, called `dev_port`.
It can be specified on the commandline using `--embedded-controller=dev_port` and permanently set in `/etc/nbfc/nbfc.json` with `"EmbeddedControllerType": "dev_port"`.

Many Linux distributions do not provide the `ec_sys` module, and the module should be compiled manually. Alternatively, the [`acpi_ec`](https://github.com/MusiKid/acpi_ec) module can be used. The `acpi_ec` module comes with a DKMS config script, which automatically rebuilds the `acpi_ec` module when a new kernel is installed and supports running NBFC with Secure Boot and Lockdown Kernel. NBFC-Linux will try to use the `acpi_ec` module if available. It can be set with `"EmbeddedControllerType": "acpi_ec"`.

Advanced Compilation
--------------------

NBFC-Linux allows disabling features at compile time to produce an even smaller binary.

Pass the following flags to `./configure` to disable specific components.

- `--disable-syslog`: Don't log to syslog in daemon mode
- `--disable-ec-debug`: Disable debugging of reads/writes from/to the embedded controller
- `--disable-ec-dummy`: Disable the dummy embedded controller implementation
- `--disable-ec-dev-port`: Disable the /dev/port embedded controller implementation
- `--disable-ec-sys`: Disable the embedded controller implementation that relies on `ec_sys` kernel module
- `--disable-ec-acpi`: Disable the embedded controllern implementation that relies on the `acpi_ec` kernel module

See [Configure Command Generator](https://nbfc-linux.github.io/compile/) for an interactive interface to generate the `./configure` command.

Shell autocompletion
--------------------

NBFC-Linux comes with shell completion scripts for Bash, Fish and Zsh.

The completion files are generated using [crazy-complete](https://github.com/crazy-complete/crazy-complete).

```
~ $ nbfc_service <TAB>
--config-file          -c  -- Use alternative config file (default /etc/nbfc/nbfc.json)
--debug                -d  -- Enable tracing of reads and writes of the embedded controller
--embedded-controller  -e  -- Specify embedded controller to use
--fork                 -f  -- Switch process to background after sucessfully started
--help                 -h  -- show this help message and exit
--read-only            -r  -- Start in read-only mode

~ $ nbfc <TAB>
acpi-dump       -- Dumps information of your ACPI DSDT
config          -- List or apply configs
get-model-name  -- Print model name for notebook
help            -- Show help
rate-config     -- Rate a configuration file
restart         -- Restart the service
sensors         -- Configure fan sensors
set             -- Control fan speed
start           -- Start the service
status          -- Show the service status
stop            -- Stop the service
support         -- Show how to support the project
update          -- Download new configuration files
wait-for-hwmon  -- Wait for /sys/class/hwmon/hwmon* files
warranty        -- Show warranty
```

Contributing
------------

You can write a configuration file for your laptop model. See the [Configuration HowTo](https://nbfc-linux.github.io/creating-config/) and [Wiki of the original NBFC](https://github.com/hirschmann/nbfc/wiki/How-to-create-a-NBFC-config) for more details.

If you found a working configuration for your laptop model, you can register it in the [Compatibility Database](share/nbfc/model_support.json).

If you want to write a program that controls the NBFC service, see the [protocol](/PROTOCOL.md).

Developers are welcome to try optimizing the code of the service for memory usage. However, be warned that it is likely a waste of time, as the author has already tried every possible approach. It seems that every line of code is necessary for the current functionality.

See also the documentation about the [nbfc configuration](doc/nbfc_service.json.5.md).

nbfc-linux

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README