Optional arguments:¶

Arguments supplied on the command line override config file equivalent settings.

Settings Menu and Config files¶

The Settings dialog features a tab for editing common/default settings as well as tabs specific to each VDU. The config files are named according to the following scheme:

The VDU-specific config files can be used to:

The config files are in INI-format divided into a number of sections as outlined below:

[vdu-controls-globals]
# The vdu-controls-globals section is only required in $HOME/.config/vdu_controls/vdu_controls.conf
system-tray-enabled = yes|no
splash-screen-enabled = yes|no
translations-enabled = yes|no
weather-enabled = yes|no
schedule-enabled = yes|no
lux-options-enabled = yes|no
warnings-enabled = yes|no
debug-enabled = yes|no
syslog-enabled = yes|no
[vdu-controls-widgets]
# Yes/no for each of the control options that vdu_controls normally provides by default.
brightness = yes|no
contrast = yes|no
audio-volume = yes|no
audio-mute = yes|no
audio-treble = yes|no
audio-bass = yes|no
audio-mic-volume = yes|no
input-source = yes|no
power-mode = yes|no
osd-language = yes|no
# Enable ddcutil supported codes not enabled in vdu_controls by default, CSV list of two-digit hex values.
enable-vcp-codes = NN, NN, NN
# User friendly VDU name
vdu_name = My Main Monitor (on the right)
[ddcutil-parameters]
# Useful values appear to be >=0.1
sleep-multiplier = 0.5
[ddcutil-capabilities]
# The (possibly edited) output from "ddcutil --display N capabilities" with leading spaces retained.
capabilities-override =

Config files can only be used to enable and alter definitions of VCP codes supported by ddcutil. Unsupported manufacturer-specific features should only be enabled with caution; some may have irreversible consequences, including bricking the hardware.

As well as using the Settings, config files may also be created by the command line option:

vdu_controls --create-config-files

which will create initial templates based on the currently connected VDUs.

The config files are completely optional, they need not be used if the default options are found to be adequate.

Adding value restrictions to a VDU's capabilities override¶

In some cases, a VDU's DDC reported minimums and maximums may be incorrect or overstated. Within vdu_controls this can be corrected by overriding the DDC reported range. For example, perhaps a VDU reports it supports a brightness range of 0 to 100, but in fact only practically supports 20 to 90. This can be corrected by bringing up the VDU's settings tab and editing the text in the capabilities override:

For the brightness example, the completed edit would look like:

Feature: 10 (Brightness)


    Values: 20..80

The vdu_controls slider for that value will now be restricted to the specified range.

Adding a refresh/reload requirement to a VDU's capabilities override¶

Altering the values of some VCP codes may result in a cascade of changes to other codes. For example, changing a VCP value for Picture Mode might result in changes to several VCP-code features, including brightness, contrast, and others. Exactly which codes have these kinds of side effects isn't indicated in the metadata obtained from each VDU, however, vdu_controls supports adding refresh annotations to the feature-names within the capabilities override. For example:

Feature: 15 (Picture Mode)

Can be annotated with:

Feature: 15 (Picture Mode *refresh*)

With this annotation, when ever Picture Mode is altered, vdu_controls will reload all configuration files and refresh all control values from the VDUs.

DBUS ddcutil-service¶

When available, vdu_controls defaults to interacting with VDUs via the DBUS ddcutil-service service rather than the ddcutil command. The service should be both faster and more reliable (especially when multiple VDUs need to be controlled). Whether to use the service can be controlled by the DBUS client checkbox in the settings dialog.

When using the service, you may optionally enable service detection of DPMS events and VDU connectivity events (hot-plugging cables or power-cycling VDUs). Whether to enable events is controlled by the DBUS events checkbox in the settings dialog. The reliability and timeliness of events may vary depending on the GPU model, GPU driver, VDU model, and VDU connector-cable (DP, HDMI, ...). In some cases, the service polling for DPMS or connection status may wake some VDU models. Both ddcutil-service or libddcutil offer options for finer control over which events are detected and how.

Presets¶

A named _Preset_ can be used to save the current VDU settings for later recall. Any number of presets can be created for different lighting conditions or different applications, for example, Night, Day, Overcast, Sunny, Photography, and Video. Each preset can be assigned a name and icon.

The Presets item in main-menu will bring up a Presets dialog for managing and applying presets. The main-menu also includes an item for each existing preset.

Any small SVG or PNG can be assigned as a preset's icon. Monochrome SVG icons that conform to the Plasma color conventions will be automatically inverted if the desktop them is changed from dark to light. If a preset lacks an icon, an icon will be created from the initials of the first and last words of its name. A starter set of icons is included in /usr/share/vdu_controls/icons/.

Any time the current VDUs settings match those of a preset, the preset's name and icon will automatically show in the window-title, tray tooltip, tray icon.

Presets may be set to transition immediately (the default); gradually on schedule (solar elevation); or gradually always (when triggered by schedule, main-menu, or UNIX signal). The speed of transition is determined by how quickly each VDU can respond to adjustment. During a transition, the transition will be abandoned if the controls involved in the transition are altered by any other activity.

Each preset is stored in config directory as: $HOME/.config/vdu_controls/Preset_<preset_name>.conf

Preset files are saved in INI-file format for ease of editing. Each preset file contains a section for each connected VDU, for example:

[preset]
icon = /usr/share/icons/breeze/status/16/cloudstatus.svg
solar-elevation = eastern-sky 40
transition-type = scheduled
transition-step-interval-seconds = 5
[HP_ZR24w_CNT008]
brightness = 50
osd-language = 02
[LG_HDR_4K_89765]
brightness = 13
audio-speaker-volume = 16

When creating a preset file, you may select which controls to save for each VDU. For example, you might create a preset that includes the brightness, but not the contrast or audio-volume. Keeping the included controls to a minimum speeds up the transition and reduces the chances of the VDU failing to keep up with the associated stream of DDC commands.

While using the GUI to create or edit a preset, activation of scheduled presets and adjustments due to light-metering are blocked until editing is complete.

Presets - VDU initialization-presets¶

For a VDU named abc with a serial number xyz, if a preset named abx xyz exists, that preset will be restored at startup or when ever the VDU is subsequently detected.

This feature is designed to restore settings that cannot be saved in the VDU’s NVRAM or for VDUs where the NVRAM capacity has been exhausted or is faulty.

Presets - solar elevation triggers¶

A preset may be set to automatically trigger when the sun rises to a specified elevation. The idea is to allow a preset to trigger relative to dawn or dusk, or when the sun rises above some surrounding terrain (the time of which will vary as the seasons change).

If a preset has an elevation, the preset will be triggered each day at a time calculated according to the latitude and longitude specified by in the vdu-controls-globals location option. By choosing an appropriate solar-elevation a preset may be confined to specific times of the year. For example, a preset with a positive solar elevation will not trigger at mid-winter in the Arctic circle (because the sun never gets that high). Any preset may be manually invoked regardless of its specified solar elevations.

To assign a trigger, use the Preset Dialog to set a preset's solar-elevation. A solar elevation may range from -19 degrees in the eastern sky (morning/ascending) to -19 degrees in the western sky (afternoon/descending), with a maximum nearing 90 degrees at midday.

On any given day, the Preset Dialog may be used to temporarily override any trigger, in which case the trigger is suspended until the following day. For example, a user might choose to disable a trigger intended for the brightest part of the day if the day is particularly dull.

At startup vdu_controls will restore the most recent preset that would have been triggered for this day (if any). For example, say a user has vdu_controls set to run at login, and they've also set a preset to trigger at dawn, but they don't log in until just after dawn, the overdue dawn preset will be triggered at login.

Presets - time-of-day triggers¶

A preset may be set to trigger at a fixed time each day. This is an alternative to the elevation trigger. It's not possible for a single preset to have both kinds of trigger.

As with the elevation trigger, the Preset Dialog may be used to temporarily override any trigger, in which case the trigger is suspended until the following day. Similarly, at startup, the most recent preset that would have been triggered for this day will be restored.

Presets - Smooth Transitions¶

__To minimize writes to VDU NVRAM, smooth-transitions have been deprecated and are disabled by default. To re-enable smooth transitions, uncheck the protect-nvram option in _Settings_.__

A preset may be set to Smoothly Transition, in which case changes to controls continuous-value slider controls such as brightness and contrast will be stepped by one until the final values are reached. Any non-continuous values will be set after all continuous values have reached their final values, for example, if input-source is included in a preset, it will be restored at the end.

The Preset Dialog includes a combo-box for defining when to apply transitions to a preset:

Normally a transition single-steps the controls as quickly as possible. In practice, this means each step takes one or more seconds and increases linearly depending on the number of VDUs and number of controls being altered. The Presets Dialog includes a Transition Step seconds control that can be used to increase the step interval and extend a transition over a longer period of time.

If any transitioning controls change independently of the transition, the transition will cease. In that manner, a transition can be abandoned by dragging a slider or choosing a different preset.

Presets - supplementary weather requirements¶

A solar elevation trigger can have a weather requirement which will be checked against the weather reported by https://wttr.in.

By default, there are three possible weather requirements: good, bad, and all weather. Each requirement is defined by a file containing a list of WWO (https://www.worldweatheronline.com) weather codes, one per line. The three default requirements are contained in the files $HOME/.config/vdu_controls/{good,bad,all}.weather. Additional weather requirements can be created by using a text editor to create further files. The all.weather file exists primarily as a convenient resource that lists all possible codes.

Because reported current weather conditions may be inaccurate or out of date, it's best to use weather requirements as a coarse measure. Going beyond good and bad may not be very practical. What's possible might depend on your local weather conditions.

To ensure wttr.in supplies the weather for your location, please ensure that Settings Location includes a place-name suffix. The Settings Location Detect button has been enhanced to fill out a place-name for you. Should wttr.in not recognize a place-name, the place-name can be manually edited to something more suitable. The nearest big city or an airport-code will do, for example: LHR, LAX, JFK. You can use a web browser to test a place-name, for example: https://wttr.in/JFK

When weather requirements are in use, vdu_controls will check that the coordinates in Settings Location are a reasonable match for those returned from wttr.in, a warning will be issued if they are more than 200 km (124 miles) apart.

If the place-name is left blank, the wttr.in server will try to guess your location from your external IP address. The guess may not be accurate and may vary over time.

Presets - remote control¶

UNIX/Linux signals may be used to cause vdu_controls to restore a preset or to initiate a refresh of the application from the connected monitors. Signals in the range 40 to 55 correspond to first to last presets (if any are defined). Additionally, SIGHUP can be used to initiate "Refresh settings from monitors". For example:

ps axwww | grep '[/]usr/bin/vdu_controls'

kill -40 $(ps axwww | grep '[/]usr/bin/vdu_controls' | awk '{print $1}')
kill -41 $(ps axwww | grep '[/]usr/bin/vdu_controls' | awk '{print $1}')

kill -HUP $(ps axwww | grep '[/]usr/bin/vdu_controls' | awk '{print $1}')

Any other signals will be handled normally (in many cases they will result in process termination).

Ambient Light Levels and Light/Lux Metering¶

The default UI includes an ambient-light slider which will simultaneously adjust all VDUs according to custom VDU profiles. As well as manual adjustment, the slider-value can adjust semi-automatically based on geolocation and local-datetime, or fully-automatically by hardware light-metering.

The Light-Metering dialog provides options for setting up light-metering, adjustment intervals, and per-VDU lux/brightness profiles. The metering dialog additionally provides a rolling display of current metered light level and VDU brightness levels.

Semi-automatic ambient-light level adjustment periodically adjusts the light-level in proportion to the estimated sunlight for your geolocation. Set the current light level by adjusting the ambient-light-level slider. Starting from your chosen level, the application will adjust the light-level following a trajectory based on the estimated sunlight. If conditions change, adjust the slider to alter the trajectory. The trajectory is plotted in the Light-Metering dialog, along with the estimate of outdoor lux (Eo) and the Daylight-Factor (DF) - the ratio of indoor to outdoor lux.

Fully-automatic ambient-light level adjustment requires setting up a hardware lux metering device. A metering device may be a serial-device, a UNIX FIFO (named-pipe), or an executable (script or program):

Possible hardware devices include:

Further information on various lux metering options, as well as instructions for constructing and programming an Arduino with a GY-30/BH1750, can be found at:

Example scripts for mapping a webcam's average-brightness to approximate lux values are included in /usr/share/vdu_controls/sample-scripts/, or they can also be downloaded from the following location:

The examples include vlux_meter.py, a beta-release Qt-GUI python-script that meters from a webcam and writes to a FIFO ($HOME/.cache/vlux_fifo). Controls are included for mapping image-brightness to lux mappings, and for defining a crop from which to sample brightness values. The script optionally runs in the system-tray.

The examples may require customizing for your own webcam and lighting conditions.

If ambient light level controls are not required, the Settings Dialog includes an option to disable and hide them.

Lux Metering and brightness transitions¶

Due to VDU hardware and DDC protocol limitations, gradual transitions from one brightness level to another are likely to be noticeable and potentially annoying. As well as being annoying, excessive stepping may eat into VDU NVRAM lifespan.

The auto-brightness adjustment feature includes several measures to reduce the number of changes passed to the VDU:

When ambient light conditions are fluctuating, for example, due to passing clouds, automatic adjust can be manually suspended. The main-panel, main-menu, and light-metering dialog each contain controls for toggling Auto/Manual. Additionally, moving the manual lux-slider turns off automatic adjustment.

The Light-metering dialog includes an option to enable auto-brightness interpolation. This option will enable the calculation of values between steps in the profiles. To avoid small fluctuating changes, interpolation won't result in brightness changes less than 10%. During interpolation, if a lux value is found to be close to any attached-preset, the preset values will be preferred over interpolated ones.

Light/Lux Metering and Presets¶

The Light-Metering Dialog includes the ability to set a Preset to trigger at a lux value. This feature is accessed by hovering under the bottom axis of the Lux Profile Chart.

When a preset is attached to a lux value, the preset's brightness values become fixed points on the Lux Profile Chart. When the specified metered lux value is achieved, the stepping process will restore the preset's brightness values and then trigger the full restoration of the preset. This ordering of events reduces the likelihood of metered-stepping and preset-restoration from clashing.

A preset that does not include a VDU's brightness may be attached to a lux point to restore one or more non-brightness controls. For example, on reaching a particular lux level, an attached preset might restore a contrast setting.

If a preset is attached to a lux value and then detached, the preset's profile points will be converted to normal (editable) profile points. Attach/detach is a quick way to copy VDU brightness values from presets if you don't want to permanently attach them.

If you use light-metered auto-brightness and preset-scheduling together, their combined effects may conflict. For example, a scheduled preset may set a reduced brightness, but soon after, light-metering might increase it. If you wish to use the two together, design your lux/brightness profile steps to match the brightness levels of specific presets - for example, a full-sun preset and the matching step in a lux/brightness Profile might both be assigned the same brightness level.

Lux Metering Internal Parameters¶

The following internal constants can be altered by manually editing ~/.config/vdu_controls/AutoLux.conf. They guide the various metering and auto-adjustment heuristics:

[lux-meter]
# How many times per minute to sample from the Lux meter (for auto-adjustment)
samples-per-minute=3
# How many samples to include in the smoothing process
smoother-n=5
# How heavily should past values smooth the present value (smaller = more smoothing)
# See: https://en.wikipedia.org/wiki/Low-pass_filter#Simple_infinite_impulse_response_filter
smoother-alpha=0.5
# If an interpolated value yields a change in brightness, how big should the change
# be to trigger an actual VDU change in brightness? Also determines how close
# an interpolated value needs to be to an attached preset's brightness in order
# to prefer triggering the preset over applying the interpolated value.
interpolation-sensitivity-percent=10
# Jump brightness in one step up to this maximum, after which transition in steps.
max-brightness-jump=100

Improving Response Time: Dynamic Optimization and Sleep Multipliers¶

If you are using ddcutil version 2.0 or greater, vdu_controls will default to using the ddcutil dynamic sleep optimizer. The optimizer automatically tunes and caches VDU specific timings when ever ddcutil is run. Any reliability-issues or errors may be automatically resolved as the optimizer refines its cached timings. Should problems persist, the optimizer can be disabled by adding --disable-dynamic-sleep to the ddcutil extra arguments in the Settings Dialog (either globally on the vdu_controls tab or selectively under each VDU's tab). If dynamic sleep is disabled, multipliers can then be manually assigned. The optimizer's heuristics continue to be refined, it may be that some issues may be resolved by moving to a more recent version of libddcutil/ddcutil.

For versions of ddcutil prior to 2.0, you can manually set the vdu_control sleep-multiplier passed to ddcutil. A sleep multiplier less than one will speed up the i2c protocol interactions at the risk of increased protocol errors. The default sleep multiplier of 1.0 has to be quite conservative, many VDUs can cope with smaller multipliers. A bit of experimentation with multiplier values may greatly speed up responsiveness. In a multi-VDU setup, individual sleep multipliers can be configured.

Improving Response Time and Reliability: Connections and Controls¶

DDC/I2C is not a totally reliable form of communication. VDUs may vary in their responsiveness and compliance. GPUs, GPU drivers, and types of connection may affect the reliability. Both ddcutil and vdu_controls attempt to manage the reliability by using repetition and by adjusting timings.

If you have the choice, a DisplayPort to DisplayPort connection may be more reliable than DVI or HDMI.

Reducing the number of enabled controls can speed up initialization, decrease the refresh time, and reduce the time taken to restore presets.

There's plenty of useful info for getting the best out of ddcutil at https://www.ddcutil.com/.

Laptops¶

A laptop's builtin-panel normally doesn't implement DDC and cannot be controlled by ddcutil or ddcutil-service. Laptop panel brightness is controlled by a variety of methods that vary by vendor and hardware. If you have a laptop where such adjustments can be scripted, you can use the --ddcutil-emulator option and provide vdu_controls with a ddcutil-like script for getting and setting the panel brightness; then vdu_controls will treat the laptop panel just like any other VDU. A template script is provided in the sample-scripts.

Cross-platform differences¶

Wayland doesn't allow an application to precisely position its windows. When the smart-window option is enabled and the desktop platform is Wayland, the application switches its platform to XWayland (X11 xcb).

The UI attempts to step around minor differences between KDE, GNOME, and the rest, the UI on each may not be exactly the same.

The scaling and appearance of Qt6 differs from Qt5, its more chunky and rounded. If you have Qt5 installed and prefer it, you can uncheck prefer-qt6 in settings.

Other concerns¶

The power-supplies in some older VDUs may buzz/squeel audibly when the brightness is turned way down. This may not be a major issue because, in normal surroundings, older VDUs are often not usable below about 85-90% brightness.

Going beyond the standard DDC features by attempting to experiment with hidden or undocumented features or values has the potential to make irreversible changes.

Some controls change the number of connected devices (for example, some VDUs support a power-off command). If such controls are used, vdu_controls will detect the change and will reconfigure the controls for the new situation (for example, DDC VDU 2 may now be DDC VDU 1). If you change settings independently of vdu_controls, for example, by using a VDU's physical controls, the vdu_controls UI includes a refresh button to force it to assess the new configuration.

Some VDU settings may disable or enable other settings in the VDU. For example, setting a VDU to a specific picture-profile might result in the contrast-control being disabled, but vdu_controls will not be aware of the restriction resulting in its contrast-control erring or appearing to do nothing.

If your VDUs support picture-modes, altering any controls in vdu_controls will most likely result in the picture-mode being customized. For example, say you have selected the VDU's Vivid picture-mode, if you use vdu_controls to change the brightness, it's likely that this will now become the brightness for Vivid until the VDU is reset to its defaults. To avoid confusion, it may be advisable to stick to one picture-mode for use with vdu_controls, preserving the others unaltered.