Ubuntu Manpage: ddcutil - Query and change monitor settings

NAME

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

The monitor 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
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 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 in $HOME/.local/share/ddcutil,

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 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 that modify behavior
--mccs MCCS version
Tailor command input and output to a particular MCCS version, e.g. 2.1
--enable-usb, --disable-usb
Enable or disable support for monitors that implement USB commuincation with the
Virtual Control Panel. The default is --disable-usb
--enable-udf, --disable-udf
Enable or disable support for user supplied feature definitions. The default is
--enable-udf
enable-capabilities-cache, --disable-capabilities-cache
Enable or disable caching of capabilities strings, improving performance. The
default is --enable-capabilities-cache
--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.
--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.

Options to tune execution:
--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.
--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 work better
with sleep-multiplier values greater than 1.0.

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.

Debugging options.
--trace trace group name
Enable tracing for functions in the specified trace group. For a list of trace
group names, use the --help option. This option can be specified more than once.
--trcfunc function name
Trace the specified function, which must have been enabled for tracing. This
option can be specified more than once.
--trcfile file name
Trace all functions in a source file that are enabled for tracing. The argument is
a simple file name, with or without the ".c" suffix, e.g. "i2c_bus_core",
"i2c_bus_core.c". This option can be specified more than once.
--timestamp, --ts
Preface trace messages with the time since program start. --thread-id,--tid
Preface trace messages with the thread number.
excp Report freed exceptions

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.

AUTHOR

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

                                            2020-05-15                                 ddcutil(1)