NBFC-SERVICE.JSON(5)

NAME

nbfc_service.json - Notebook FanControl service configuration

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

  ServiceConfig

Main configuration file of nbfc_service (/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 beeing 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).

CriticalTemperatureOffset: Integer > 0
    See CriticalTemperature.

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.

LuaLibraries: Array of String
    Import additional Lua libaries. 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.

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 (everytime the fan control service starts).

    •   OnWriteFanSpeed: writes the value everytime 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 option is mutually exclusive to AcpiMethod and LuaCode. Only one of them can be set at a time.

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. See LUA CODE. 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.

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 a time.

ResetWriteMode: String
    See WriteMode. Will only be applied on reset.

Description: String
    A short description of what effect the RegisterWriteConfiguration will have.

  FanSpeedPercentageOverride

Overrides the default algorithm to calculate fan speeds.

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.

  TemperatureThreshold

Defines how fast the fan runs at different temperatures.

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. Lua code can be specified as either a String or an Array of String.

  Return Values
Every Lua code must return exactly to 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).

  Availabe 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.

  Coding Conventions
If possible, use the variables e (error) and v (value) for capturing the result of NBFC functions.

  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.

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. 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

/etc/nbfc/nbfc.json
    The main configuration file for nbfc_service.
/run/nbfc_service.pid
    File containing the PID of current running nbfc_service.
/run/nbfc_service.socket
    Socket file of nbfc_service.

/usr/share/nbfc/configs/*.json
    Configuration files for various notebook models.
/usr/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 /usr/share/nbfc/configs.
/var/lib/nbfc/model_support.json
    Model support database downloaded from the internet. Both /var/lib/nbfc/model_support.json and /usr/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)

SEE ALSO

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