NBFC-SERVICE.JSON(5)

📦
version 0.5.4 · 2 versions
, in nixpkgs unstable

💅 NAME 💅

nbfc_service.json is the Notebook FanControl service configuration, bestie — section 5 energy, and this is the whole config vibe for nbfc_service. Every field is getting its moment. 💖

✨ CONFIGURATION ✨

💡 NOTE: Comments can be added in any JSON object by using the Comment or the # field.

🛠️ ServiceConfig

Main configuration file of nbfc_service (/nix/store/48mhb6ci6w735jxaz60mhn63p4ccn956-nbfc-linux-0.5.4/etc/nbfc/nbfc.json).

  • SelectedConfigId: String — The selected config model. This equals the basename of a notebook model configuration file. Absolute file paths can also be specified.
  • EmbeddedControllerType: String — Selects the implementation used to access the embedded controller.
    • ec_sys — Use the ec_sys kernel module.
    • acpi_ec — Use the acpi_ec kernel module.
    • dev_port — Access the embedded controller via /dev/port.
    • dummy — Do not access the embedded controller at all.

If not given, the embedded controller type will be automatically selected.

  • FanTemperatureSources: Array of FanTemperatureSourceConfig — Used for configuring which sensors are attached to a fan.

🌸 FanTemperatureSourceConfig 🌸

Configures which sensors are attached to a fan.

  • FanIndex: Integer >= 0 && Integer <= 255 — Specify which fan should be configured.
  • TemperatureAlgorithmType: String — See FanConfiguration->TemperatureAlgorithmType.
  • Sensors: Array of String — See FanConfiguration->Sensors.

🦋 ServiceState 🦋

State file of the service (/var/lib/nbfc/state.json).

  • TargetFanSpeeds: Array of Float — This holds the fixed speed of the fans. A value of -1 means the fan should be left in auto mode.

🎀 ModelConfig 🎀

  • NotebookModel: String — The Notebook Model as described in your BIOS. See nbfc get-model-name.
  • Author: String — The Author of the config file. Enter whatever you want.
  • LegacyTemperatureThresholdsBehaviour: Boolean — This option was introduced for being backwards compatible with configuration files from the original NBFC project. The default is false. Do not use this option for new configuration files.
  • EcPollInterval: Integer > 0 — Defines how often NBFC polls the EC for changes (in milliseconds).
  • CriticalTemperature: Integer — If the temperature exceeds this threshold, NBFC will ignore all Temperature threshold elements and set the fan to 100% speed until the temperature drops below (CriticalTemperature minus CriticalTemperatureOffset).

Can be overwritten by FanConfiguration's CriticalTemperature.

  • CriticalTemperatureOffset: Integer > 0 — See CriticalTemperature.

Can be overwritten by FanConfiguration's CriticalTemperatureOffset.

  • ReadWriteWords: Boolean — If true, NBFC will combine two 8 bit registers to one 16-bit register when reading from or writing to the EC registers.

DEPRECATED. Use FanConfiguration->ReadWords and FanConfiguration->WriteWords instead.

  • LuaLibraries: Array of String — Import additional Lua libraries.

Example: "LuaLibraries": ["math"]

Available libraries:

  • base — Provides core global functions.
  • math — Provides standard mathematical functions and constants.
  • string — Provides functions for pattern matching and basic string manipulation.
  • table — Provides utilities for creating and manipulating tables (arrays and dictionaries).
  • io — Provides file input/output facilities and stream-based I/O operations.
  • os — Provides operating system interface functions such as time, environment, and process control.
  • FirmwareFingerprint: Array of String — See FIRMWARE FINGERPRINTING.
  • FanConfigurations: Array of FanConfiguration — Array of at least one FanConfiguration
  • RegisterWriteConfigurations: Array of RegisterWriteConfiguration — Array of RegisterWriteConfiguration

🌈 FanConfiguration 🌈

Defines how NBFC controls a fan.

  • FanDisplayName: String — Sets the fan display name.
  • CriticalTemperature: Integer — If the temperature exceeds this threshold, NBFC will ignore all Temperature threshold elements and set the fan to 100% speed until the temperature drops below (CriticalTemperature minus CriticalTemperatureOffset).
  • CriticalTemperatureOffset: Integer > 0 — See CriticalTemperature.
  • ReadWords: Boolean — If true, NBFC will combine two 8 bit registers to one 16-bit register when reading from the EC.

Overrides ModelConfig->ReadWriteWords.

  • WriteWords: Boolean — If true, NBFC will combine two 8 bit registers to one 16-bit register when writing to the EC.

Overrides ModelConfig->ReadWriteWords.

  • ReadRegister: Integer >= 0 && Integer <= 255 — The register from which NBFC reads the fan speed.

This option is mutually exclusive to ReadAcpiMethod and ReadLuaCode. Only one of them can be set at a time.

  • ReadAcpiMethod: String — The ACPI method for reading the fan speed.

Example:

"ReadAcpiMethod": "\\_SB.PCI0.LPCB.EC0.GFSD"

This option is mutually exclusive to ReadRegister and ReadLuaCode. Only one of them can be set at a time.

  • ReadLuaCode: String or Array of String — The Lua code to be executed for reading the fan speed. See LUA CODE.

Example:

"ReadLuaCode": "return
acpi_call(\"\\\\_SB.PCI0.LPCB.EC0.GFSD\")"

This option is mutually exclusive to ReadRegister and ReadAcpiMethod. Only one of them can be set at a time.

  • WriteRegister: Integer >= 0 && Integer <= 255 — The register which NBFC uses to control the fan.

This option is mutually exclusive to WriteAcpiMethod and WriteLuaCode. Only one of them can be set at a time.

  • WriteAcpiMethod: String — The ACPI method for writing the fan speed. The command must contain a placeholder ($) which will be replaced by the fan speed.

Example:

"WriteAcpiMethod": "\\_SB.PCI0.LPCB.EC0.SFSD $"

This option is mutually exclusive to WriteRegister and WriteLuaCode. Only one of them can be set at a time.

  • WriteLuaCode: String or Array of String — The Lua code to execute for writing the fan speed. See LUA CODE.

Example:

"WriteLuaCode": "return
acpi_call(\"\\\\_SB.PCI0.LPCB.EC0.SFSD \" .. get_value())"

This option is mutually exclusive to WriteRegister and WriteAcpiMethod. Only one of them can be set at a time.

  • MinSpeedValue: Integer >= 0 && Integer <= 65535 — The value which puts the fan to the lowest possible speed (usually this stops the fan). Must be an integer between 0 and 255 or 0 and 65535 if ReadWriteWords is true. Note: MinSpeedValue does not necessarily have to be smaller than MaxSpeedValue.
  • MaxSpeedValue: Integer >= 0 && Integer <= 65535 — The value which puts the fan to the highest possible fan speed.
  • MinSpeedValueRead: Integer >= 0 && Integer <= 65535 — The value which corresponds to the lowest possible fan speed. Will be ignored if IndependentReadMinMaxValues is false.
  • MaxSpeedValueRead: Integer >= 0 && Integer <= 65535 — The value which corresponds to the highest possible fan speed. Will be ignored if IndependentReadMinMaxValues is false.
  • IndependentReadMinMaxValues: Boolean — Defines if independent minimum/maximum values should be applied for read operations.

This enables MinSpeedValueRead and MaxSpeedValueRead.

  • ResetRequired: Boolean — Defines if the EC should be reset before the service is shut down.
  • FanSpeedResetValue: Integer >= 0 && Integer <= 65535 — Defines the value which will be written to WriteRegister to reset the EC.

This option is mutually exclusive to ResetAcpiMethod and ResetLuaCode. Only one of them can be set at a time.

  • ResetAcpiMethod: String — The ACPI method to call upon fan reset.

This option is mutually exclusive to FanSpeedResetValue and ResetLuaCode. Only one of them can be set at a time.

  • ResetLuaCode: String or Array of String — The Lua code to be executed upon fan reset. See LUA CODE.

This option is mutually exclusive to FanSpeedResetValue and ResetAcpiMethod. Only one of them can be set at a time.

  • Sensors: Array of String — Defines which sensors shall be used for this fan. This should either be a sensor name or a sensor group.

Available groups:

  • @CPU — Uses all sensors named coretemp, k10temp or zenpower
  • @GPU — Uses all sensors named amdgpu, nvidia, nvidia-ml, nouveau or radeon
  • TemperatureAlgorithmType: String — Specify the algorithm type to compute the temperature.
    • Average — Computes the average temperature from all specified sensors (default)
    • Min — Selects the lowest temperature among all specified sensors
    • Max — Selects the highest temperature among all specified sensors
  • TemperatureThresholds: Array of TemperatureThreshold — Defines how fast the fan runs at different temperatures.
  • FanSpeedPercentageOverrides: Array of FanSpeedPercentageOverride — Overrides the default algorithm to calculate fan speeds.

🧚 RegisterWriteConfiguration 🧚

Allows to write to any EC register.

  • WriteMode: String — Defines how the value will be written:
    • Set — overwrites the register with the specified value (register = value)
    • And — performs a binary AND operation (register = register & value)
    • Or — performs a binary OR operation (register = register | value)
    • Call — calls the ACPI method stored in AcpiMethod or ResetAcpiMethod
    • Lua — executes the Lua code stored in LuaCode or ResetLuaCode
  • WriteOccasion: String — Defines when the value should be written:
    • OnInitialization — writes the value once upon initialization (every time the fan control service starts).
    • OnWriteFanSpeed — writes the value every time the fan speed is set.
  • Register: Integer >= 0 && Integer <= 255 — The register which will be manipulated.
  • Value: Integer >= 0 && Integer <= 255 — The value which will be written.

This one's mutually exclusive to AcpiMethod and LuaCode bestie — only one of them can be set at a time, no cap 💅

  • AcpiMethod: String — the ACPI method to call. ✨ This option is mutually exclusive to Value and LuaCode. Only one of them can be set at a time.
  • LuaCode: String or Array of String — the Lua code to be executed. Peep LUA CODE below for the deets. 🔮 This option is mutually exclusive to Value and AcpiMethod. Only one of them can be set at a time.
  • ResetRequired: Boolean — defines if the register should be reset before the service is shut down. 💀 lowkey important.
  • ResetValue: Integer >= 0 && Integer <= 255 — the value which will be written upon reset. This option is mutually exclusive to ResetAcpiMethod and ResetLuaCode. Only one of them can be set at a time.
  • ResetAcpiMethod: String — the ACPI method to call upon reset. This option is mutually exclusive to ResetValue and ResetLuaCode. Only one of them can be set at a time.
  • ResetLuaCode: String or Array of String — the Lua code to be executed upon reset. See LUA CODE. This option is mutually exclusive to ResetValue and ResetAcpiMethod. Only one of them can be set at a time.
  • ResetWriteMode: String — see WriteMode. Will only be applied on reset, iykyk ✨
  • Description: String — a short description of what effect the RegisterWriteConfiguration will have. just a lil blurb 🎀

🌸 FanSpeedPercentageOverride 🌸

Overrides the default algorithm to calculate fan speeds. it's giving "I know better than the math" energy 😌

  • FanSpeedPercentage: Float >= 0.0 && Float <= 100.0 — the fan speed in percent.
  • FanSpeedValue: Integer >= 0 && Integer <= 65535 — the fan speed value which will be written to WriteRegister.
  • TargetOperation: String — defines for which operations the speeds should be overridden:
    • Read: if the value in the EC's ReadRegister is equal to FanSpeedValue, the corresponding percentage will not be calculated, but instead be set to FanSpeedPercentage.
    • Write: if the target fan speed percentage is equal to FanSpeedPercentage, the corresponding value will not be calculated, but instead be set to FanSpeedValue.
    • ReadWrite: applies to both, read and write operations. both is good 🫶

🌡️ TemperatureThreshold 🌡️

Defines how fast the fan runs at different temperatures. the whole vibe curve, fr fr 🌈

  • UpThreshold: Integer — NBFC will select the next upper threshold as soon as the temperature exceeds UpThreshold (in celsius).
  • DownThreshold: Integer — NBFC will select the next lower threshold as soon as the temperature falls below the DownThreshold (in celsius).
  • FanSpeed: Float >= 0.0 && Float <= 100.0 — the fan speed in percent.

🧚 LUA CODE 🧚

NBFC-Linux allows executing Lua code to implement more complex read or write operations. yes bestie, you can write actual logic in here 🔥

Lua code can be specified as either a String or an Array of String.

⭐ Return Values ⭐

Every Lua code must return exactly two values: Error, Result.

Error is either nil (on success) or a string describing the error (on failure).

Result is an integer and is used for read operations. For write operations this value is ignored (returning 0 is recommended). like, it's not even looking at it 🙈

💜 Available Lua Functions 💜

The following functions are exposed to Lua:

  • acpi_call(method): Executes an ACPI method. Returns error, value (integer).
  • acpi_call_raw(method): Executes an ACPI method and returns the raw result as a string. Returns error, value (string).
  • acpi_get_int(acpi_result, path): Extracts the integer located at path from an ACPI result. Returns error, value (integer).

Example:

result = "{[0x0, 0x0], [0xFF, 0x0]}"
e, v = acpi_get_int(result, "1 0")
-- v is 0xFF
  • ec_read(register): Reads a byte from the embedded controller. Returns error, value.
  • ec_read_word(register): Reads two bytes and combines them into a single value. Returns error, value.
  • ec_write(register, value): Writes a byte to the embedded controller. Returns error, 0.
  • ec_write_word(register, value): Writes a 16-bit value to a two-byte register. Returns error, 0.

🎀 Lua Libraries 🎀

To keep memory usage as low as possible, no Lua libraries are loaded by default. They must be explicitly loaded when needed. See ModelConfig->LuaLibraries for details. ngl, load only what you need, she's on a diet 💅

🦋 Coding Conventions 🦋

If possible, use the variables e (error) and v (value) for capturing the result of NBFC functions. it's just cute, okay? 🫶

🌸 Testing Configuration 🌸

If a configuration uses Lua code, ensure that it works correctly with nbfc rate-config. During rating, nbfc rate-config replaces all NBFC-specific Lua functions with dummy implementations that always return nil, 1. so like, test it before you commit to it bestie 😭

👑 FIRMWARE FINGERPRINTING 👑

Firmware fingerprinting can be used to ensure that a configuration file matches a specific notebook firmware.

This is especially important for configurations that invoke WMI methods. Many notebook vendors reuse the same WMI method names across different notebook models while changing the internal implementation and method arguments. As a result, matching method names alone is often insufficient to determine whether a configuration is compatible with a specific firmware. the way that method names are basically catfishing you 💀

Fingerprinting allows AML methods to be analyzed for specific code patterns.

🔍 Fingerprint Syntax 🔍

Fingerprints are written using AML syntax. A fingerprint always begins with a method definition, followed by AML code that is searched for within the method body.

In addition to regular AML syntax, two wildcard operators are supported:

  • .. — matches any code within the current block scope, but only at the current scope level.
  • ... — matches any code within the current block scope, including code contained in nested scopes.

Example:

Given the following method:

Method (\FOO, 2, Serialized) {
    SMTH()

    Switch (Arg0) {
        Case (0xDEAD) {
            If (Arg1 == 0xBEEF) {
                FMTH()
                Return (One)
            }
        }
    }
}

The following patterns would match:

  • Method(\FOO)
  • Method(\FOO) { ... 0xDEAD
  • Method(\FOO) { ... 0xBEEF
  • Method(\FOO) { ... Switch (Arg0) { .. Case (0xDEAD)
  • Method(\FOO) { ... Switch (Arg0) { .. Case (0xDEAD) { ... If (Arg1 == 0xBEEF)
  • Method(\FOO) { ... Switch (Arg0) { .. Case (0xDEAD) { ... If (Arg1 == 0xBEEF) { ... FMTH()
  • Method(\FOO) { ... Switch (Arg0) { .. Case (0xDEAD) { ... FMTH()

The following patterns would not match:

  • Method(\FOO) { .. 0xDEAD
  • Method(\FOO) { Switch (Arg0)

🧚 Matching Rules 🧚

  • Whitespace is ignored
  • Comments are ignored
  • Only the basename of the identifiers are matched
  • Only scope hierarchy and ordering are considered
  • Intermediate code between matched blocks is ignored

⭐ Recommendations ⭐

When writing fingerprints:

  • Match magic numbers used by WMI method calls whenever possible
  • Do not use fully qualified identifiers (use FOO instead of _SB.DEV0.FOO)
  • Avoid unnecessary parentheses, as they are ignored during matching (use If (FOO == 0x0) instead of If ((Foo == 0x0)))
  • The .. operator should only be used when matching a direct child block is required. A common example is matching Case() blocks within a Switch() statement, where only direct descendants should be considered.

🍓 FILES 🍓

  • /nix/store/48mhb6ci6w735jxaz60mhn63p4ccn956-nbfc-linux-0.5.4/etc/nbfc/nbfc.json — the main configuration file for nbfc_service. the main character, honestly 👑
  • /run/nbfc_service.pid — file containing the PID of current running nbfc_service.
  • /run/nbfc_service.socket — socket file of nbfc_service.
  • /nix/store/48mhb6ci6w735jxaz60mhn63p4ccn956-nbfc-linux-0.5.4/share/nbfc/configs/*.json — configuration files for various notebook models.
  • /nix/store/48mhb6ci6w735jxaz60mhn63p4ccn956-nbfc-linux-0.5.4/share/nbfc/model_support.json — model support database. This file maps notebook model names to configuration files.
  • /var/lib/nbfc/configs/*.json — configuration files downloaded from the internet. Files in this directory take precedence over those in /nix/store/48mhb6ci6w735jxaz60mhn63p4ccn956-nbfc-linux-0.5.4/share/nbfc/configs. she comes first, periodt 💅
  • /var/lib/nbfc/model_support.json — model support database downloaded from the internet. Both /var/lib/nbfc/model_support.json and /nix/store/48mhb6ci6w735jxaz60mhn63p4ccn956-nbfc-linux-0.5.4/share/nbfc/model_support.json are taken into account.
  • /var/lib/nbfc/state.json — state file of nbfc_service. This holds the current fan speeds. 🌬️

💖 AUTHOR 💖

Benjamin Abendroth (braph93@gmx.de) — king behavior, honestly 👑

🌈 SEE ALSO 🌈

nbfc(1), nbfc_service(1), ec_probe(1), fancontrol(1), sensors(1)

okay that's the whole thing bestie, you ate that 💅✨ This is Notebook FanControl 0.5.4, dated APRIL 2026 — go forth and keep those fans cute and quiet 🎀🦋💜
📦 where this page comes from