1. Manuals
  2. Tumbleweed
  3. ddcutil-service
  4. ddcutil-service(1)

Scroll to navigation

ddcutil-service(1) General Commands Manual ddcutil-service(1)

NAME

ddcutil-service - D-Bus service for libddcutil VESA DDC Monitor Virtual Control Panel

SYNOPSIS

ddcutil-service --help | --version | --introspect
ddcutil-service [ --emit-connectivity-signals ] | [ --prefer-polling ] | [ --prefer-drm ] | [ --polling-interval seconds ] | [ --return-raw-values ] | [ --lock ] | [ --log-info ] [ --ddca-syslog-level N ] | [ --ddca-init-options M ] [ -- libddcutil ddc_init options... ]

DESCRIPTION

ddcutil-service is D-Bus service wrapper for libddcutil which implements the VESA DDC Monitor Control Command Set. Most things that can be controlled using a monitor's on-screen display can be controlled by this service.

The service is registered as a session-service with the dbus-daemon. The daemon starts the service on demand. If the service terminates for any reason, the daemon will be restart it when it is next accessed. Client connections with the service are stateless, each request is handled atomically.

When using this service, avoid excessively writing VCP values because each VDU's NVRAM likely has a write-cycle limit/lifespan. The suggested guideline is to limit updates to rates comparable to those observed when using the VDU's onboard controls. Avoid coding that might rapidly or infinitely loop, including when recovering from errors and bugs.

Non-standard manufacturer specific features should only be experimented with caution, some may have irreversible consequences, including bricking the hardware.

OPTIONS

Depending on the version of libddcutil in use, not all options may be available.

Outputs options-help and exits.

Outputs the service interface version and the libddcutil version and exits.

Outputs the XML introspection text for the service and exits.

Enable the ConnectedDisplaysChanged signal sent to clients and also enable any monitoring for changes. Once the service is running, this setting can be toggled by altering the ServiceEmitConnectivitySignals property. See SERVICE SIGNALS.

Set polling to be the preferred method for detecting display connectivity changes for the ConnectedDisplaysChanged signal. This is the default.

Use libddcutil DRM-lookups as the preferred method for detecting display connectivity changes for the ConnectedDisplaysChanged signal. This option should detect changes sooner with less overheads, but may fail to detect changes for some combinations or drivers and hardware.

If polling is enabled, this option defines how often to check for display connectivity changes. Default 30 seconds, minimum 10 seconds, zero to disable polling.

If polling is enabled, this option defines the minimum interval between events within a cascade of events. For example, a cascade of events will occur when a session is locked and all displays are put into DPMS sleep. Default 0.5 seconds, minimum 0.1 seconds.

Return high-byte and low-byte for all values, including for Simple Non-Continuous values. Normally SMC (single-byte) values are masked to remove the high-byte value (see LIMITATIONS for an explanation).

Lock the configuration. Disable the SetSleepMultiplier and Restart methods. Make all properties read-only. This option provides a way to lockdown the service to the configuration passed on the command line. The lock is provided to assist with avoiding conflicts when more than one ddcutil-service client is in use at the same time.

Enabling log-info will produce info and debug level output. When the service is run from dbus-daemon, the diagnostic output will be captured in the journal logs, otherwise it is directed to standard-error. This option can also be toggled after startup by using B-Bus to alter the service's ServiceInfoLogging property (see EXAMPLES below).

The DDCA syslog level numerical value is passed to libddcutil ddca_init() function at startup to enable logging from within the library. It's only available for libddcutil version 2.1.0 and up. Values for N are 0:never, 2:error:, 6:warning, 9:notice, 12:info, 15:verbose, and 18:debug.

The DDCA init option is a numerical value is passed to libddcutil ddca_init() function at startup to enable/disable various options with the library. It's only available for libddcutil 2.1.0+.

The libddcutil library also supports its own extensive set of init options, any arguments following -- will be passed as to libddcutil ddca_init() function at service startup.

SERVICE METHODS

The following is a brief summary of the methods provided by the service. Full API documentation can be found in ddcutil_service(7).

Return a list of monitors detected along with their properties.

Query a display settings by VCP code, for example, brightness is VCP code 0x10.

The method's flags bit-string parameter can be set to 2 (RETURN_RAW_VALUES), see LIMITATIONS for an explanation.

Query multiple VCP codes for a single display.

The method's flags bit-string parameter can be set to 2 (RETURN_RAW_VALUES), see LIMITATIONS for an explanation.

Set a display setting, specified by VCP code, to a new value. If the method succeeds, it will also emit a D-Bus VcpValueChanged signal. Set the method's flags to 4 (NO_VERIFY) to disable libddcutil verification and retry.

As with SetVcp, but also accept a client supplied context string to be returned with the emitted D-Bus VcpValueChanged signal. The client-context may be of use to signal recipients for interpreting the origin of the change.

Query a displays capabilities returning a parsed data-structure describing the features and permitted values.

Query a displays capabilities returning a unparsed capabilities string.

Query the metadata describing a specific VCP code for a specific display.

Get the display specific ddcutil sleep multiplier.

Set a display specific ddcutil sleep multiplier.

Restart the service with specific arguments.

If a method requires a display-argument, either an integer display-number or a base64-encoded EDID can be supplied. Base64-encoded EDIDs are obtained from the Detect method. When passing an EDID, pass -1 for display_number, otherwise both are tied with the display_number having precedence. If a EDID is supplied, a method's flags bit-string parameter can be set to 1 (EDID_PREFIX), this indicates a unique prefix of an EDID has been passed rather than the entire string (this makes using EDIDs from the command line a little easier).

Run ddcutil-service --introspect for details on each method's in/out parameters. For even more information, the d-feet graphical D-Bus debugger provides a very readable way to browse and experiment with the service interface, simply start d-feet, select the Session Bus and search for ddcutil-service.

SERVICE SIGNALS

At startup the service emits the ServiceInitialized D-Bus signal. This signal provides clients with a way to detect a service restart and reinstate any custom service properties or settings.

The service may optionally emit a ConnectedDisplaysChanged D-Bus signal when a display undergoes a connectivity status change due to hot-plug and DPMS events. This feature is optional because the manual experimentation required to configure it is unnecessary for display configurations that remain static.

Change-detection can be enabled by passing --emit-connectivity-signals on the command line, or by setting the ServiceEmitConnectivitySignals property.

To permanently enable change-detection, the --emit-connectivity-signals option can be appended to the Exec line of the system or user D-Bus com.ddcutil.DdcutilService.service file (see FILES).

Changes are detected in one of two ways. The service defaults to periodic polling by issuing libddcutil DDCA detects. Polling is likely to work for a wide variety of drivers and hardware. Polling for changes will be subject to delays because the polling interval defaults to 30 seconds (with a minimum of 10 seconds). Alternatively the service can use libddcutil DRM access to provide a more efficient method for change detection, this requires ddcutil/libddcutil version 2.1.0+, a GPU configured for DRM, and the --enable-watch-displays to be added to [libddcutil] options in $HOME/.config/ddcutil/ddcutilrc.

Not all displays, GPUs, GPU-drivers, or cabling, provide the necessary support for detecting connection status changes. Results may vary depending on the mix of desktop components, such as KDE, Gnome, X11, and Wayland. DisplayPort behaves differently to DVI and HDMI when a display is turned off but remains connected. Some drivers that support DRM don't properly support the necessary change detection features.

The service will emit a VcpValueChanged D-Bus signal whenever a SetVcp or SetVcpWithContext method call succeeds in changing a VCP's value. Only changes made by service methods are detected, changes made externally to the service are not detected and will not trigger this signal.

SERVICE PROPERTIES

Query the fieldnames returned from the Detect method. Lists the names of the fields in the order they are found in each struct returned from Detect.

Query the list of status values returned by libddcutil along with their text names.

List the event-types sent by the ConnectedDisplaysChanged signal along with their text names. Events are included for display connection/disconnection (hot-plug), DPMS-sleep, and DPMS-wake. If the list is empty, the GPU, GPU-driver, or libddcutil version doesn't support display event detection.

Enable/disable libddcutil dynamic-sleep adjustment of DDC timings.

Read/write the libddcutil output level.

Obsolete as of version 1.0.5+, replaced by the SetVcp method's NO_VERIFY flag.

Query the libddcutil version string.

Set this property to true or false to enable or disable the ConnectedDisplaysChanged dbus-signal and associated monitoring.

Enable/disable the service's diagnostic level output to include info and debug messages. Note that libddcutil also has a logging mechanism (see libddcutil ddc_init options).

Query the service interface version.

List the available flag option values that can be passed to service methods. Not all options are applicable to all methods.

Returns whether the --lock command line argument has been used.

Query or set the display change detection poll-interval (minimum 10 seconds, zero to disable polling).

Query or set the display change detection poll-cascade-interval (minimum 0.1 seconds). When dealing with a cascade of events, for example, when a desktop-session is locked and sets all VDUs to DPMS sleep, polling occurs more frequently until the cascade is cleared.

Properties can be queried and set using utilities such as busctl, d-bus-send, and d-feet, see EXAMPLES.

SERVICE ERRORS

Errors forwarded from libddcutil

Status codes and error messages from libddcutil are passed back to clients as part of the data returned by each method call.

Exceptions

The service may also issue the following exceptions when attempting to set properties or call methods:

The --lock option has prevented a client from altering a configuration settings. This includes using the SetSleepMultiplier method, Restart method,
or setting any property value.
An attempt was made to set ServicePollInterval to a value outside its accepted range.
An attempt was made to set ServicePollCascadeInterval to a value outside its accepted range.
At startup no /dev/i2c devices are present and an attempt to verify communications via i2c failed.
At startup it was found that the user/service lacked read/write access to the /dev/i2c devices.

FILES

/usr/share/dbus-1/services/com.ddcutil.DdcutilService.service
If running via the dbus-daemon, this config file is read when the service is requested. Typically the contents would be as follows 



    [D-BUS Service]


    Name=com.ddcutil.DdcutilService


    Exec=/usr/bin/ddcutil-service

Service options, such as --emit-connectivity-signals or --prefer-drm, should be appended to the end of Exec= line.

$HOME/.local/share/dbus-1/services/com.ddcutil.DdcutilService.service
If you do not have root access or wish to set options for a specific user, the dbus-daemon first looks for in $HOME/.local/share before looking in /usr/share.

$HOME/.config/ddcutil/ddcutilrc
When initialised at service startup, libddcutil loads options from its rc file. See https://www.ddcutil.com/config_file/ for details.

/usr/share/ddcutil-service/examples/
The service is packaged with several example scripts, including dbus-send bash-scripts and python3 clients for D-Bus dasbus and QtDBus APIs.

EXECUTION ENVIRONMENT

The service relies on libddcutil which requires read/write access to the /dev/i2c devices. See http://www.ddcutil.com/i2c_permissions for details.

At startup ddcutil-service will attempt to verify that i2c-dev module is loaded and that the permissions for /dev/i2c are set appropriately. If these checks fail, method calls will error until the problem is resolved.

NVIDIA PROPRIETARY DRIVER

Some Nvidia cards using the proprietary Nvidia driver require special settings to properly enable I2C support. See http://www.ddcutil.com/nvidia for details.

VIRTUAL MACHINES

Virtualized video drivers in VMWare and VirtualBox do not provide I2C emulation. It may be possible to forward D-BUS over ssh to side step this issue.

EXAMPLES

The commonly available command line utilities systemd bustctl and dbus-tools dbus-send command can be used to interact with the service.

Summarise the service methods and properties:



    busctl --user introspect com.ddcutil.DdcutilService /com/ddcutil/DdcutilObject


    dbus-send --session --dest=com.ddcutil.DdcutilService --print-reply \


        /com/ddcutil/DdcutilObject \


        org.freedesktop.DBus.Introspectable.Introspect

Detect the connected displays:



    busctl --user call com.ddcutil.DdcutilService /com/ddcutil/DdcutilObject \


        com.ddcutil.DdcutilInterface Detect u 0


    dbus-send --dest=com.ddcutil.DdcutilService --print-reply --type=method_call \


        /com/ddcutil/DdcutilObject com.ddcutil.DdcutilInterface.Detect uint32:0

Get the brightness of display-1 (VCP 0x10):



    busctl --user call com.ddcutil.DdcutilService /com/ddcutil/DdcutilObject \


        com.ddcutil.DdcutilInterface GetVcp isyu 1 "" 0x10 0


    dbus-send --dest=com.ddcutil.DdcutilService --print-reply --type=method_call \


        /com/ddcutil/DdcutilObject com.ddcutil.DdcutilInterface.GetVcp \


        int32:1 string: byte:0x10 uint32:0

Set brightness of display-1 (VCP 0x10):



    busctl --user call com.ddcutil.DdcutilService /com/ddcutil/DdcutilObject \


        com.ddcutil.DdcutilInterface SetVcp isyqu 1 "" 16 50 0


    dbus-send --session --dest=com.ddcutil.DdcutilService --print-reply --type=method_call \


        /com/ddcutil/DdcutilObject com.ddcutil.DdcutilInterface.SetVcp \


        int32:1 string:"" byte:0x10 uint16:10  uint32:0

Query or set the service logging level property:



   busctl --user get-property com.ddcutil.DdcutilService /com/ddcutil/DdcutilObject \


       com.ddcutil.DdcutilInterface ServiceInfoLogging


   busctl --user set-property com.ddcutil.DdcutilService /com/ddcutil/DdcutilObject \


       com.ddcutil.DdcutilInterface ServiceInfoLogging b true


   dbus-send --session --dest=com.ddcutil.DdcutilService --print-reply \


        --type=method_call /com/ddcutil/DdcutilObject \


        org.freedesktop.DBus.Properties.Get \


        string:com.ddcutil.DdcutilInterface \


        string:ServiceInfoLogging


   dbus-send --dest=com.ddcutil.DdcutilService --print-reply \


        --type=method_call /com/ddcutil/DdcutilObject \


        org.freedesktop.DBus.Properties.Set \


        string:com.ddcutil.DdcutilInterface \


        string:ServiceInfoLogging variant:boolean:true

LIMITATIONS

Some VDUs are not fully DDC compliant. In some cases issues raised by non-compliance can only be resolved at the client-level, often by requiring the user to provide additional metadata. For example, the vdu_controls client allows the user to edit/override the service supplied capabilities-metadata.

Some VDUs differ in how they treat the data-type for Simple-Non-Continuous values. SNC values are used for features such as the Input-Source or OSD-language. According to the DDC specification, SNC values should be 8-bit values passed in the low-byte of a 16-bit value.

Some VDUs don't zero the SNC high-byte. This may cause a mismatch with the values specified in the VDU metadata. The service handles this by defaulting to masking off the high-byte of SNC values.

Some VDUs return SNC values where both the low and high byte are significant. The GetVcp and GetMultipleVcp methods support the RETURN_RAW_VALUES flag to force the return of unmasked 16-bit values. This allows clients to apply heuristics or use additional metadata to handle such cases. The SetVcp counterpart always accepts full 16-bit values and passes them unaltered to the VDU.

Some mixes of VPUs and GPUs don't consistently update DRM metadata for hot-plug events. If ConnectedDisplaysChanged signals are not being raised, try manually adding --prefer-polling option, to force the service to poll for changes. Polling is less responsive, but it doesn't require DRM, and is likely to always work.

Some GPU drivers and VDUs have buggy implementations of DDC. If you have the choice, a DisplayPort to DisplayPort connection may work more reliably than DVI, HDMI or mixed connectors. In some cases GPU driver editions, such as production, beta, and development, may vary in the state of their DDC support.

Some parameters can only be changed at process startup. The service can be restarted either by killing it with a UNIX signal, or by invoking the service's Restart method.

The service is a relatively thin wrapper around libddcutil, in order to resolve VDU compatibility/compliance issues, the user may need to become familiar with the libddcutil configuration options normally stored in $HOME/.config/ddcutil/ddcutilrc and documented at https://www.ddcutil.com/config_file/.

In some cases libddcutil has been found to perform differently from the ddcutil command. If the service has problems with a VDU, it's worth trying the ddcutil command to see if it differs in result and to include those details in any issue raised.

SEE ALSO

ddcutil-service(7), vdu_controls(1), ddcutil(1), dbus-daemon(1), dbus-send(1), busctl(1)

REPORTING BUGS

Before raising a new issue, please read through LIMITATIONS. Issues can be raised at https://github.com/digitaltrails/ddcutil-service/issues (requires a github login).

AUTHOR

Michael Hamilton

ACKNOWLEDGEMENTS

Thanks go out to Sanford Rockowitz for libddcutil, ddcutil and all the assistance and advice provided during the development of this service.

Thanks also go out to all those who assisted with development and packaging. An up-to-date list of contributors can be found at https://github.com/digitaltrails/vdu_controls#acknowledgements.

COPYRIGHT

Copyright (C) 2023,2024 Michael Hamilton.

ddcutil-service 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; either version 2, or (at your option) any later version.

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, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

ddcutil-service MH