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
18 ddcutil is used to query and change monitor settings.
19 ddcutil communicates with monitors that implement the Monitor Control
21 Command Set (MCCS) using the DDC/CI protocol on an I2C bus. Normally,
22 the video driver for the monitor exposes the I2C bus as devices named
23 /dev/i2c-n. Alternatively, ddcutil can communicate with monitors that
24 use USB to communicate MMCS, provided the monitors meet the USB Monitor
25 Control Class Specification.
26 The Monitor Control Command Set describes a collection of Virtual Con‐
28 trol Panel (VCP) features that a monitor can implement. Each feature
29 is identified using a single byte. For example, feature x10 is the
30 brightness control.
31 The monitor settings that can be controlled by ddcutil are, generally
33 speaking, those that can be changed using the buttons on a monitor and
34 its on screen display. The specific capabilities vary from monitor to
35 monitor.
36 A particular use case for ddcutil is as part of color profile manage‐
38 ment. Monitor calibration is relative to the monitor color settings
39 currently in effect, e.g. red gain. ddcutil allows color related set‐
40 tings to be saved at the time a monitor is calibrated, and then re‐
41 stored when the calibration is applied.
42 Another common use case is to switch the monitor input source.
44 This man page describes ddcutil commands and options most important to
46 the typical user. For complete documentation, use the --help option or
47 see the web site ⟨http://www/ddcutil.com⟩.
48
52 ddcutil does not support laptop monitors, which do not implement
53 DDC/CI.
54
58 Primary Commands
59 These are the most used ddcutil commands.
60 detect "Report monitors"
62 vcpinfo [ feature-code | feature-group ]
64 Describe VCP feature codes. as defined in the MCCS specifica‐
65 tion. Use option --verbose to see values for Non-Continuous
66 features.
67 capabilities
69 Query the monitor's capabilities string
70 getvcp [ feature-code | feature-group ] ...
72 Report a VCP feature value, or a group of feature values. More
73 than one feature code can be specified. However feature codes
74 and groups cannot be combined.
75 setvcp feature-code [+|-] new-value ...
77 Set a VCP feature value. If + or - is specified, it must be
78 surrounded by blanks, and indicates a relative value change of a
79 continuous VCP feature. Multiple feature/value pairs (with or
80 without [+|1]) can be specified.
81 Secondary Commands
83 These commands address special situations.
84 dumpvcp filename
86 Save color profile related VCP feature values in a file. If no
87 file name is specified, one is generated and the file is saved
88 in $HOME/.local/share/ddcutil,
89 loadvcp filename
91 Set VCP feature values from a file. The monitor to which the
92 values will be applied is determined by the monitor identifica‐
93 tion stored in the file. If the monitor is not attached, noth‐
94 ing happens.
95 scs Issue DDC/CI Save Current Settings request. Most monitors do not
97 implement this command. A few require it for values changed by
98 setvcp to take effect.
99 chkusbmon
101 Tests if a hiddev device may be a USB connected monitor, for use
102 in udev rules.
103 Diagnostic commands
105 These commands diagnose issues in the system configuration that affect
106 ddcutil operation, and that gather information for remote problem diag‐
107 nosis.
108 environment
110 Probe the ddcutil installation environment.
111 usbenv Probe USB aspects of the ddcutil installation environment.
113 probe Explore the capabilities and features of a single monitor.
115 interrogate
117 Collect maximum information for problem diagnosis. Includes the
118 output of ddcutil environment --verbose andfor each detected
119 monitor, the output of ddcutil capabilities --verbose and ddcu‐
120 til probe --verbose.
121
123 feature-code
124 A feature-code is specified by its 2 character hex feature number, with
126 or without a leading "0x", e.g. 0x10, 10
127 feature-group
130 The following are the most useful feature groups. For a complete list,
133 use the --help option.
134 ALL|KNOWN
136 All feature codes understood by ddcutil
137 COLOR Scan color related feature codes
138 PROFILE
139 Subset of color related feature codes that are saved and re‐
140 stored by dumpvcp and loadvcp
141 SCAN Scan all possible feature codes 0x00..0xff, except those known
142 the be write-only
143 Feature group names can be abbreviated to the first 3 characters. Case
145 is ignored. e.g. "COL", "pro".
146 new-value
148 Normally, this is a decimal number in the range 0..255, or a hexadeci‐
150 mal number in the range x00..xff. More generally, this is actually a
151 two byte value, i.e. x00..xffff, and a few features on some monitors
152 use this extended range.
153
159 Options for monitor selection. If none are specified, the default is
160 the first detected monitor. Options --mfg, --model and --sn can be
161 specified together.
162 -d , --dis , --display ,
163 display-number logical display number (starting from 1)
164 -b,--bus
165 bus-number I2C bus number
166 --hiddev
167 device number hiddev device number
168 -u,--usb busnum.devicenum
169 USB bus and device numbers
170 -g,--mfg
171 3 letter manufacturer code
172 -l,--model
173 model name
174 -n,--sn
175 serial number. (This is the "serial ascii" field from the EDID,
176 not the binary serial number.)
177 -e,--edid
178 256 hex character representation of the 128 byte EDID. Needless
179 to say, this is intended for program use.
180 Feature selection filters
183 -U, --show-unsupported
184 Normally, getvcp does not report unsupported features when
185 querying a feature-group. This option forces output.
186 --show-table | --no-table
187 Normally, getvcp does not report Table type features when query‐
188 ing a feature-group. --show-table forces output. --no-table
189 is the default.
190 --rw, --ro, --wo
191 Limit getvcp or vcpinfo output to read-write, read-only, or (for
192 vcpinfo) write-only features.
193 Options that control the amount and form of output.
196 -t, --terse, --brief
197 Show brief detail. For command getvcp, the output is in machine
198 readable form.
199 -v, --verbose
200 Show extended detail
201 Options for program information.
204 -h,--help
205 Show program help.
206 -V, --version
207 Show program version.
208 --settings
209 Report option settings in effect.
210 Options for diagnostic output
213 --ddc Reports DDC protocol errors. These may reflect I2C bus errors,
214 or deviations by monitors from the MCCS specification.
215 [--stats|--vstats] [all|errors|tries|calls|elapsed|time]
216 Report execution statistics.
217 I2C bus communication is an inherently unreliable. It is the
218 responsibility of the program using the bus, i.e. ddcutil, to
219 manage retries in case of failure. This option reports retry
220 counts and various performance statistics. If no argument is
221 specified, or ALL is specified, then all statistics are output.
222 ELAPSED is a synonym for TIME. CALLS implies TIME.
223 --vstats [all|errors|tries|calls|elapsed|time]
225 Like --stats, but includes per-display statistics.
226 --syslog[ debug|verbose|info|notice|warn|error|never ]
227 Write messages of the specified or more urgent severity level to
228 the system log. The default is WARN.
229 Options that tune execution
232 --enable-capabilities-cache, --disable-capabilities-cache
233 Enable or disable caching of capabilities strings, improving
234 performance. The default is --enable-capabilities-cache
235 --enable-displays-cache, --disable-displays-cache
236 Enable or disable caching of information about detected dis‐
237 plays, improving performance. The default is --enable-displays-
238 cache
239 --sleep-multiplier decimal number
240 Adjust the length of waits listed in the DDC/CI specification by
241 this number to determine the actual wait time. Well behaved
242 monitors work with sleep-multiplier values less than 1.0, while
243 monitors with poor DDC implementations may require sleep-multi‐
244 plier values greater than 1.0.
245 --enable-dynamic-sleep, --disable-dynamic-sleep
246 Dynamically adjust the sleep-multiplier over multiple ddcutil
247 invocations, improving performance. The default is --enable-dy‐
248 namic-sleep
249 --async
250 If there are several monitors, initial checks are performed in
251 multiple threads, improving performance.
252 --lazy-sleep
253 Peform mandated sleeps before the next DDC/CI operation instead
254 of immediately after the DDC/CI operation that specified a de‐
255 lay, marginally improving performance.
256 Options that modify behavior
259 --maxtries (max-read-tries, max-write-read-tries, max-multi-part-tries)
260 Adjust the number of retries. A value of "." or "0" leaves the
261 setting for a retry type unchanged.
262 --verify | --noverify
263 Verify or do not verify values set by setvcp or loadvcp.
264 --noverify is the default.
265 --mccs MCCS version
266 Tailor command input and output to a particular MCCS version,
267 e.g. 2.1
268 --enable-udf, --disable-udf
269 Enable or disable support for user supplied feature definitions.
270 The default is --enable-udf
271 --enable-usb, --disable-usb
272 Enable or disable support for monitors that implement USB com‐
273 muincation with the Virtual Control Panel. (These options are
274 available only if ddcutil was built with USB support.) The de‐
275 fault is --disable-usb
276 --ignore-usb-vid-pidvid:pid
277 Force ddcutil to ignore a particular USB device, specified by
278 its 4 hex digit vendor id and its 4 hex digit product id.
279 --ignore-hiddev hiddev-device-number
280 Force ddcutil to ignore a particular USB device, specified by
281 /dev/usb/hiddev device number
282 --use-file-io | --use-ioctl-io
283 Cause ddcutil to use the write()/read() interface or the ioctl
284 interface of driver dev-i2c to send and receive I2C packets. By
285 default, ddcutil uses the ioctl interface. Depending on how the
286 Nvidia proprietary driver was built, this can fail, in which
287 case ddcutil switches to using the file io interface.
288 --force-slave-address
289 Take control of slave addresses on the I2C bus even they are in
290 use. Has use only for the proprietary Nvidia video driver.
291 --edid-read-size 128|256
293 Force ddcutil to read the specified number of bytes when reading
294 the EDID. This option is a work-around for certain driver bugs.
295 The default is 256.
296
300 Requires read/write access to /dev/i2c devices. See
301 ⟨http://www.ddcutil.com/i2c_permissions⟩
302
305 Some Nvidia cards using the proprietary Nvidia driver require special
306 settings to properly enable I2C support. See
307 ⟨http://www.ddcutil.com/nvidia⟩.
308
312 Virtualized video drivers in VMWare and VirtualBox do not provide I2C
313 emulation. Use of normal video drivers with PCI passthrough is possi‐
314 ble.
315
319 ddcutil detect
320 Identify all attached monitors.
321 ddcutil getvcp supported
326 Show all settings that the default monitor supports and that ddcutil
328 understands.
329 ddctpp getvcp 10 --display 2
331 Query the luminosity value of the second monitor.
332 ddcutil setvcp 10 30 --bus 4
334 Set the luminosity value for the monitor on bus /dev/i2c-4.
335 ddcutil vcpinfo --verbose
337 Show detailed information about VCP features that ddcutil understands.
338 ddcutil interrogate > ~/ddcutil.out
340 Collect maximum information about monitor capabilities and the execu‐
341 tion environment, and direct the output to a file.
342
346 Returns 0 on success, 1 on failure.
347 Requesting help is regarded as success.
349
355 The project homepage: ⟨http://www.ddcutil.com⟩
356
365 Sanford Rockowitz (rockowitz at minsoft dot com)
366 Copyright 2015-2023 Sanford Rockowitz
367 2020-05-15 ddcutil(1)