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 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 focuses on the 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 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.
- chkusbmon
- Tests if a hiddev device is 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 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 that modify behavior
- --mccs MCCS
version
- Tailor command input and output to a particular MCCS version, e.g.
2.1
- --enable-usb,
--disable-usb
- Enable or disable support for monitors that implement USB commuincation
with the Virtual Control Panel. The default is --disable-usb
- --enable-udf,
--disable-udf
- Enable or disable support for user supplied feature definitions. The
default is --enable-udf
- enable-capabilities-cache,
--disable-capabilities-cache
- Enable or disable caching of capabilities strings, improving performance.
The default is --enable-capabilities-cache
- --force-slave-address
- Take control of slave addresses on the I2C bus even they are in use.
- --verify |
--noverify
- Verify or do not verify values set by setvcp or loadvcp.
--noverify is the default.
- --async
- If there are multiple monitors, initial checks are performed in multiple
threads, improving performance.
- --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.
Options to tune execution:
- --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.
- --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 work better with sleep-multiplier values greater than
1.0.
Options for diagnostic output.
- --stats
[all|errors|tries|calls|elapsed|time]
- Report execution statistics. If no argument is specified, or ALL is
specified, then all statistics are output. elapsed is a synonym for
time. calls implies time.
I2C bus communication is an inherently unreliable. It is the responsibility
of the program using the bus to manage retries in case of failure. This
option reports retry counts and various performance statistics.
- --ddc
- Reports DDC protocol errors. These may reflect I2C bus errors, or
deviations by monitors from the MCCS specification.
Debugging options.
- --trace trace
group name
- Enable tracing for functions in the specified trace group. For a list of
trace group names, use the --help option. This option can be
specified more than once.
- --trcfunc
function name
- Trace the specified function, which must have been enabled for tracing.
This option can be specified more than once.
- --trcfile file
name
- Trace all functions in a source file that are enabled for tracing. The
argument is a simple file name, with or without the ".c" suffix,
e.g. "i2c_bus_core", "i2c_bus_core.c". This option can
be specified more than once.
- --timestamp,
--ts
- Preface trace messages with the time since program start.
- --wall-timestamp,
--wts
- Preface trace messages with the current wall time.
--thread-id,--tid Preface trace messages with the thread
number.
- --syslog
- Write trace messages to the system log.
- --excp
- Report freed exceptions
- --use-file-io
- Use the write()/read() interface of driver i2c-dev to send and receive I2C
packets. This is the default for the nvidia proprietary driver.
- --use-ioctl-io
- Use the ioctl() interface of driver i2c-dev to send and receive I2C
packets. This is the default for video drivers other than the proprietary
nvidia driver.
Options for program information.
- -h,--help
- Show program help.
- -V, --version
- Show program version.
- --settings
- Report option settings in effect.
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.
Sanford Rockowitz (rockowitz at minsoft dot com)
Copyright 2015-2023 Sanford Rockowitz