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.

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 fBSimple Non-Continuous values. Normally SMC 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 options 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. The output will go to standard-error or, if running from dbus-daemon, to the journal. 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 libddutil's ddca_init() function at startup to enable logging from within the library. It's only available for libddutil 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 libddutil ddca_init() function at startup to enable/disable various options with the library. It's only available for libddutil 2.1.0+.

The libddcutil library also supports its own extensive set of init options, any arguments following -- will be passed as to libddutil 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 displays's settings by VCP code, for example, bightness 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. 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 (hotplug), 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 services's ConnectedDisplaysChanged 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 options 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⟩.

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

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 standards compliant. In some cases, non-compliance can vary to the extent that only a service client can deal with it, and often only by by requiring additional user supplied metadata For example, the vdu_controls client allows the user to edit/override the service supplied capabilities-metadata.

Simple Non Continuous values, such as the VDU input-source, are supposed to be 8 bits only and are masked to remove the high-byte. SNC masking is performed because some VDUs don't clear the SNC high-byte. In such cases, the full 16 bit SNC value will fail to match that declared in the capabilities-metadata. However, there are other VDUs that disregard the 8 bit restriction and set the SNC high-byte to a significant value. The service defaults to standard-compliance and clears the high-byte. The GetVcp and GetMultipleVcp methods support the RETURN_RAW_VALUES flag which forces the return of the original 16 bit values. The client may then be able disambiguate each case by seeing if the 16 bit value matches that declared in the capabilities-metadata, or by consulting additional user supplied metadata. Note that the SetVcp counterpart always accepts full 16 bit values and passes them unaltered to the VDU.

The service may fail to determine working options for the ConnectedDisplaysChanged signal for some mixes of VPUs and GPUs (some hardware/drivers misreport their capabilities). If signals are not being raised, try manually adding --prefer-polling option, this option is not the most responsive, but it is the one most 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. Different 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/.

The service wraps libddcutil that in some cases 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

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

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

ddcutil-service MH