search

digitaltrails / vdu_controls

VDU controls - a control panel for monitor brightness/contrast/...
GNU General Public License v3.0
103 stars 4 forks source link
bh1750 ddc ddcutil gui gy-30 gy-302 linux mccs python qt5

readme

vdu_controls - a DDC control panel for monitors

A control panel for external monitors (Visual Display Units).

KDE 6 introduced energy saving brighness dimming after 5 minutes of idle time. This may interfere with changes made via vdu_controls, including scheduled-presets and ambient-light-control. The relevant KDE 6 options can be found under System Settings -> System -> Energy Saving.

vdu_controls version 2.0 adds manual ambient-light-level input. This allows all connected VDU's to be simultatiniously adjusted by moving one slider. This is an alternative to fully automatic control via hardware lux-metering. When the ambient-light-level is changed, each VDU us adjusted according to its own custom light-level/brighness profile defined under Settings->Light-Metering. This new option is enabled by default, but can be disabled by unchecking Settings->Lux options enabled.

Custom

The second major change in 2.0 is actually far more wide-reaching, but much less visibile. The internal DDC/VDU interface has been rewritten to optionally use the D-Bus ddcutil-service instead of the ddcutil command. The new ddcutil-service is a daemon I've written to interface with libddcutil, it's faster and more reponsive than the older command-based implementation. Should the ddcutil-service be unavailable, the DDC/VDU interface reverts to using the ddcutil command. Should you encounter any issues with using the service, Settings->D-Bus client enabled can be used to disable it and force the use of the command.

If you'd like to try the ddcutil-service, builds are available for OpenSUSE Tumbleweed and the Arch AUR:

OpenSUSE Tumbleweed RPM:

https://software.opensuse.org/package/ddcutil-service

AUR (Arch Linux User Repository):

https://aur.archlinux.org/packages/ddcutil-service

Otherwise it's written in C, so you'd need to build and install it. It's one C file. It will build against any libddcutil from 1.4 onward. It doesn't need to be installed as root, it can also be started manually from the command line or installed as a single user D-Bus daemon. For install/build details, see:

https://github.com/digitaltrails/ddcutil-service

The service can be installed for on demand access via the D-BUS daemon. It can also run manually from the command line. Once the service is running, any new instance of vdu_controls should automatically find and connect to the service. When using the service, the bottom line of vdu_controls About Dialog will list ddcutil-interface as 1.0.0 (QtDBus client). Use of the service can be manually toggled via vdu_controls->Settins->dbus client enabled.

The service may also be accessed from generic D-Bus clients such as d-feet dbus-send and busctl.

Description

vdu_controls is a virtual control panel for externally connected VDUs. The application detects DVI, DP, HDMI, or USB connected VDUs. It provides controls for settings such as brightness and contrast.

The application interacts with VDUs via the VESA Display Data Channel (DDC) Virtual Control Panel (VCP) commands set. DDC VCP interactions are mediated by the ddcutil command line utility. Ddcutil provides a robust interface that is tolerant of the vagaries of the many OEM DDC implementations.

By default vdu_controls offers a subset of controls including brightness, contrast and audio controls. Additional controls can be enabled via the Settings dialog.

vdu_controls may optionally run as an entry in the system tray of KDE, Deepin, GNOME, and Xfce (and possibly others). The UI attempts to adapt to the quirks of the different tray implementations.

Named Preset configurations can be saved for later recall. For example, a user could create presets for night, day, photography, movies, and so forth. Presets may be automatically triggered according to solar elevation, and can be further constrained by local weather conditions (as reported by https://wttr.in). Presets can be set to transition immediately or gradually. Presets may also be activated by UNIX signals.

From any application window, use F1 to access help, and F10 to access the context-menu. The context menu is also available via the right-mouse button in the main-window, the hamburger-menu item on the bottom right of the main window, and the right-mouse button on the system-tray icon. The context-menu provides ALT-key shortcuts for all menu items (subject to sufficient letters being available to support all user defined Presets).

Version 1.10 introduces options for using lux readings from a hardware lux meter (or in some cases a webcam). When lux metering is enabled, vdu_controls can vary brightness according to customisable lux/VDU-brightness profiles. See Lux Metering for more details.

The UI's look-and-feel dynamically adjusts to the desktop theme and desktop environment: light-theme, dark-theme, KDE, Deepin, GNOME, and others.

Default Custom Custom Custom Custom Custom

Getting Started

The long term affects of repeatably rewriting a VDUs setting are not well understood, but some concerns have been expressed. See below for further details.

To get started with vdu_controls, you only need to download the vdu_controls.py python script and check that the dependencies described below are in place. Alternatively, should you wish to install vdu_controls for all users, RPMs are available for OpenSUSE, Fedora, and there is an archlinux AUR package which also works in Manjaro. See the Install section below.

Development is trunk-based. It is my intention that the trunk should always be usable as a daily-driver. That being said, a download of trunk is likely to be less stable than downloading one of the formal releases or installing one of the packages that are available in various distros.

Dependencies

All the following runtime dependencies are likely to be pre-packaged on any modern Linux distribution (vdu_controls was originally developed on OpenSUSE Tumbleweed).

It's best to confirm that ddcutil is functioning before using vdu_controls:

As of ddcutil 1.4, installing a pre-packaged ddcutil will most likely set the correct udev rules to grant users access to the required devices. If you are using an earlier ddcutil, it may be necessary to follow all the steps detailed in the links above.

Installing

As previously stated, the vdu_vontrols.py script is only file required beyond the prerequisites. There are also OpenSUSE and Fedora RPMs available at: https://software.opensuse.org/package/vdu_controls and an archlinux (manjaro compatible) AUR package at: https://aur.archlinux.org/packages/vdu_controls

That makes three options for "installation":

  1. The script can be run without installation by using a python interpreter, for example: 
    % python3 vdu_controls.py
  2. The script can be self installed as desktop application in the current user's desktop menu as Applications->Settings->VDU Controls by running: 
    % python3 vdu_controls.py --install

    Depending on which desktop you're running menu changes may require logout before they become visible.

  3. A system-wide installation using a distribution's packaging system which will install all of:

    /usr/bin/vdu_controls
/usr/share/applications/vdu_controls.desktop
/usr/share/licenses/vdu_controls/LICENSE.md
/usr/share/vdu_controls/icons/*
/usr/share/vdu_controls/sample-scripts/*
/usr/share/vdu_controls/translations/*
/usr/share/man/man1/vdu_controls.1.gz

Please note the first two options only install vdu-controls for the current user. The script and desktop-file installed for a single user could be modified and copied into /usr or /usr/local hierarchies should you wish to do so. If using the first two options, you might want to follow up by manually downloading some of the other items such as the starter set of icons for use when creating Presets.

Executing the program

Help

Detailed help can be accessed by using the right mouse-button to bring up a context-menu. Access to the context-menu is available in the application-window and in the system-tray icon.

Both brief help and detailed help can also be accessed via the command line:

% python3 vdu_controls.py --help
% python3 vdu_controls.py --detailed-help
% python3 vdu_controls.py --detailed-help | pandoc --from markdown --to html > vdu_controls_help.html
# or if installed as an executable:
% vdu_controls --help
% vdu_controls --detailed-help
% vdu_controls --detailed-help | pandoc --from markdown --to html > vdu_controls_help.html

Whether run from the desktop application-menu or run from the command line, vdu-controls behaviour can be altered in a number of ways:

See the context-menu or the man page for details.

VDU controls and optimisations can be specified in the global or VDU-specific config-files.

Does adjusting a VDU affect its lifespan or health?

There has been speculation that repeatably altering VDU settings might affect VDU lifespan. Possible reasons include the consumption of NVRAM write cycles, stressing the VDU power-supply, or increasing the LED panel burn-in.

That said, vdu_controls does include a number of features that can be used to reduce the overall frequency of adjustments, see Limitations in the man page for further details.

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.

Bugs and Suggestions

If you encounter a bug or issue, or wish to make a suggestion, you're most welcome to raise it on the issues page.

Development

I've set up the vdu_controls source as a typical Python development, but there is only one real source file, vdu_controls.py, so the file hierarchy is rather over the top. A standard python distributable can be built by issuing the following commands at the top of the project hierarchy:

% python3 -m pip install build
% python3 -m build
...
% ls -1 dist/
total 268
vdu_controls_digitaltrails-1.0.0-py3-none-any.whl
vdu_controls-digitaltrails-1.0.0.tar.gz

The source includes configuration files for the Sphinx Python Documentation Generator. The following commands will extract documentation from vdu_controls.py:

% cd docs
% make man
% make html

I prefer Pandoc's HTML generation. There is a util script that generates the Sphinx outputs and then pandoc for the html:

% ./util/make-man

My IDE for this project is PyCharm Community Edition.

Coverage testing is assisted by Coverage.py and Vulture. Type checking is assisted by Mypy.

My development Linux desktop is OpenSUSE Tumbleweed. The python3 interpreter and python3 libraries are from the standard Tumbleweed repositories.

Acknowledgements

Author

Michael Hamilton

Version History

License

This project is licensed under the GNU General Public License Version 3 - see the LICENSE.md file for details

vdu_controls Copyright (C) 2021 Michael Hamilton

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.