DDF cheat sheet

Precedence of DDF files

All DDF coming with deCONZ typically reside in /usr/share/deCONZ/devices/generic/ on a Linux system and are loaded first. However, files residing in the home directory of the user running deCONZ (e.g. /home/deconzuser/.local/share/dresden-elektronik/deCONZ/devices) will override the pre-packaged files to allow users to amend and keep their own files if desired.
As the feature is still beta, DDF are disabled by defaut at deconz restart for the moment.

DDF are enabled in Panels / Control. After that just select a node then right click and "Edit DDF", some of them can be pre-filled.

Usage of DDF editor

Items panel

Device (on top of the left scrollable area)

Status

When you want to make a DDF for an already supported device which doesn't have a DDF or start a new one for anything unsupported, the status is per default set to Draft. This means that deCONZ does not consider it for any processing yet. In order to put it into effect, set the status to anything else.

Sleeper

What might be important for a device in general is to know if it is a sleeper or not. Mains powered devices are not concerned by this (there might be some hybrid exceptions), but battery powered sensors. In order to find out, select the basic cluster for a device and double click on the number right of its name (this directly shows the available attributes in the cluster info panel). Then select attribute 0x0005 (Model Identifier), double click on its value and press, read button (not read config) and observe the dot left to the battery icon. If it doesn't blink green in about 10 seconds, reading the attribute has failed being a good indication for the device being a sleeper. To get a higher confidence, you might want to try this with some other clusters/attributes of interest.

Basic cluster Identification

Used to recognize the device, you need to use exactly the same value than in the basics cluster attributes table, can use drag&drop to copy values.

Device type (on top of the left scrollable area in grey)

Need to be dragged first from the "available items" windows

Attributes (on top of the left scrollable area in purple)

Will be filled automaticaly during the device type setting, and you can add/edit/remove them.

States (in green) and Configs (in blue).

Will be filled automaticaly, and you can add/edit/remove them, still using drag&drop.

Read/write/parse functions

Defaults

Defaults for the resource items are to be found in the respective item file in /usr/share/deCONZ/devices/generic/items, if any. E.g.: the resource item attr/modelid has a default parsing stanza. In that case, it is sufficient to have the below in the DDF for handling the model ID. Of course, the defaults can be overwritten for almost every resource item.

{
    "name": "attr/modelid"
},

Endpoint

Try to use the good endpoint instead of "auto".

Scripts/Expressions

The above mentioned resource item files also contain a corresponding Script or Expression in case a function stanza is defined. If you wish or need to change the data processing, there're various deCONZ objects and methods which can be used. Taken from device_js.h:

    # Javascript API

    This API can be used in expressions in "parse" and "write" functions.
    Beside this anything can be used what is supported by QJSEngine.

    If a expression/script is too long to write it in the DDF file it could saved in an external
    file and referenced as "file://<path>/some-script.js" instead of an JS expression string.
    The file path is relative to the DDF file directory.

    ## Global objects accessible in evaluate() call

    Following globals are scoped to the surrounding item object in the DDF

    R        – access related Resource (Device | Sensor | LightNode)
    Item     — acces related ResourceItem
    Attr     — acces parsed deCONZ::ZclAttribute (if available in "parse")
    ZclFrame — access parsed deCONZ::ZclFrame (if available in "parse)

    ### Object Methods

    R.item(suffix) -> gets Item object, for example the 'config.offset'
    Item.val       -> ResourceItem value (read/write)
    Item.name      -> ResourceItem name like 'state/on' (read only)
    Attr.id        -> attribute id (number, read only)
    Attr.dataType  -> attribute datatype (number, read only)
    Attr.val       -> attribute value (read only)

    ZclFrame.cmd           -> ZCL command (read only)
    ZclFrame.payloadSize   -> ZCL payload size (read only)
    ZclFrame.isClCmd       -> cluster command (read only, 2.13.03?)
    ZclFrame.at(x)         -> value at position x (read only)

    ### under consideration (not implemented)
    R.parent --> get the parent resource object (Device)
    R.subDevice(uniqueId) --> get another sub-device resource object
    Item.lastSet --> timestamp when item was last set
    Item.lastChanged --> timestamp when item was last changed
    ZclFrame.attr(id) --> Attr object (if the ZclFrame has multiple)


    Example expressions:

    "parse"

        Item.val = Attr.val + R.item('config/offset').val
        Item.val = Attr.val
        Item.val = Attr.val << 16

    "write"

        let out = -1;
        if (Item.val === 'heat') out = 2;
        else if (Item.val === 'cool') out = 0;
        out; // becomes the result of the expression

Bindings panel

Adding bindings is a convenient drag&drop experience. From the device of interest, drag the cluster of interest to the left area and drop it. This adds the cluster to the list. For the attribute of interest, drag the respective attribute but this time drop it in the middle area. Thiss adds the attribute to the list. Then configure the attribute with the values of choice and repeat the steps where necessary.