Man pages sections > man1 > ddcutil

ddcutil - Query and change monitor settings

ddcutil(1) General Commands Manual ddcutil(1)

NAME

ddcutil - Query and change monitor settings

SYNOPSIS

ddcutil [--display|--dis|-d dispno] [--bus|-b busno] [--adl|-a adapter-index.display-index] [--hiddev hiddevdevicenumber] [--usb|-u busnum.devicenum] [--edid 256 hex character EDID] [--mfg|-g manufacturer code] [--model|-l model name] [--sn|-n serial number] [--noverify] [-v|--verbose] [-t|--terse|--brief] [-U|--show-unsupported] [--ddc] [-s|--stats] [--trace trace-class] [--timestamp|--ts] [--maxtries commaseparatedlist] [--force-slave-address] [-f|--force] [--async] [--nodetect] [-V|--version] [h|--help] detect | listvcp | capabilities | getvcp | probe [feature-code|feature-group] |setvcp feature-code new-value ] | vcpinfo [feature-code|feature-group] | dumpvcp [filename] | loadvcp filename ] | environment | usbenvironment'| interrogate
 
 
 
 

DESCRIPTION

ddcutil is used to query and change monitor settings.
 
ddcutil communicates with monitors implementing MCCS (Monitor Control Command Set) using the DDC/CI protocol on the I2C bus. Normally, the video driver for the monitor exposes the I2C bus as devices named /dev/i2c-n. Alternatively, ddcutil can communicate with USB connected monitors implementing 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.
 
In general, the monitor settings that can be controlled by ddcutil are a superset of what 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.
 
For extended documentation, see http://www.ddcutil.com.
 

COMMANDS

detect Report attached monitors
vcpinfo [ feature-code | feature-group ]
Describe VCP feature codes that ddcutil knows how to interpret
capabilities
Query the monitor's capabilities string
getvcp [ feature-code | feature-group ]
Report a single VCP feature value, or a group of feature values
setvcp feature-code new-value
Set a single VCP feature value
dumpvcp filename
Save color related VCP feature values in a file. If no file name is specified, one is generated and the file is saved <describe location>
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.
environment
Probe the ddcutil installation environment.
usbenv
Probe USB aspects of the ddcutil installation environment.
probe
Explore the capabilities and features of a sing monitor.
interrogate
Collect maximum information for problem diagnosis.
chkusbmon
Tests if hiddev device is a USB connected monitor, for use in udev rules.

COMMAND ARGUMENTS

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 recognized. For a complete list, use the --help option.
ALL
All feature codes understood by ddcutil KNOWN Scan all understood feature codes, but show only codes supported by the monitor 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
 
A number in the range 0..255
 
 
 
 
 

OPTIONS

Options for monitor selection. If none are of these options are specified, the default is the first detected monitor. Options --mfg, --model and --sn can be specified together. -d,--display display-number logical display number (starting from 1) -b,--bus bus-number I2C bus number -a,--adl adapterIndex.displayIndex ADL adapter and display indexes --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.
 
Options to control the amount and form of output. -U, --show-unsupported Normally, getvcp does not report unsupported features when querying a feature-group. This option forces output. -t, --terse, --brief Show brief detail. For command getvcp, the output is in machine readable form. -v, --verbose Show extended detail
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. --trace trace-class Enable debug tracing for a trace class. Valid values are: base, i2c, adl, ddc, main, and the special value all. Some trace classes are more useful than others.
 
Specify this option multiple times to enable multiple trace classes. --timestamp, --ts Prepend trace messages with elapsed time
Options for program information. -h,--help Show program help. -V, --version Show program version.
Options to tune execution: --maxtries (max-read-tries, max-write-read-tries, max-multi-part-read-tries) Adjust the number of retries --force-slave-address Take control of slave addresses on the I2C bus even they are in use. -f, --force Do not check certain parameters. --verify Verify values set by setvcp or loadvcp. (default) --noverify Do not verify values set by setvcp or loadvcp. --async If there are multiple monitors, initial checks are performed in multiple threads, improving performance. --nodetect If the monitor is specified by its I2C bus number (option --busno) skip the monitor detection phase, improving performance.
 

EXECUTION ENVIRONMENT

requires package i2c-dev
 
i2c permissions
 

NVIDIA PROPRIETARY DRIVER

Some newer Nvidia cards (e.g. GTX660Ti) require special settings to properly enable I2C support. If you are using this driver and ddcctool does not work with your Nvidia card (TODO: Describe symptoms), you can try the following:
 
Copy file /usr/local/share/ddcutil/data/90-nvidia-i2c.conf to directory /etc/X11/xorg.conf.d
 
sudo cp /usr/local/share/ddcutil/data/90-nvidia-i2c.conf /etc/X11/xorg.conf.d
 
This file will work "out of the box" if you do not have an /etc/X11/xorg.conf file. If you do, adjust the Identifier value in the file to correspond to the value in the master xorg.conf file.
 
(Note that the above instructions assume that datadir was set to /usr/local/share when ddcutil was installed. YMMV)
 

AMD PRORIETARY DRIVER

AMD's proprietary video driver fglrx does not expose the I2C bus. Instead, it provides access to the bus through the AMD Display Library, aka ADL. Owing to copyright restrictions, the ADL header files are not distributed with the ddcutil source. Additional steps are required to build ddcutil with fglrx support.
 
To see if your copy of ddcutil was built with fglrx support, issue the command:
 
ddcutil --version
 
ADL identifies monitors using an adapter-number/display-number pair. To select a monitor using these numbers, specify the --adl option with a period separating the adapter-number and display-number, e.g.
 
--adl 0.1
 
 

VIRTUAL MACHINES

Virtualized video drivers in VMWare and VirtualBox do not provide I2C emulation. Use of normal video drivers with PCI passthrough in a virtual machine has not been tested.
 
 

EXAMPLES

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.
 
 

DIAGNOSTICS

Returns 0 on success, 1 on failure.
 
Requesting help is regarded as success.
 
 
 
 

SEE ALSO

The project homepage: http://www.ddcutil.com
 
 
 
 
 
 
 

AUTHOR

Sanford Rockowitz (rockowitz at minsoft dot com)
 
Copyright 2015-2016 Sanford Rockowitz
 
 
15 December 2015 Debian Sid