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

Presets¶

A custom 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 presets 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 a shortcut for applying each existing presets.

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 its initials (of its first and last words). 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.

Presets - solar elevation triggers¶

A preset may be set to automatically trigger when the sun rises to a specified elevation. The idea being 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 actually log in until just after dawn, the overdue dawn preset will be triggered at login.

Presets - Smooth Transitions¶

In order to minimize writes to VDU NVRAM, the smooth transtion of presets is deprecated and is now normally disabled. Transitions can be renabled by disabling protect-nvram in _Settings_.

A preset may be set to Transition Smoothly, 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 you 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 recognise 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 you location from your external IP address. The guess may not be accurate and may vary over time.

Presets - remote control¶

Scripts may use UNIX/Linux signals may be used to instruct a running vdu_controls to invoke a preset or to initiate "Refresh settings from 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 per-VDU lux/brightness profiles. As well as indicating the ambient light level manually via the slider, vdu_controls can be configured to periodically read from a hardware lux metering device and adjust brightness automatically. The Lux-Dialog provides controls for setting up light metering and VDU lux/brightness profiles. If ambient light level controls are not required, the Settings Dialog includes an option to disable and hide them.

As well as the manual-slider, 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 customising for your own webcam and lighting conditions.

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 anoying 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. In order 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 in proximity 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 tied to a lux value, the preset's VDU 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 utilise 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 optimiser. The optimiser automatically tunes and caches VDU specific timings when ever ddcutil is run. Any reliability-issues or errors may be automatically resolved as the optimiser refines it's cached timings. Should problems persist, the optimiser 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 optimiser'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 (see previous section).

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

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

The ddcutil-service has some ability to signal hot-plug events, such as connecting a new VDU or powering one down. Not all GPU-drivers support an efficient means of event detection, as a result there may be a delay of many seconds before ddcutil-service passes these events to vdu_controls.

Builtin laptop displays normally don't implement DDC and those displays are not supported, but a laptop's externally connected VDUs are likely to be controllable.