Skip to content

Brightness and calibration

ShellCode33 edited this page Nov 15, 2026 · 2 revisions

Brightness and calibration

Understand the numbers first

backlightctl --devices
backlightctl --devices --json

Device details distinguish:

Field Meaning
requested_percent Retained logical target from a successful command, or null
brightness_percent Logical percentage representable by the stored hardware value
hardware_percent Raw control value as a rounded percentage of the hardware maximum
hardware_raw, maximum_raw Device control value and maximum, using 32-bit integers
readback_raw Control value read during discovery; null after an unverified write
actual_raw Optional sysfs actual_brightness reading; null when unavailable/invalidated

Ordinary CLI/JSON status and Waybar average the retained logical targets across enabled monitors. If no target is retained, a device uses its inverse-mapped hardware value. Detailed device brightness_percent still reports the representable percentage, separately from requested_percent. None of these values measures emitted light in nits or guarantees equal perceived brightness between monitors. Status uses cached values; it does not perform a fresh read. To update device readings, use backlightctl --refresh.

A device with only three raw brightness steps cannot represent every percentage. With the default curve, a requested 1% may become raw 1, representable as 58%. Ordinary status still shows 1%. The daemon retains the requested target so repeated small relative changes can eventually reach the next step. External hardware changes found during discovery reset that retained intent.

Limit a monitor's hardware range

Copy its exact ID from --devices, then add:

[[devices]]
id = "COPY-THE-EXACT-ID-HERE"
minimum_percent = 5
maximum_percent = 80

Logical 0% now maps to 5% of that monitor's control range, and logical 100% maps to 80%. With the default exponent 2.0, logical 50% maps to 23.75%, rounded to a hardware step. This applies to both manual commands and automatic targets.

The same fields under [brightness] apply globally. Device rules override only the fields they specify. [automatic] limits select logical schedule endpoints; they are not a second set of raw hardware bounds.

Brightness curves and human perception

Equal increases in emitted light do not generally feel like equal increases in brightness. The default power curve allocates finer hardware adjustments near the dim end and larger adjustments near the bright end. This changes brightness control values, not image colors or the display's pixel gamma.

With hardware bounds 0–100%, the mapping is:

hardware_percent = 100 * (logical_percent / 100)^2

For example, logical 50% maps to hardware control 25%. On a monitor with raw levels 0–100, logical 1% maps below the smallest positive step and is kept at raw

  1. The inverse mapping of raw 1 is 10%, but ordinary status continues to show the requested 1%. The default automatic minimum is logical 5%, not a hardware floor.

No software curve can create extra hardware levels. Several logical targets can therefore select the same raw setting. Discovery preserves the logical target while calibration and raw readings remain unchanged; an external raw change replaces it with the inverse-mapped value. Failed writes do not claim a new successfully applied device target.

The curve is a useful control preference rather than a guarantee of perceptually equal steps. Monitor firmware, drivers, ambient lighting, and display response vary; some devices already apply a nonlinear mapping. Adjust the exponent per device, or choose 1.0 for linear control. Hardware percentages are not measured luminance or a promise of equal brightness between monitors.

[brightness]
exponent = 2.0

With default hardware bounds, logical 50% maps to 25% of the hardware range for exponent 2.0. Exponents above one provide finer low-end control; below one brighten the low end. The default is 2.0; use 1.0 for linear control. Valid values are finite and between 0.1 and 10. This is a tuning preference, not a universal correction for human perception.

Tune one screen at a time, and compare under your usual lighting. Validate and reload after editing. In manual mode, reload leaves the hardware setting unchanged; the next brightness command uses the new mapping. Auto mode reapplies its current target.

Exclude a screen

[[devices]]
id = "COPY-THE-EXACT-ID-HERE"
enabled = false

The screen remains discoverable/listed but receives no brightness/power writes and does not affect the group average. Removing the rule restores global control.

IDs and hardware limits

DDC IDs fingerprint EDID and normally survive I2C bus renumbering. Two screens with identical EDIDs share a configuration ID. Without EDID, the fallback may be bus-dependent. Sysfs IDs retain the historical acpi: prefix for compatibility; this does not mean the backend assumes ACPI firmware.

Sysfs brightness supports values beyond 65,535. DDC retains its 16-bit protocol limit. The driver/monitor remains responsible for supported steps and behavior. Backlight power, control percentages, actual driver readings, and compositor DPMS are separate mechanisms.

Clone this wiki locally