NBFC-LINUX(7)

📦 version 0.5.4, in nixpkgs unstable

okay bestie, welcome to NBFC-LINUX(7) — the Miscellaneous Information Manual for NBFC-Linux 💖 this is the whole lore, and yes, it’s giving “your notebook’s fans are about to become main character energy.”

🌸 GENERAL 🌸

✨ What is NBFC-Linux? ✨

NBFC-Linux is a C port of the original but unmaintained C# software NBFC (NoteBook FanControl). It allows you to control the notebook’s fans by accessing the embedded controller (EC) or invoking ACPI methods. It shares the same utilities and interfaces as the original NBFC. periodt.

🦋 What is the difference between NBFC and NBFC-Linux? 🦋

NBFC-Linux is specifically designed and optimized for the Linux ecosystem. lowkey its whole personality.

It also comes with features that the original NBFC does not have, such as:

  • Configuration rating (nbfc rate-config)
  • Support for calling ACPI methods
  • Lua scripting
  • Online configuration fetching
  • Firmware fingerprinting
  • Shell autocompletion for Bash, Fish and Zsh.

🎀 INSTALLATION 🎀

🌈 Where to get NBFC-Linux from? 🌈

NBFC-Linux can be downloaded from https://github.com/nbfc-linux/nbfc-linux.

Packages are available for Ubuntu, Linux Mint, Debian, Fedora, OpenSUSE and Arch Linux. slay.

🧚 Which kernel modules are required? 🧚

For accessing the embedded controller:

The embedded controller can also be accessed through /dev/port (without any kernel module).

For invoking ACPI methods:

  • acpi_call (manual compilation may be required for some distributions)

💅 CONFIGURATION 💅

🌸 Updating configurations 🌸

To fetch the latest configuration files from the project repository, run:

sudo nbfc update

🦋 Setting a configuration 🦋

To set a configuration, run:

sudo nbfc config --set CONFIG

Where CONFIG is the base filename of a configuration (without .json file extension).

⭐ Testing configurations automatically ⭐

Configurations can be tested automatically by calculating a correlation score between CPU/GPU temperature and the fan speed reported by each configuration.

First, collect the data by running:

sudo nbfc rate-config --all -q -q | sudo nbfc test-config run --cpu 8
  • With a dedicated GPU (this may require proprietary GPU drivers):
sudo nbfc rate-config --all -q -q | sudo nbfc test-config run --cpu 8 --gpu 8

These commands write the nbfc.test-config.result.json file.

The results can be evaluated by running:

nbfc test-config evaluate

🫶 Testing a configuration manually 🫶

When trying out configuration files, it is recommended to follow these steps:

  1. Set the configuration using sudo nbfc config --set CONFIG
  2. Start the service in read-only mode using sudo nbfc restart --read-only
  3. Let the fan spin up and down by stressing the CPU (using stress -c 8)
  4. Check if the reported fan speed matches the real (physical) fan speed using nbfc status
  5. If this is the case, restart the service in write-mode using sudo nbfc restart
  6. Now you can change the fan speed. See USAGE

💜 Finding a suitable configuration 💜

🌟 Automatic detection 🌟

To automatically select a configuration that matches your notebook model name, run:

sudo nbfc config --set auto

🔥 Configuration rating 🔥

To get a list of configurations that are safe to execute on the current system and may work on the device, run:

sudo nbfc rate-config --all

🎀 Configurations with similar names 🎀

To get a list of configuration files with a name similar to the current notebook model, run:

nbfc config --recommend
WARNING: A similar model name does not mean that the configuration can be safely used on the device. It can actually be dangerous. Please only use configurations from this output if you are absolutely sure it is appropriate for your device. no cap, this is the serious part.

🧚 Converting an XML model configuration from the original NBFC 🧚

If you found a configuration that was made for the original NBFC project, you can convert it using:

nbfc xml2json INFILE.xml > OUTFILE.json

In order to use the configuration, it has to be copied to /nix/store/48mhb6ci6w735jxaz60mhn63p4ccn956-nbfc-linux-0.5.4/share/nbfc/configs/.

Such configurations may be available in the NBFC-Revive project, see https://github.com/UraniumDonut/nbfc-revive.

🦋 ADVANCED CONFIGURATION 🦋

🌸 Changing temperature sensors attached to a fan 🌸

If a model configuration does not configure sensors for a fan, then the default will be used, which is @CPU, meaning all CPU-associated sensors.

You may have to change the sensors attached to a fan, e.g. setting a fan to the @GPU sensor group.

To override the default sensors, use this command:

sudo nbfc sensors set -f FAN [-s SENSOR...]  [-a ALGORITHM]

ALGORITHM is one of:

  • Min (take the minimum temperature among all specified sensors)
  • Max (take the maximum temperature among all specified sensors)
  • Average (calculate the average temperature among all specified sensors; default)

SENSOR may either be a:

  • temperature file
  • sensor name (which will result in one or more temperature files)
  • sensor group (@CPU, @GPU)
NOTE: If you are writing model configuration files, use the Sensors field. It is recommended to use sensor groups, so that the configuration works on many systems regardless of the hardware.

🌟 Showing sensors attached to a fan 🌟

To show all fans with their configured sensors, run:

nbfc sensors show

🎀 Finding all available sensors 🎀

To get a list of all available sensors, run:

nbfc sensors list

✨ USAGE ✨

💖 Getting the service status 💖

To get information about the service, including the notebook’s fans, run:

nbfc status

🔥 Setting the fan speed 🔥

To set the speed of all available fans, run:

nbfc set -s PERCENT

To set all available fans to profile based automatic control, run:

nbfc set -a

To apply the fan speed to only a specific fan, run:

nbfc set -s PERCENT -f FAN
NOTE: FAN is a number starting from zero. iykyk.

🎀 MISCELLANEOUS 🎀

🌈 Starting NBFC-Linux automatically at boot time 🌈

NBFC-Linux comes with a systemd service file.

To enable NBFC-Linux to start on boot, run:

sudo systemctl enable nbfc_service.service

💜 Resetting the notebook’s fans to the default behaviour 💜

If the model configuration file for the notebook has been written properly, then

sudo nbfc stop
- or -
sudo systemctl stop nbfc_service

should reset the notebook’s fans to their default behaviour.

In 99% of cases, a reboot will also reset the embedded controller.

💀 TROUBLESHOOTING 💀

🫠 Error: No such configuration available

The selected config file (as referenced by SelectedConfigId in /etc/nbfc/nbfc.json) does not exist.

😭 Error: No working implementation found for accessing the embedded controller

Neither ec_sys nor acpi_ec kernel modules are available. Access through /dev/port is also not possible.

🙈 Error: /sys/kernel/debug/ec/ec0/io: Invalid argument

The ec_sys kernel module is loaded, but write_support is disabled.

Edit /etc/default/grub and find the line GRUB_CMDLINE_LINUX_DEFAULT then append ec_sys.write_support=1 to it.

For example, the line should look like this:

GRUB_CMDLINE_LINUX_DEFAULT="quiet kvm.enable_virt_at_load=0 ec_sys.write_support=1"

Then run sudo update-grub and reboot your system.

💀 Error: Could not load kernel module "acpi_call"

The acpi_call kernel module is missing. Install or build it as needed.

🌸 Error: /proc/acpi/call: AE_NOT_FOUND

An unknown ACPI method was invoked. It usually indicates an incorrect or incompatible configuration.

🦋 Error: @GPU: No sensors found

The notebook either doesn't have a dedicated GPU or requires proprietary (NVIDIA) drivers.

🌟 NOTEBOOK FIRMWARE BACKGROUND 🌟

🧚 What is an embedded controller (EC)? 🧚

The embedded controller is a microcontroller within modern notebook computers. It manages system hardware functions such as fan speed, battery charging, keyboard control, LCD backlight and many more.

⭐ What is ACPI? ⭐

The Advanced Configuration and Power Interface (ACPI) is an open industry standard for device configuration and power management. ACPI methods allow the operating system to control various hardware components.

🛠️ CONFIGURATION DEVELOPMENT

⚠️ Safety Considerations

Okay bestie, read this one twice. Only poke at EC registers or ACPI methods that you fully understand. Like, actually understand-understand, not "I skimmed a forum post" understand. Misuse can damage hardware. And if you can, pull the battery while you're building a config — because accidentally modifying battery registers may brick the battery permanently. Not "oops reboot" bricked. Bricked bricked. 😭

🏷️ Naming configuration files

Easy one: use the output of nbfc get-model-name as the configuration's filename. That's it. That's the rule. ✨

🔍 How to analyze the firmware?

To get a list of all registers that are accessible through the embedded controller, run:

sudo nbfc acpi-dump ec-registers

To get a list of all embedded controller registers, run:

sudo nbfc acpi-dump registers
🚨 WARNING: Do not try to access those registers through ec_probe, because they are not exposed through the embedded controller. Only write to registers that are listed by sudo nbfc acpi-dump ec-registers. Please, king. 🙏

To get a list of all ACPI methods, run:

sudo nbfc acpi-dump methods

To disassemble all the ACPI firmware tables, run:

sudo nbfc acpi-dump dsl

🌀 How to identify fan registers?

Go hunting for registers named like FAN, RPM, PWM, etc. 💅

Examples: SFAN CFAN PFAN FAN1 FSW1 FRDC FTGC RPM1 RPM2

🧚 How to identify ACPI methods?

Same vibe, but for methods — search for names like FAN, RPM, PWM, etc.

Examples: FANG FANW GFSD SFSD SFNV FRSP STMM GFRM

🎛️ Accessing the embedded controller

For reading a register:

sudo ec_probe read REGISTER

For reading a 16-bit register:

sudo ec_probe read --word REGISTER

For writing to a register:

sudo ec_probe write REGISTER VALUE

For writing to a 16-bit register:

sudo ec_probe write --word REGISTER VALUE

For reading a single bit from a register:

sudo ec_probe read_bit REGISTER OFFSET

For writing a single bit to a register:

sudo ec_probe write_bit REGISTER OFFSET VALUE

📞 Invoking ACPI methods

To call an ACPI method, run:

sudo ec_probe acpi_call '\METHOD ARGS...'

📈 Tracing embedded controller changes

Honestly this is the fun part. It's genuinely useful to trace the registers of the embedded controller as the fan spins up and down. 🌬️

To do so, make sure the fan is at its lowest speed first, then run:

sudo ec_probe monitor --cpu --report OUTFILE.csv

- With a dedicated GPU (this may require proprietary GPU drivers)
-

sudo ec_probe monitor --cpu --gpu --report OUTFILE.csv

While recording, first stress the CPU and then after a while the GPU:

stress-ng --cpu 8

stress-ng --gpu 8

Once the fans have reached their highest speeds, stop the stress-ng command and wait until the fans are back at their lowest speed again. 😮‍💨

Now you can kill the ec_probe monitor command (Ctrl+C) and inspect the OUTFILE.csv for register changes. Detective era. 🔍

You can also visualize the OUTFILE.csv by running:

ec_probe graph OUTFILE.csv

For finding correlations between register values and CPU/GPU temperatures automatically, run:

ec_probe evaluate OUTFILE.csv

🌙 Writing complex configurations with Lua

Sometimes a firmware must be accessed in a more complex way than the NBFC software supports. Like, for example, ACPI commands have to be constructed, or the readings of the embedded controller have to be modified. That's when Lua steps in. 💜

See nbfc_service.json(5) for details.

🫰 Firmware Fingerprinting

Firmware fingerprinting is especially useful if a model configuration file uses ACPI WMI methods. Because these methods often have the same names but not the same implementation, it is necessary to look for characteristics in the firmware that confirm it is the intended firmware. Basically a vibe check for firmware. iykyk. 👑

See nbfc_service.json(5) for details.

🆘 Getting Help

See nbfc_service.json(5) for details.

For more information, see the Creating Model Configuration HowTo: https://nbfc-linux.github.io/creating-config/

For further assistance, visit the project at GitHub: https://github.com/nbfc-linux/nbfc-linux

💖 CONTRIBUTING

📎 Contributing a configuration file

When contributing a configuration file, please also attach your firmware. You can create an archive containing your firmware by running:

sudo nbfc support --create-archive ARCHIVE.tar.gz

This helps the developer validate your configuration and keep the register-name database up to date. Teamwork makes the dream work, fr fr. 🫶

💻 Contributing code

Before contributing code, please open an issue and ask if the contribution is wanted. This helps avoid frustration and prevents unnecessary work. Nobody wants to write 400 lines and then hear "actually no". 😭

☁️ Uploading your firmware

Uploading your notebook firmware helps the developer to understand existing configuration files.

The following data will be transmitted:

  • The laptop manufacturer (/sys/devices/virtual/dmi/id/sys_vendor)
  • The laptop model (/sys/devices/virtual/dmi/id/product_name)
  • The ACPI DSDT firmware table (/sys/firmware/acpi/tables/DSDT)
  • The ACPI SSDT firmware tables (/sys/firmware/acpi/tables/SSDT*)

The preferred method for uploading your notebook firmware is to use:

sudo nbfc support --upload-firmware

However, if you're paranoid, you can upload it manually using curl:

nbfc support --print-command

👑 AUTHOR

Benjamin Abendroth (braph93@gmx.de)

🌈 SEE ALSO

nbfc(1), nbfc_service(1), nbfc_service.json(5), ec_probe(1)

okay that's the whole page bestie, go forth and read your registers responsibly 💅✨

this iconic lil manual is the NBFC-Linux Manual, dated June 2026 — mwah, no notes 🎀🦋

📦 where this page comes from