User Defined Features

ddcutil contains a preliminary implementation of User Defined Features. This section describes the current implementation in git development branch 1.0.0-dev. User Defined Features is enabled or disabled using command line options --udf or --noudef. The default is currently --noudf.

The user defined features for a monitor are specified in a feature definition file. The format of this file is subject to change.

User Defined Feature File

Here's an example of a file that specifies user defined features.

$ cat ~/.local/share/ddcutil/DEL-DELL_U2222-16485.mccs
MFG_ID       DEL
MODEL        DELL U2222
PRODUCT_CODE 16485
MCCS_VERSION 2.2
FEATURE_CODE FD  Feature Name
    ATTRS NC RW
    VALUE 0 First Val
    VALUE 0X01 Second Val 0x
    VALUE X02  Third value X
    VALUE 03H  H at end
FEATURE_CODE xFB Another Feature
    ATTRS C RO
FEATURE_CODE 0xfa a feature with code staring with 0x
    ATTRS C RO 

The first 3 lines identify the monitor model, using a 3 character manufacturer id, the model name, and the product number, as given in the EDID. The feature definition applies to any monitor that matches those identifiers. Model name and product number are both required because some manufacturers use generic model names, and many set the product number to 0. For example, Samsung commonly uses the name "SyncMaster", and LG commonly uses the name "LG ULTRAWIDE".

These three fields are also are used to create the file name of the feature description, which has the form <mfg_id>-<model name>-<product code>.mccs. The values in the file name must match those in the file.

The optional MCCS_VERSION line specifies the version of the MCCS Specification used to describe the monitor. If specified, it is used instead of the value returned by querying VCP feature xDF (VCP Version). If the MCCS version is also specified using the --mccs command line option, the command line option takes precedence.

In addition to the monitor identification lines and optional MCCS version line, there are one or more feature definitions.

Each defnition starts with a line of the form FEATURE_CODE <feature-id> <feature name>. Feature codes are implicitly hex numbers, and can be written with or without a leading "x".

The ATTRS line contains feature attributes: "C" or "NC" indicating whether the feature is continuous or non-continuous, and "RW", "RO", or "WO" indicating whether the feature is read-write, read-only, or write-only.

For non-continuous features, there are one or more VALUE lines describing the possible values. Each line has the form: VALUE <value> <description>. Feature values can be written either as decimal or hexadecimal.

The MCCS specification has evoloved include features that don't neatly conform the original Continous/Non-Continuous classification. For example, continous features can have special reserved values, and non-continuous features exist that do not have simple tables of feature values, but instead have unique interpretations. The User Defined Feature facility cannont define such features.

Blank lines and lines beginning with "*" or "#" are ignored.

Examples

An actual feature definition file for a monitor whose values for feature x60 (Input Source) do not conform to the MCCS specification.

$ cat ~/.local/share/ddcutil/SAM-U32H75x-3586.mccs
MFG_ID       SAM
MODEL        U32H75x
PRODUCT_CODE 3586
MCCS_VERSION 2.1
FEATURE_CODE 60 Input Source
  ATTRS NC RW
  VALUE x05 HDMI-1
  VALUE x06 HDMI-2
  VALUE x0f DisplayPort

Feature Definition Search Path

Feature definition files are saved in the user's ddcutil data directory, $HOME/.local/share/ddcutil. More generally, ddcutil searches for feature definition files using environment variables $XDG_DATA_HOME and $XDG_DATA_DIRS, per the XDG Base Directory Specification.