ddcutil

Announcements

05 March 2017

Release 0.7.3 is a maintenance release. There is no need to install it unless you are experiencing problems.

This release introduces the following features:

  • Command ddcutil detect --verbose shows additional information.
  • Command ddcutil environment --verbose implements additional diagnostic tests.
  • configure option --enable-drm controls whether DRM is used to enhance the diagnostics of command ddcutil environment --verbose. If enable-drm=yes, package libdrm-dev or libdrm-devel (depending on Linux distribution) must be installed to build ddcutil. Setting --enable-drm=no affects only diagnostic output, not normal execution.

For a complete list of changes and bug fixes, see Release Notes. Prior annoucnements can be found here.

01 Febrary 2017

Release 0.7.2 fixes a critical bug in release 0.7.1 where insufficient privileges on a /dev/i2c-n device causes program termination. Additionally there are minor improvements to diagnostic output.

For a complete list of changes and bug fixes, see Release Notes. Prior annoucnements can be found here.

27 January 2017

Release 0.7.1 is a maintenance release. There is no need to install it unless you are experiencing problems.

This release introduces the following features:

  • Command option --force-slave-address causes ddcutil to attempt to take control of slave addresses on the I2C bus even if they are in use by another driver. This may aid in certain situations where monitors on an I2C bus are not properly detected. See Instrumentation and Tuning)

For a complete list of changes and bug fixes, see Release Notes. Prior annoucnements can be found here.

Introduction

ddcutil is a Linux program for querying and changing monitor settings, such as brightness and color levels.

ddcutil primarily uses DDC/CI (Display Data Channel Command Interface) to communicate with monitors implementing MCCS (Monitor Control Command Set) over I2C. Normally, the video driver for the monitor exposes the I2C channel as devices named /dev/i2c-n. Alternatively, there is support for monitors (such as Eizo ColorEdge displays) that implement MCCS using a USB connection. See USB Connected Monitors.

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.

Restrictions:
-ddcutil does not support laptop displays, which are controlled using a special API, not I2C.
- Nvidia's proprietary video driver may require special configuration. See Special Nvidia Driver Settings.
- Operation with AMD's proprietary video driver fglrx requires a specially built version of ddcutil. See Building with ADL Support.
- Reading and writing Table type features is implemented but untested. See Table Features

Command Overview

ddcutil is a command line program. (A GUI user interface is planned.) ddcutil implements the following subcommands:

Subcommand Function
detect report monitors detected
capabilities report a monitor's capabilities string
vcpinfo (feature-code-or-group) list VCP features codes that ddcutil knows how to interpret
getvcp feature-code-or-group report a single VCP feature value, or a group of values
setvcp feature-code new-value set a single VCP feature value
dumpvcp filename save color related VCP feature values to a file
loadvcp filename restore color related VCP feature values from a file
environment explore the ddcutil installation environment (other than USB)
usbenv explore USB aspects of the ddcutil installation environment
probe explore the capabilities string and probe the features of a single monitor
interrogate collect maximal information for problem diagnosis
chkusbmon /dev/hiddevN used by udev rules to test if a USB device represents a monitor

There is an extensive set of options for tailoring ddcutil operation. Some are described in this documentation. For a full list of options and detailed documentation for each command, use the --help option or see the man page:

$ ddcutil --help
$ man 1 ddcutil

Monitor Selection

If more than one monitor is attached, the desired monitor can be specified using any of the following options:

--display <display number>
--bus <i2c bus number>
--adl <iAdapterNumber>.<iDisplayNumber>
--usb <usb bus number>.<usb device number>
--edid <256 character hex string>
--mfg <mfg code> --model <model name> and/or --sn <serial number>

Notes:
- Monitors under control of AMD's proprietary driver (fglrx) are selected by adapter number and display number. These numbers are specified on the --adl option separated by a period, e.g. "--adlno 1.0"
- Any combination of manufacturer code, model name and serial number can be used together to identify a monitor. The first monitor to satisfy all the specified criteria is selected. (This behavior differs from releases prior to 0.7 where model name and serial number had to be specified together.)

To see a list of all attached monitors and their associated identifiers:

$ ddcutil detect

Examples

Installing ddcutil From Prebuilt Packages

Packages for recent Debian, Fedoray, openSUSE, and Ubuntu releases are available for download from the openSUSE Build Service. Unfortunately, there's not one clean link for downloading OBS packages, so here are several.
- Add repository and download package ddcutil. This is all you will need if just installing the command line version of ddcutil.
- All ddcutil packages Packages for both the command line and shared library version of ddcutil. Note that the development package is named libddcutil-devel on RPM based distributions (SUSE, Fedora) and libddcutil-dev on dpkg based distributions (Debian, Ubuntu).
- File system view

For Ubuntu xenial, there's a PPA. To use it, add the following lines to /etc/apt/sources.list:

deb http://ppa.launchpad.net/rockowitz/ddcutil/ubuntu xenial main 
deb-src http://ppa.launchpad.net/rockowitz/ddcutil/ubuntu xenial main 

For other distributions, or if using AMD's proprietary fglrx driver, ddcutil must be built from source.

ddcutil Configuration

DDC/CI communication must be enabled on the monitor. This setting can only be changed using the monitor's on screen display.

ddcutil users require write permission to /dev/i2c-* devices. See /dev/i2c Permissions

If using an open source video driver, kernel module i2c-dev must be loaded. See Kernel Module Configuration

If using Nvidia's proprietary video driver, special settings may be necessary. See Special Nvidia Driver Settings

Installation Diagnostics

If ddcutil installs successfully but execution fails, command ddcutil environment can be used to probe the I2C environment and may provide clues as to the problem. For USB connected monitors, use command ddcutil usbenvironment.

Additional Topics

Author

Sanford Rockowitz rockowitz@minsoft.com