ddccontrol-scanmonitor - Man Page

generate a monitor database XML file

Synopsis

ddccontrol-scanmonitor [dev:/dev/i2c-N] [--output FILE] [--db-path DIR]
ddccontrol-scanmonitor --list

Description

ddccontrol-scanmonitor creates an editable XML file for the ddccontrol monitor database from a connected DDC/CI monitor. With no device argument, it selects the only detected monitor automatically or asks which monitor to scan when several are available. For unattended use with several monitors, specify a device explicitly.

The scanner always accesses /dev/i2c-* directly, with no environment variable needed. Read and write permission on the device is required; use sudo ddccontrol-scanmonitor if necessary. It reads EDID, capabilities and supported controls without changing control values.

The generated XML enables known controls whose values could be read. Uncertain controls are left commented out for manual testing. Control and value definitions come from the database's options.xml. Some monitor quirks, special initialization and unadvertised controls still need manual edits.

By default the output is named after the monitor's PnP ID, for example DEL1234.xml, in the current directory. Existing files are never overwritten.

Options

dev:/dev/i2c-N

Scan this device instead of choosing from detected monitors.

--list

List detected DDC/CI monitors and their device paths, then exit without writing XML.

-o,  --output FILE

Write XML to this file. The file must not already exist.

-b,  --db-path DIR

Read control definitions from DIR/options.xml. By default, use the database location configured at build time, usually /usr/share/ddccontrol-db or /usr/local/share/ddccontrol-db. Use the same database with the preview application's -b option.

-h,  --help

Show usage information.

-V,  --version

Show the program version.

Examples

Create an XML file interactively:

ddccontrol-scanmonitor

Choose a monitor and output path explicitly:

ddccontrol-scanmonitor dev:/dev/i2c-4 --output ./DEL1234.xml

Try the generated file directly (replace the filename with your monitor's ID):

DDCCONTROL_NO_DAEMON=1 gddccontrol --monitor-file ./DEL1234.xml
DDCCONTROL_NO_DAEMON=1 ddccontrol --monitor-file ./DEL1234.xml

Keep the filename PNPID.xml and relaunch the application after editing it. No system database changes or service restart are needed for this preview. Loading a local file requires DDCCONTROL_NO_DAEMON=1 and permission to access the I2C device directly. If needed, prefix the command with sudo env.

Install a tested result into a typical package database and reload the service:

sudo cp -i DEL1234.xml /usr/share/ddccontrol-db/monitor/DEL1234.xml
sudo systemctl restart ddccontrol.service

Use the database path printed by the scanner for your installation. Test the enabled controls with gddccontrol(1) or ddccontrol(1), edit the XML as needed, and relaunch with --monitor-file after each change. Submit the tested file in a pull request to the ddccontrol-db repository.

Exit Status

Zero indicates success. A nonzero exit status indicates invalid arguments, discovery or communication failure, an invalid database, or an output error.

See Also

ddccontrol(1), gddccontrol(1)

Monitor database contribution guide:
https://github.com/ddccontrol/ddccontrol-db/blob/master/doc/how-to-add-a-monitor.md

Info

September 22, 2026