ddcutil(1)

📦
version 3.0.2 · 8 versions
, in arch rolling, fedora 44, ubuntu stonking

🎀 ddcutil(1) 🎀 — the general commands manual, but make it bestie-coded

🌸 NAME 🌸

ddcutil — query and change monitor settings 💅

✨ SYNOPSIS ✨

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

and the ICONIC part: options can be written either before or after the command and its arguments. no rules, just vibes 🫶

💖 DESCRIPTION 💖

okay so here's the tea, bestie: ddcutil is what you use to query and change monitor settings. and like — which settings? generally speaking, the ones you could already fiddle with using the buttons on your monitor and its on screen display. but the exact list? literally varies from monitor to monitor, it's giving "every monitor is a unique little main character" 😭

ddcutil talks to monitors that implement the Monitor Control Command Set (MCCS) using the DDC/CI protocol on an I2C bus. normally your video driver exposes that I2C bus as devices named /dev/i2c-n. alternatively, ddcutil can talk to monitors that use USB to communicate MMCS, as long as those monitors meet the USB Monitor Control Class Specification ✨

now, the Monitor Control Command Set describes a whole collection of Virtual Control Panel (VCP) features that a monitor can implement. each feature gets identified by a single byte. for example, feature x10 is the brightness control. iconic numbering, no notes 💅

common use cases? changing monitor brightness and color, obviously. and with scripts you can make those changes happen from keystrokes, or in response to the time of day — yes, your monitor can be a whole mood ring 🌈 another super common one: switching the monitor input source.

but there's a more complex use case that's lowkey kinda gorgeous: using ddcutil as part of color profile management. see, monitor calibration is relative to the monitor color settings currently in effect — e.g. red gain. so ddcutil lets you save color related settings at the moment a monitor is calibrated, and then restore them when the calibration is applied. perfection 😌✨

this man page describes the ddcutil commands and options most important to the typical user. for complete documentation, use the --help option or go see the web site http://www.ddcutil.com. and if option --verbose is specified in conjunction with --help, you get more extensive help on option arguments — the deluxe version, we love her 👑

option --hh shows all options recognized by ddcutil. and when we say all, we mean: deprecated option names (the ones that got replaced by more descriptive names), experimental options, and options only of interest to developers. the whole vault, unlocked 🔓👑

🚫 RESTRICTIONS 🚫

ddcutil does not support laptop monitors, because they do not implement DDC/CI. sorry babes, that's just not our lane 💀

💜 COMMANDS 💜

🌟 Primary Commands 🌟

these are the most used ddcutil commands. the everyday slays.

  • detect — find monitors that have a Virtual Control Panel 🔍
  • vcpinfo [ feature-code | feature-group ] — describe VCP feature codes, as defined in the MCCS specification. use option --verbose to see values for Non-Continuous features 👀
  • capabilities — query the monitor's capabilities string
  • getvcp [ feature-code | feature-group ] ... — report a VCP feature value, or a group of feature values. more than one feature code can be specified. however — and this is important — feature codes and groups cannot be combined 🙅
  • setvcp feature-code [+|-] new-value ... — set a VCP feature value. if + or - is specified, it must be surrounded by blanks, and it indicates a relative value change of a continuous VCP feature. and yes you can specify multiple feature/value pairs (with or without [+|1]) in one go. go off ✨

🦋 Secondary Commands 🦋

these ones handle special situations. the niche queens.

  • 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 the values get applied to is determined by the monitor identification stored in the file. if a monitor is specified on the command line, it must identify the same monitor as determined from the values in the file. and if the monitor is not attached? nothing happens. literally nothing. we simply do not proceed 💀
  • scs — issue DDC/CI Save Current Settings request. heads up: most monitors do not implement this command. a few require it for values changed by setvcp to take effect. so it's giving "rare, but occasionally the main character" 🙈
  • chkusbmon — tests if a hiddev device may be a USB connected monitor, for use in udev rules
  • discard all|capabilities|dsa cache[s] — discard cached files used for performance improvement. clear the cache, clear the mind 🧹✨
  • traceable-functions — lists functions that can be specifically traced using an option like --trcfunc or --trcfrom
  • noop — do not execute a command. just process options. sometimes you just wanna be perceived and do nothing, and honestly? valid 🙈

🔎 Diagnostic commands 🔎

these commands diagnose issues in the system configuration that affect ddcutil operation, and that gather information for remote problem diagnosis. detective mode, activated 🕵️♀️

  • 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. this includes the output of ddcutil environment --verbose for each detected monitor, the output of ddcutil capabilities --verbose and ddcutil probe --verbose. it's the full dossier, no crumbs left behind 👑

🍓 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

here 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 to 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. but more generally? bestie, it's actually a two byte value, i.e. x00..xffff, and a few features on some monitors use this extended range. shocking, I know 😳

and we are SO not done here, keep reading for the rest 💜

👑 OPTIONS ✨

okay bestie, buckle up, this is the big one. 💅 Everything below is a flag you can slap on your ddcutil command. Grouped all cute by vibe.

🌸 Options that control the amount and form of output

  • -t, --terse, --brief — show the short version. For command getvcp, the output comes out machine readable, iykyk. 🤖
  • -v, --verbose — show the extended version, the whole lore. ✨

💜 Options for program information

  • -V, --version — show the program version. yes queen, identify yourself. 👑
  • --settings — report the option settings currently in effect.
  • -h, --help — show program help. 🫶
  • --hh — show program help including hidden options. And bestie, "hidden" here means: alternative option names, experimental and deprecated options, and the debugging ones. peek behind the curtain. 🫣

🦋 Options for monitor selection

fr fr, if you don't name any of these, the default is just the first detected monitor. And PS — --mfg, --model and --sn can be specified together. combo move. 💫

  • -d, --dis, --display display-number — the logical display number (starting from 1).
  • -b, --bus bus-number — the I2C bus number.
  • --hiddev device-number — the hiddev device number.
  • -u, --usb busnum.devicenum — the USB bus and device numbers.
  • -g, --mfg 3-letter-code — the 3 letter manufacturer code.
  • -l, --model model-name — the model name.
  • -n, --sn serial-number — the serial number. (heads up, this is the "serial ascii" field from the EDID, NOT the binary serial number. very much not the same thing.)
  • -e, --edid 256-hex-chars — the 256 hex character representation of the 128 byte EDID. needless to say, this one is intended for program use, not for your eyeballs. 🙈

🎀 Feature selection filters

  • -U, --show-unsupported — normally, getvcp does NOT report unsupported features when you query a feature-group. This option forces that output anyway. no gatekeeping. 🚪
  • --show-table | --no-table — normally, getvcp does not report Table type features when querying a feature-group. --show-table forces the 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 for diagnostic output

  • --ddcdata — reports DDC protocol errors. these may reflect I2C bus errors, or monitors being dramatic and deviating from the MCCS specification. formerly named --ddc.
  • --stats [all|errors|tries|calls|elapsed|time] — report execution statistics. lowkey important: I2C bus communication is inherently unreliable, and it's the responsibility of the program using the bus (that's ddcutil, bestie) to manage retries when things fail. 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. And 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. we're going deeper. 🔍
  • --syslog [debug|verbose|info|notice|warn|error|never] — write messages of the specified severity level or more urgent to the system log. The ddcutil default is WARN. The libddcutilP default is NOTICE.

💫 Options that tune execution

  • --enable-capabilities-cache, --disable-capabilities-cache — enable or disable caching of capabilities strings, which improves 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 so it never adjusts the sleep multiplier below this value. This option can help dampen swings in sleep multiplier values. calm the algorithm down. 🧘
  • --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, the newer option --enable-dynamic-sleep will provide better performance. (bestie, read that again: newer one is the move.)
  • --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. improves display detection performance. living on faith, honestly. 🙏
  • --discard-cache [capabilities|dsa|all] — discard cached display information and/or dynamic sleep data. bye bye cache 💀

🍓 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. (yep, those exact values. don't get cute with it.)
  • --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. not today, device. 🚫
  • --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. The Nvidia proprietary driver is built in a way such that the ioctl interface can fail, in which case ddcutil switches to using the file io interface. (it has a backup plan. queen behavior. 💅)
  • --force-slave-address — take control of slave addresses on the I2C bus even if 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 instances 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 the DDC packet, instead of the normal value. This option has been found to enable access to some control functions when using some displays, particularly from LG. 👀
  • --permit-unknown-feature — allow setvcp of unknown features. (yes, exactly what it sounds like. proceed thoughtfully.)
  • --ignore-mmid monitor-model-id — ignore monitors with this monitor-model-id. To see the monitor-model-id for a display, use command ddcutil --verbose.
  • --noconfig — do not process the configuration file.

🖥️ NVIDIA PROPRIETARY DRIVER

Some Nvidia cards using the proprietary Nvidia driver require special settings to properly enable I2C support. See http://www.ddcutil.com/nvidia. (yes, go read it, it's giving Important.)

🧚 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

the moment you've all been waiting for. actual receipts. 🔥

ddcutil detect

Identify all attached monitors. hi bestie, who are you 👋

ddcutil getvcp all

Show all settings that the default monitor supports and that ddcutil understands.

ddcutil 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. this one is the info dump of all info dumps. 💾

💀 DIAGNOSTICS

  • Returns 0 on success, 1 on failure.
  • Requesting help is regarded as success. (asking for help is always a slay, periodt.)

🌈 SEE ALSO

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

💖 AUTHOR

Sanford Rockowitz (rockowitz at minsoft dot com)

Copyright 2015-2023 Sanford Rockowitz

and that's the whole page bestie!! 🎀 this was ddcutil(1), source/version and dated 2024-01-11 — go forth and control your monitors, you absolute icon. no cap, you ate. 💅✨🦋

📦 where this page comes from