ddcutil - Man Page

Query and change monitor settings

Synopsis

ddcutil [options] command [command-arguments] [options]

Options can be written either before or after the command and its arguments.

Description

ddcutil is used to query and change monitor settings.  

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

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.

This man page focuses on the 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.

Restrictions

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

Commands

Primary Commands

These are the most used ddcutil commands.

detect

"Report monitors"

vcpinfo [ feature-code | feature-group ]

Describe VCP feature codes. as defined in the MCCS specification.

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.  If + or - is specified, it must be surrounded by blanks, and indicates a relative value change of a Continuous VCP feature.

Secondary Commands

These commands address special situations.

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

scs

Issue DDC/CI Save Current Settings request.

chkusbmon

Tests if a hiddev device is a USB connected monitor, for use in udev rules.

Diagnostic commands

These commands  diagnose issues in the system configuration that affect  ddcutil operation,   and that gather information for remote problem diagnosis.

environment

Probe the ddcutil installation environment.

usbenv

Probe USB aspects of the ddcutil installation environment.

probe

Explore the capabilities and features of a single monitor.

interrogate

Collect maximum information for problem diagnosis. Includes the output of ddcutil environment --verbose andfor each detected monitor,  the output of ddcutil capabilities --verbose and ddcutil probe --verbose.

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.  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 use this  extended range.

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

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

-t,  --terse,  --brief

Show brief detail.  For command getvcp, the output is in machine readable form.

-v,  --verbose

Show extended detail

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

--mccs  MCCS version

Tailor vcpinfo output to a particular MCCS version, e.g. 2.1

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.

Options to tune execution:

--maxtries (max-read-tries, max-write-read-tries, max-multi-part-tries)

Adjust the number of retries

--force-slave-address

Take control of slave addresses on the I2C bus even they are in use.

--verify | --noverify

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

--async

If there are multiple monitors, initial checks are performed in multiple threads, improving performance.

Options for program information.

-h,--help

Show program help.

-V,  --version

Show program version.

Execution Environment

Requires read/write access to /dev/i2c devices.  See http://www.ddcutil.com/i2c_permissions

Nvidia Proprietary Driver

Some Nvidia cards using the proprietary Nvidia driver require special settings to properly enable I2C support.  If you are using this driver and ddccutil does not  work with your Nvidia card, you can try the following:

Copy file /usr/share/ddcutil/data/90-nvidia-i2c.conf to directory /etc/X11/xorg.conf.d:

sudo cp /usr/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.

(The above instructions assume that the normal location of the ddcutil data directory.  YMMV.)

For further discussion of Nvidia driver settings, see http://www.ddcutil.com/nvidia.

Virtual Machines

Virtualized video drivers in VMWare and VirtualBox do not provide I2C emulation.  Use of normal video drivers with PCI passthrough  is possible.

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-2020 Sanford Rockowitz

Info

2020-05-15