1ddcutil(1) General Commands Manual ddcutil(1)
2
6 ddcutil - Query and change monitor settings
7
9 ddcutil [options] command [command-arguments] [options]
10 Options can be written either before or after the command and its argu‐
12 ments.
13
19 ddcutil is used to query and change monitor settings.
20 ddcutil communicates with monitors that implement the Monitor Control
22 Command Set (MCCS) using the DDC/CI protocol on an I2C bus. Normally,
23 the video driver for the monitor exposes the I2C bus as devices named
24 /dev/i2c-n. Alternatively, ddcutil can communicate monitors that use
25 USB to communicate MMCS, provided the monitors meet the USB Monitor
26 Control Class Specification.
27 The Monitor Control Command Set describes a collection of Virtual Con‐
29 trol Panel (VCP) features that a monitor can implement. Each feature
30 is identified using a single byte. For example, feature x10 is the
31 brightness control.
32 In general, the monitor settings that can be controlled by ddcutil are
34 a superset of what can be changed using the buttons on a monitor and
35 its on screen display. The specific capabilities vary from monitor to
36 monitor.
37 A particular use case for ddcutil is as part of color profile manage‐
39 ment. Monitor calibration is relative to the monitor color settings
40 currently in effect, e.g. red gain. ddcutil allows color related set‐
41 tings to be saved at the time a monitor is calibrated, and then
42 restored when the calibration is applied.
43 Another common use case is to switch the monitor input source.
45 This man page focuses on the ddcutil commands and options most impor‐
47 tant to the typical user. For complete documentation, use the --help
48 option or see the web site ⟨http://www/ddcutil.com⟩.
49
53 ddcutil does not support with laptop monitors, which do not implement
54 DDC/CI.
55
59 Primary Commands
60 These are the most used ddcutil commands.
61 detect "Report monitors"
63 vcpinfo [ feature-code | feature-group ]
65 Describe VCP feature codes. as defined in the MCCS specifica‐
66 tion.
67 capabilities
69 Query the monitor's capabilities string
70 getvcp [ feature-code | feature-group ]
72 Report a single VCP feature value, or a group of feature values
73 setvcp feature-code [+|-] new-value
75 Set a single VCP feature value. If + or - is specified, it must
76 be surrounded by blanks, and indicates a relative value change
77 of a Continuous VCP feature.
78 Secondary Commands
80 These commands address special situations.
81 dumpvcp filename
83 Save color profile related VCP feature values in a file. If no
84 file name is specified, one is generated and the file is saved
85 <describe location>
86 loadvcp filename
88 Set VCP feature values from a file. The monitor to which the
89 values will be applied is determined by the monitor identifica‐
90 tion stored in the file. If the monitor is not attached, noth‐
91 ing happens.
92 scs Issue DDC/CI Save Current Settings request.
94 chkusbmon
96 Tests if a hiddev device is a USB connected monitor, for use in
97 udev rules.
98 Diagnostic commands
100 These commands diagnose issues in the system configuration that affect
101 ddcutil operation, and that gather information for remote problem diag‐
102 nosis.
103 environment
105 Probe the ddcutil installation environment.
106 usbenv Probe USB aspects of the ddcutil installation environment.
108 probe Explore the capabilities and features of a single monitor.
110 interrogate
112 Collect maximum information for problem diagnosis. Includes the
113 output of ddcutil environment --verbose andfor each detected
114 monitor, the output of ddcutil capabilities --verbose and ddcu‐
115 til probe --verbose.
116
118 feature-code
119 A feature-code is specified by its 2 character hex feature number, with
121 or without a leading "0x", e.g. 0x10, 10
122 feature-group
125 The following are the most useful feature groups. For a complete list,
128 use the --help option.
129 ALL|KNOWN
131 All feature codes understood by ddcutil
132 COLOR Scan color related feature codes
133 PROFILE
134 Subset of color related feature codes that are saved and
135 restored by dumpvcp and loadvcp
136 SCAN Scan all possible feature codes 0x00..0xff, except those known
137 the be write-only
138 Feature group names can be abbreviated to the first 3 characters. Case
140 is ignored. e.g. "COL", "pro".
141 new-value
144 Normally, this is a decimal number in the range 0..255, or a hexadeci‐
146 mal number in the range x00..xff. More generally, this is actually a
147 two byte value, i.e. x00..xffff, and a few features use this extended
148 range.
149
156 Options for monitor selection. If none are of these options are speci‐
157 fied, the default is the first detected monitor. Options --mfg,
158 --model and --sn can be specified together.
159 -d,--display
160 display-number logical display number (starting from 1)
161 -b,--bus
162 bus-number I2C bus number
163 --hiddev
164 device number hiddev device number
165 -u,--usb busnum.devicenum
166 USB bus and device numbers
167 -g,--mfg
168 3 letter manufacturer code
169 -l,--model
170 model name
171 -n,--sn
172 serial number. (This is the "serial ascii" field from the EDID,
173 not the binary serial number.)
174 -e,--edid
175 256 hex character representation of the 128 byte EDID. Needless
176 to say, this is intended for program use.
177 Options to control the amount and form of output.
180 -t, --terse, --brief
181 Show brief detail. For command getvcp, the output is in machine
182 readable form.
183 -v, --verbose
184 Show extended detail
185 -U, --show-unsupported
186 Normally, getvcp does not report unsupported features when
187 querying a feature-group. This option forces output.
188 --show-table | --no-table
189 Normally, getvcp does not report Table type features when query‐
190 ing a feature-group. --show-table forces output. --no-table
191 is the default.
192 --rw, --ro, --wo
193 Limit getvcp or vcpinfo output to read-write, read-only, or (for
194 vcpinfo) write-only features.
195 --mccs MCCS version
196 Tailor vcpinfo output to a particular MCCS version, e.g. 2.1
197 Options for diagnostic output.
199 --stats [all|errors|tries|calls|elapsed|time]
200 Report execution statistics. If no argument is specified, or
201 ALL is specified, then all statistics are output. elapsed is a
202 synonym for time. calls implies time.
203 I2C bus communication is an inherently unreliable. It is the
204 responsibility of the program using the bus to manage retries in
205 case of failure. This option reports retry counts and various
206 performance statistics.
207 --ddc Reports DDC protocol errors. These may reflect I2C bus errors,
208 or deviations by monitors from the MCCS specification.
209 Options to tune execution:
212 --maxtries (max-read-tries, max-write-read-tries, max-multi-part-tries)
213 Adjust the number of retries
214 --force-slave-address
215 Take control of slave addresses on the I2C bus even they are in
216 use.
217 --verify | --noverify
218 Verify or do not verify values set by setvcp or loadvcp.
219 --noverify is the default.
220 --async
221 If there are multiple monitors, initial checks are performed in
222 multiple threads, improving performance.
223 Options for program information.
225 -h,--help
226 Show program help.
227 -V, --version
228 Show program version.
229
232 Requires read/write access to /dev/i2c devices. See
233 ⟨http://www.ddcutil.com/i2c_permissions⟩
234
237 Some Nvidia cards using the proprietary Nvidia driver require special
238 settings to properly enable I2C support. If you are using this driver
239 and ddccutil does not work with your Nvidia card, you can try the fol‐
240 lowing:
241 Copy file /usr/share/ddcutil/data/90-nvidia-i2c.conf to directory
243 /etc/X11/xorg.conf.d:
244 sudo cp /usr/share/ddcutil/data/90-nvidia-i2c.conf /etc/X11/xorg.conf.d
246 This file will work "out of the box" if you do not have an
248 /etc/X11/xorg.conf file. If you do, adjust the Identifier value in
249 the file to correspond to the value in the master xorg.conf file.
250 (The above instructions assume that the normal location of the ddcutil
252 data directory. YMMV.)
253 For further discussion of Nvidia driver settings, see
255 ⟨http://www.ddcutil.com/nvidia⟩.
256
260 Virtualized video drivers in VMWare and VirtualBox do not provide I2C
261 emulation. Use of normal video drivers with PCI passthrough is possi‐
262 ble.
263
267 ddcutil detect
268 Identify all attached monitors.
269 ddcutil getvcp supported
274 Show all settings that the default monitor supports and that ddcutil
276 understands.
277 ddctpp getvcp 10 --display 2
279 Query the luminosity value of the second monitor.
280 ddcutil setvcp 10 30 --bus 4
282 Set the luminosity value for the monitor on bus /dev/i2c-4.
283 ddcutil vcpinfo --verbose
285 Show detailed information about VCP features that ddcutil understands.
286 ddcutil interrogate > ~/ddcutil.out
288 Collect maximum information about monitor capabilities and the execu‐
289 tion environment, and direct the output to a file.
290
294 Returns 0 on success, 1 on failure.
295 Requesting help is regarded as success.
297
303 The project homepage: ⟨http://www.ddcutil.com⟩
304
313 Sanford Rockowitz (rockowitz at minsoft dot com)
314 Copyright 2015-2020 Sanford Rockowitz
315 2020-05-15 ddcutil(1)