ddcutil - Man Page

• List all compatible displays: ddcutil detect
• Change the brightness (option 0x10) of display 1 to 50%: ddcutil [-d|--display] 1 setvcp 10 50
• Increase the contrast (option 0x12) of display 1 by 5%: ddcutil [-d|--display] 1 setvcp 12 + 5
• Read the settings of display 1: ddcutil [-d|--display] 1 getvcp ALL

tldr.sh

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.   The 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 settings vary from monitor to monitor.

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 with 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.

Common use cases include changing monitor brightness and color.  Using scripts, the changes can be effected by keystrokes, or in response to the time of day.   Another common use case is to switch the monitor input source.

A more complex  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.

This man page describes 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. If option --verbose is specifeid in conjunction with --help, more extensive help on option arguments is shown.

Option --hh shows all options recognized by ddcutil. These include deprecated option names (which have been replaced by more descriptive names), experimental options, and options only of interest to developers.

ddcutil does not support laptop monitors, which do not implement DDC/CI.

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 on some monitors 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 for program information.

-V,  --version

Show program version.

--settings

Report option settings in effect.

-h,--help

Show program help.

--hh

Show program help including hidden options. Hidden options include alternative option names, experimental and deprecated options, and ones for debugging.

Options for diagnostic output

--ddcdata

Reports DDC protocol errors.  These may reflect I2C bus errors, or deviations by monitors from the MCCS specification. Formerly named --ddc,

--stats [all|errors|tries|calls|elapsed|time]

Report execution statistics. I2C bus communication is inherently unreliable.  It is the responsibility of the program using the bus, i.e. ddcutil, to manage retries in case of failure.  This option reports retry counts and various performance statistics. If no argument is specified, or ALL is specified, then all statistics are  output.  ELAPSED is a synonym for TIME.  CALLS implies TIME.

--vstats [all|errors|tries|calls|elapsed|time]

Like --stats, but includes per-display statistics.

--istats [all|errors|tries|calls|elapsed|time]

Like --vstats, but includes additional internal information.

--syslog [debug|verbose|info|notice|warn|error|never ]

Write messages of the specified or more urgent severity level to the system log. The ddcutil default is WARN. The libddcutilP default is NOTICE.

--libddcutil-trace-filefilename

Direct trace output to the specified file instead of the terminal. This is a libddcutil only option.

--tracetrace-class-name

Trace all functions in a trace class.  For a list of trace classes, use --help --verbose.

--trcfuncfunction-name

Trace a specific function.

Options that tune execution

--enable-capabilities-cache,  --disable-capabilities-cache

Enable or disable caching of capabilities strings, improving performance. The default is --enable-capabilities-cache

--enable-dynamic-sleep,  --disable-dynamic-sleep

Dynamically adjust the sleep-multiplier over multiple ddcutil invocations, improving performance.

The default is --enable-dynamic-sleep

--min-dynamic-multiplier decimal number

Modify the dynamic sleep algorithm to never adjust the sleep multiplier below this value. This option can help dampen swings in sleep multiplier values.

--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 require sleep-multiplier values greater than 1.0.  In general, newer option --enable-dynamic-sleep will provide better performance.

--lazy-sleep

Peform mandated sleeps before the next DDC/CI operation instead of immediately after the DDC/CI operation that specified a delay, marginally improving performance.

--ddc-checks-async-min

If there are several monitors, initial DDC checks are performed in multiple threads, improving performance. This option was formerly (and ambiguously) named --async.  The default is --ddc-checks-async-min 3

--skip-ddc-checks

Assume DDC communication works and monitors properly use the invalid feature flag in a DDC/CI Reply packet to indicate an unsupported feature, improving display detection performance.

--discard-cache [capabilities|dsa|all

Discard cached display information and/or dynamic sleep data.

Options that modify behavior

--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.

--verify | --noverify

Verify or do not verify values set by setvcp or loadvcp. --noverify is the default.

--mccs MCCS version

Tailor command input and  output to a particular MCCS version, e.g. 2.1

--enable-udf,  --disable-udf

Enable or disable support for user supplied feature definitions. The default is --enable-udf

--enable-usb,  --disable-usb

Enable or disable support for monitors that implement USB communication with the Virtual Control Panel. (These options are available only if ddcutil was built with USB support.) The default is --disable-usb

--ignore-usb-vid-pid vid:pid

Force ddcutil to ignore a particular USB device, specified by its 4 hex digit vendor id and its 4 hex digit product id.

--ignore-hiddev hiddev-device-number

Force ddcutil to ignore a particular USB device, specified by /dev/usb/hiddev device number

--use-file-io | --use-ioctl-io

Cause ddcutil to use the write()/read() interface or the ioctl interface of driver dev-i2c to send and receive I2C packets. By default, ddcutil uses the ioctl interface.  Nvidia proprietary driver are built in a way such that the ioctl interface can fail, in which case ddcutil switches to using the file io interface.

--force-slave-address

Take control of slave addresses on the I2C bus even they are in use. Has use only with file-io, not with ioctl-io.

--enable-cross-instance-locks | --disable-cross-instance-locks

Coordinates /dev/i2c device access across multiple instance of ddcutil and libddcutil. The default is --enable-cross-instance-locks

--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.

--i2c-source-addr hex-addr

Use this as the source address in DDC packet, instead of the normal value. This option has been found to enable access some control functions when using some displays, particularly from LG.

--permit-unknown-feature

Allow setvcp of unknown features.

--noconfig

Do not process the configuration file

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.

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

Sanford Rockowitz (rockowitz at minsoft dot com)
Copyright 2015-2023 Sanford Rockowitz