ddcutil − Query and change monitor settings
ddcutil [options] command [command-arguments] [options]
Options can be written either before or after the command and its arguments.
ddcutil is used to query and change monitor settings.
ddcutil communicates with monitors that implement the Monitor Control Command Set (MCCS) using the DDC/CI protocol on an I2C bus. Normally, the video driver for the monitor exposes the I2C bus as devices named /dev/i2c-n. Alternatively, ddcutil can communicate with monitors that use USB to communicate MMCS, provided the monitors meet the USB Monitor Control Class Specification.
The Monitor Control Command Set describes a collection of Virtual Control Panel (VCP) features that a monitor can implement. Each feature is identified using a single byte. For example, feature x10 is the brightness control.
The monitor settings that can be controlled by ddcutil are, generally speaking, those that can be changed using the buttons on a monitor and its on screen display. The specific capabilities vary from monitor to monitor.
A particular use case for ddcutil is as part of color profile management. Monitor calibration is relative to the monitor color settings currently in effect, e.g. red gain. ddcutil allows color related settings to be saved at the time a monitor is calibrated, and then restored when the calibration is applied.
Another common use case is to switch the monitor input source.
This man page describes ddcutil commands and options most important to the typical user. For complete documentation, use the --help option or see the web site http://www/ddcutil.com.
ddcutil does not support laptop monitors, which do not implement DDC/CI.
These are the most used ddcutil commands.
|
detect |
"Report monitors" |
vcpinfo [ feature-code | feature-group ]
Describe VCP feature codes. as defined in the MCCS specification. Use option --verbose to see values for Non-Continuous features.
capabilities
Query the monitor’s capabilities string
getvcp [ feature-code | feature-group ] ...
Report a VCP feature value, or a group of feature values. More than one feature code can be specified. However feature codes and groups cannot be combined.
setvcp feature-code [+|-] new-value ...
Set a VCP feature value. If + or - is specified, it must be surrounded by blanks, and indicates a relative value change of a continuous VCP feature. Multiple feature/value pairs (with or without [+|1]) can be specified.
These commands
address special situations.
dumpvcp filename
Save color profile related VCP feature values in a file. If no file name is specified, one is generated and the file is saved in $HOME/.local/share/ddcutil,
loadvcp filename
Set VCP feature values from a file. The monitor to which the values will be applied is determined by the monitor identification stored in the file. If the monitor is not attached, nothing happens.
|
scs |
Issue DDC/CI Save Current Settings request. Most monitors do not implement this command. A few require it for values changed by setvcp to take effect. |
chkusbmon
Tests if a hiddev device may be a USB connected monitor, for use in udev rules.
These commands
diagnose issues in the system configuration that affect
ddcutil operation, and that gather information for
remote problem diagnosis.
environment
Probe the ddcutil installation environment.
|
usbenv |
Probe USB aspects of the ddcutil installation environment. |
|||
|
probe |
Explore the capabilities and features of a single monitor. |
interrogate
Collect maximum information for problem diagnosis. Includes the output of ddcutil environment --verbose andfor each detected monitor, the output of ddcutil capabilities --verbose and ddcutil probe --verbose.
feature-code
A feature-code is specified by its 2 character hex feature number, with or without a leading "0x", e.g. 0x10, 10
feature-group
The following
are the most useful feature groups. For a complete list, use
the --help option.
ALL|KNOWN
All feature codes understood by ddcutil
|
COLOR |
Scan color related feature codes |
PROFILE
Subset of color related feature codes that are saved and restored by dumpvcp and loadvcp
|
SCAN |
Scan all possible feature codes 0x00..0xff, except those known the be write-only |
Feature group names can be abbreviated to the first 3 characters. Case is ignored. e.g. "COL", "pro".
new-value
Normally, this is a decimal number in the range 0..255, or a hexadecimal number in the range x00..xff. More generally, this is actually a two byte value, i.e. x00..xffff, and a few features on some monitors use this extended range.
Options for
monitor selection. If none are specified, the default is the
first detected monitor. Options --mfg, --model
and --sn can be specified together.
-d , --dis , --display ,
display-number logical display number (starting from 1)
-b,--bus
bus-number I2C bus number
--hiddev
device number hiddev device number
-u,--usb busnum.devicenum
USB bus and device numbers
-g,--mfg
3 letter manufacturer code
-l,--model
model name
-n,--sn
serial number. (This is the "serial ascii" field from the EDID, not the binary serial number.)
-e,--edid
256 hex character representation of the 128 byte EDID. Needless to say, this is intended for program use.
Feature
selection filters
-U, --show-unsupported
Normally, getvcp does not report unsupported features when querying a feature-group. This option forces output.
--show-table | --no-table
Normally, getvcp does not report Table type features when querying a feature-group. --show-table forces output. --no-table is the default.
--rw, --ro, --wo
Limit getvcp or vcpinfo output to read-write, read-only, or (for vcpinfo) write-only features.
Options that
control the amount and form of output.
-t, --terse, --brief
Show brief detail. For command getvcp, the output is in machine readable form.
-v, --verbose
Show extended detail
Options for
program information.
-h,--help
Show program help.
-V, --version
Show program version.
--settings
Report option settings in effect.
Options for diagnostic output
|
--ddc |
Reports DDC protocol errors. These may reflect I2C bus errors, or deviations by monitors from the MCCS specification. |
[--stats|--vstats] [all|errors|tries|calls|elapsed|time]
Report execution statistics.
I2C bus communication is an inherently unreliable. It is the
responsibility of the program using the bus, i.e.
ddcutil, to manage retries in case of failure. This
option reports retry counts and various performance
statistics. If no argument is specified, or ALL is
specified, then all statistics are output. ELAPSED is a
synonym for TIME. CALLS implies TIME.
--vstats [all|errors|tries|calls|elapsed|time]
Like --stats, but includes per-display statistics.
--syslog[ debug|verbose|info|notice|warn|error|never ]
Write messages of the specified or more urgent severity level to the system log. The default is WARN.
Options that
tune execution
--enable-capabilities-cache,
--disable-capabilities-cache
Enable or disable caching of capabilities strings, improving performance. The default is --enable-capabilities-cache
--enable-displays-cache, --disable-displays-cache
Enable or disable caching of information about detected displays, improving performance. The default is --enable-displays-cache
--sleep-multiplier decimal number
Adjust the length of waits listed in the DDC/CI specification by this number to determine the actual wait time. Well behaved monitors work with sleep-multiplier values less than 1.0, while monitors with poor DDC implementations may require sleep-multiplier values greater than 1.0.
--enable-dynamic-sleep, --disable-dynamic-sleep
Dynamically adjust the sleep-multiplier over multiple ddcutil invocations, improving performance. The default is --enable-dynamic-sleep
--async
If there are several monitors, initial checks are performed in multiple threads, improving performance.
--lazy-sleep
Peform mandated sleeps before the next DDC/CI operation instead of immediately after the DDC/CI operation that specified a delay, marginally improving performance.
Options that
modify behavior
--maxtries (max-read-tries, max-write-read-tries,
max-multi-part-tries)
Adjust the number of retries. A value of "." or "0" leaves the setting for a retry type unchanged.
--verify | --noverify
Verify or do not verify values set by setvcp or loadvcp. --noverify is the default.
--mccs MCCS version
Tailor command input and output to a particular MCCS version, e.g. 2.1
--enable-udf, --disable-udf
Enable or disable support for user supplied feature definitions. The default is --enable-udf
--enable-usb, --disable-usb
Enable or disable support for monitors that implement USB commuincation with the Virtual Control Panel. (These options are available only if ddcutil was built with USB support.) The default is --disable-usb
--ignore-usb-vid-pidvid:pid
Force ddcutil to ignore a particular USB device, specified by its 4 hex digit vendor id and its 4 hex digit product id.
--ignore-hiddev hiddev-device-number
Force ddcutil to ignore a particular USB device, specified by /dev/usb/hiddev device number
--use-file-io | --use-ioctl-io
Cause ddcutil to use the write()/read() interface or the ioctl interface of driver dev-i2c to send and receive I2C packets. By default, ddcutil uses the ioctl interface. Depending on how the Nvidia proprietary driver was built, this can fail, in which case ddcutil switches to using the file io interface.
--force-slave-address
Take control of slave addresses on the I2C bus even they are in use. Has use only for the proprietary Nvidia video driver.
--edid-read-size 128|256
Force ddcutil to read the specified number of bytes when reading the EDID. This option is a work-around for certain driver bugs. The default is 256.
Requires read/write access to /dev/i2c devices. See http://www.ddcutil.com/i2c_permissions
Some Nvidia cards using the proprietary Nvidia driver require special settings to properly enable I2C support. See http://www.ddcutil.com/nvidia.
Virtualized video drivers in VMWare and VirtualBox do not provide I2C emulation. Use of normal video drivers with PCI passthrough is possible.
ddcutil
detect
Identify all attached monitors.
ddcutil getvcp supported
Show all settings that the default monitor supports and that ddcutil understands.
ddctpp getvcp
10 --display 2
Query the luminosity value of the second monitor.
ddcutil
setvcp 10 30 --bus 4
Set the luminosity value for the monitor on bus
/dev/i2c-4.
ddcutil
vcpinfo --verbose
Show detailed information about VCP features that
ddcutil understands.
ddcutil
interrogate > ˜/ddcutil.out
Collect maximum information about monitor capabilities and
the execution environment, and direct the output to a
file.
Returns 0 on success, 1 on failure.
Requesting help is regarded as success.
The project homepage: http://www.ddcutil.com
Sanford
Rockowitz (rockowitz at minsoft dot com)
Copyright 2015−2023 Sanford Rockowitz