.\" Hey, EMACS: -*- nroff -*- .\" First parameter, NAME, should be all caps .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection .\" other parameters are allowed: see man(7), man(1) .TH ddcutil 1 "01 April 2018" .\" Please adjust this date whenever revising the manpage. .\" .\" Some roff macros, for reference: .\" .nh disable hyphenation .\" .hy enable hyphenation .\" .ad l left justify .\" .ad b justify to both left and right margins .\" .nf disable filling .\" .fi enable filling .\" .br insert line break .\" .sp insert n+1 empty lines .\" for manpage-specific macros, see man(7) .SH NAME ddcutil \- Query and change monitor settings .SH SYNOPSIS .B ddcutil .RB [ "--adl" | "-a " .IR "adapter-index.display-index" ] .RB [ "--async" ] .RB [ "--bus|-b" .IR busno ] .RB [ --ddc ] .RB [ "--display|--dis|-d" .IR dispno ] .RB [ "--edid" .IR "256 hex character EDID" ] .RB [ "--excp" ] .RB [ "-f" | "--force" ] .RB [ "--force-slave-address" ] .RB [ "--hiddev" .IR hiddev device number ] .RB [ "--mfg" | "-g" .IR "manufacturer code" ] .RB [ --maxtries .IR (comma-separated-list) ] .RB [ "--model" | "-l" .IR "model name" ] .RB [ "--nodetect" ] .RB [ "--sn" | "-n" .IR "serial number" ] .RB [ " --rw | --ro | --wo" ] .RB [ "--show-table" | "--no-table" ] .RB [ "-s" | "--stats" .IR [stats-class] ] .RB [ -t | --terse | --brief | -v | --verbose ] .RB [ "-U" | "--show-unsupported" ] .RB [ "--usb" | "-u" .IR "busnum.devicenum" ] .RB [ "--verify | --noverify" ] .RB [ "-V" | "--version" ] .RB [ "h" | "--help" ] .BR detect " | " capabilities " | " scs " | " probe " | " getvcp " .RI [ "feature-code" | "feature-group" ] .RB | setvcp .I feature-code new-value ] | .BR vcpinfo " " .RI [ "feature-code" | "feature-group" "] | " .B dumpvcp .RI [ filename ] | .BI "loadvcp " filename ] | .BR environment " | " usbenvironment ' | " interrogate " " .\" ALT USING .SY .OP .\" .SY .\" .OP \-abcde .\" .OP \-b busno .\" .OP \-d|--display dispno .\" command command-arguments .\" .YS .SH DESCRIPTION \fBddcutil\fP is used to query and change monitor settings. \fBddcutil\fP 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, \fBddcutil\fP 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 \fBddcutil\fP 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 \fBddcutil\fP is as part of color profile management. Monitor calibration is relative to the monitor color settings currently in effect, e.g. red gain. \fBddcutil\fP 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 includes only abbreviated documentation of trace and other program diagnostic facilities. For extended documentation, use the "--help" option, and see http://www.ddcutil.com. .PP .\" TeX users may be more comfortable with the \fB\fP and .\" \fI\fP escape sequences to invode bold face and italics, .\" respectively. .\" .B ddcutil .\" .I command .\" .R [ .\" .I command-arguments .\" .R ] [ .\" .I options .\" .R ] .SH COMMANDS .TP .BR "detect " "Report monitors" .TP \fBvcpinfo\fP [ \fIfeature-code\fP | \fIfeature-group\fP ] Describe VCP feature codes that \fBddcutil\fP knows how to interpret .TP .B "capabilities " Query the monitor's capabilities string .TP \fBgetvcp\fP [ \fIfeature-code\fP | \fIfeature-group\fP ] Report a single VCP feature value, or a group of feature values .TP .BI "setvcp " "[+|-] " "feature-code new-value" Set a single VCP feature value. If + or - is specified, it must be surrounded by blanks, and indicates a relative value change of a Continuous VCP feature. .TP .BI "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 .TP .BI "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. .TP .B "environment " Probe the \fBddcutil\fP installation environment. .TP .B "scs " Issue DDC/CI Save Current Settings request. .TP .B "usbenv " Probe USB aspects of the \fBddcutil\fP installation environment. .TP .B "probe " Explore the capabilities and features of a single monitor. .TP .B "interrogate " Collect maximum information for problem diagnosis. .TP .B "chkusbmon " Tests if hiddev device is a USB connected monitor, for use in udev rules. .PP .SH COMMAND ARGUMENTS .I feature-code .sp A feature-code is specified by its 2 character hex feature number, with or without a leading "0x", e.g. 0x10, 10 .sp 2 .I feature-group .sp 2 The following are the most useful feature groups recognized. For a complete list, use the \fB--help\fP option. .TP .BR ALL|KNOWN All feature codes understood by \fBddcutil\fP .TQ .B COLOR Scan color related feature codes .TQ .B PROFILE Subset of color related feature codes that are saved and restored by \fBdumpvcp\fP and \fBloadvcp\fP .TQ .B SCAN Scan all possible feature codes 0x00..0xff, except those known the be write-only .PP Feature group names can be abbreviated to the first 3 characters. Case is ignored. e.g. COL, pro .I new-value .sp A decimal number in the range 0..255, or hexadeciaml number in the range x00..xff. .\" .TP inserts a line before its output, .TQ does not .SH OPTIONS Options for monitor selection. If none are of these options are specified, the default is the first detected monitor. Options \fB--mfg\fP, \fB--model\fP and \fB--sn\fP can be specified together. .TQ .BR -d , "--display " .I display-number logical display number (starting from 1) .TQ .BR "-b,--bus " .I bus-number I2C bus number .TQ .BI "-a,--adl " "adapterIndex.displayIndex" ADL adapter and display indexes .TQ .BR "--hiddev " .I device number hiddev device number .TQ .BI "-u,--usb " "busnum.devicenum" USB bus and device numbers .TQ .B -g,--mfg 3 letter manufacturer code .TQ .B -l,--model model name .TQ .B -n,--sn serial number. (This is the "serial ascii" field from the EDID, not the binary serial number.) .TQ \fB-e,--edid\fP 256 hex character representation of the 128 byte EDID. Needless to say, this is intended for program use. .PP Options to control the amount and form of output. .TQ .B "-t, --terse, --brief" Show brief detail. For command \fBgetvcp\fP, the output is in machine readable form. .TQ .B -v, --verbose Show extended detail .TQ .B "-U, --show-unsupported" Normally, \fBgetvcp\fP does not report unsupported features when querying a feature-group. This option forces output. .TQ .B "--show-table | --no-table Normally, \fBgetvcp\fP does not report Table type features when querying a feature-group. \fB--show-table\fP forces output. \fB--no-table\fP is the default. .TQ .B "--rw, --ro, --wo" Limit \fBgetvcp\fP or \fBvcpinfo\fP output to read-write, read-only, or (for \fBvcpinfo\fP) write-only features. .TQ .B "--mccs " "MCCS version" Tailor \fBvcpinfo\fP output to a particular MCCS version, e.g. 2.1 .PP Options for diagnostic output. .TQ .BR --stats " [" all | errors | tries | calls | elapsed | time ] Report execution statistics. If no argument is specified, or ALL is specified, then all statistics are output. \fBelapsed\fP is a synonym for \fBtime\fP. \fBcalls\fP implies \fBtime\fP. .br Specify this option multiple times to report multiple statistics groups. .br 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. .TQ .B --ddc Reports DDC protocol errors. These may reflect I2C bus errors, or deviations by monitors from the MCCS specification. .PP Options for program information. .TQ .BR -h , --help Show program help. .TQ .B "-V, --version" Show program version. .PP Options to tune execution: .TQ .BI "--maxtries " "(max-read-tries, max-write-read-tries, max-multi-part-tries)" Adjust the number of retries .TQ .B "--force-slave-address" Take control of slave addresses on the I2C bus even they are in use. .TQ .B "-f, --force" Do not check certain parameters. .TQ .B "--verify" Verify values set by \fBsetvcp\fP or \fBloadvcp\fP. (default) .TQ .B "--noverify" Do not verify values set by \fBsetvcp\fP or \fBloadvcp\fP. .TQ .B "--async" If there are multiple monitors, initial checks are performed in multiple threads, improving performance. .TQ .B "--nodetect" If the monitor is specified by its I2C bus number (option \fB--busno\fP) skip the monitor detection phase, improving performance. .SH EXECUTION ENVIRONMENT Requires read/write access to /dev/i2c devices. See http://www.ddcutil.com/i2c_permissions. .SH 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 \fBddcctool\fP 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 .B 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 \fBIdentifier\fP 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) For further discussion of Nvidia driver settings, see http://www.ddcutil.com/nvidia. .SH AMD PRORIETARY DRIVER AMD's proprietary video driver \fBfglrx\fP does not expose the I2C bus. Instead, it provides access to the bus through the AMD Display Library, aka \fBADL\fP. Owing to copyright restrictions, the ADL header files are not distributed with the \fBddcutil\fP source. Additional steps are required to build \fBddcutil\fP with \fBfglrx\fP support. To see if your copy of \fBddcutil\fP was built with \fBfglrx\fP support, issue the command: .br .B ddcutil --version ADL identifies monitors using an adapter-number/display-number pair. To select a monitor using these numbers, specify the \fB--adl\fP option with a period separating the adapter-number and display-number, e.g. .br .B --adl 0.1 .SH VIRTUAL MACHINES Virtualized video drivers in VMWare and VirtualBox do not provide I2C emulation. Use of normal video drivers with PCI passthrough is possible. .SH EXAMPLES .\" What do .EX and .EE do? .B ddcutil detect .sp 0 Identify all attached monitors. .sp 4 .B ddcutil getvcp supported .sp 1 .br Show all settings that the default monitor supports and that \fBddcutil\fP understands. .PP .sp 0 .B ddctpp getvcp 10 --display 2 .br Query the luminosity value of the second monitor. .B ddcutil setvcp 10 30 --bus 4 .sp 0 Set the luminosity value for the monitor on bus /dev/i2c-4. .B ddcutil vcpinfo --verbose .sp 0 Show detailed information about VCP features that \fBddcutil\fP understands. .B ddcutil interrogate > ~/ddcutil.out .sp 0 Collect maximum information about monitor capabilities and the execution environment, and direct the output to a file. .SH DIAGNOSTICS Returns 0 on success, 1 on failure. Requesting help is regarded as success. .\" .SH FILES .SH SEE ALSO .\" README file /usr/local/share/doc/ddcutil/README.md .\" The program is documented fully in .\" .br .\" /usr/local/share/doc/ddcutil/html/index.html .\" .PP The project homepage: http://www.ddcutil.com .\" .SH NOTES .\" .SH BUGS .SH AUTHOR Sanford Rockowitz (rockowitz at minsoft dot com) .br Copyright 2015\-2018 Sanford Rockowitz