DDF cheat sheet
All DDF provided directly 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.
More details about the DDF format and its processing can be found at:
https://dresden-elektronik.github.io/deconz-dev-doc/modules/ddf
There is a video too DDF description on deconz
And for reminder (extract from deconz documentation Deconz documentation ):
The items pane is the default view of the DDF editor and allows you to define exposure of a device via deCONZ REST API.
On the left-hand side, some general information regarding the associated device can be entered. Furthermore, you can see/define which light and sensor resources are created as well as the respective resource items for those. It depends if anything is shown at all for a particular device. Previously supported devices via legacy code should reflect the current state implementation (items available, but window title displays "untitled"), which must not necessarily be complete due to incomplete testing or insufficient information. Already supported devices via DDF also offer items and can be recognized as such by representing the respective JSON filename in the window title. Currently unsupported devices can be identified by either the respective node having a hex name (e.g. 0xA3E1) and/or just having the device item available.
| Content | Description |
|---|---|
 |
General, device specific information. See "Edit device area (middle)" for an overview of the associated options/fields. WIP |
 |
See "Edit subdevice area (middle)" for an overview of the associated options/fields. WIP |
 |
See "Edit resource item area (middle)" for an overview of the associated options/fields. WIP |
The right-hand side gives you a selection of all predefined light and sensor resources (colored in grey) as well as all available resource items. The aforementioned resources comprise a preselection of resource items based on experience, which should fit a device most of the time. However, selecting one and subsequently adding or removing predetermined resource items is always possible giving you a vast amount of freedom.
| Content | Description |
|---|---|
 |
States (in green) and Configs (in blue). WIP |
In the middle, the individual items chosen on the left side can be configured.
| Field/Option | Description |
|---|---|
| Status | Available options: Draft (default), Broze, Silver, Gold When you want to make a DDF for an already supported device which doesn't have a DDF or start a new one for any unsupported device, the status is per default set to Draft. Any Draft DDFs are not considered further for any processing by deCONZ. In order to put it into effect, set the status to anything else. However, as of now, any DDF in status Gold will automatically be put active upon start. Bronze and Silver status DDFs must explicitly be enabled prior to usage in the Control panel. Select Panels -> Control in deCONZ GUI to have the respective panel show up at the left bottom, then make your choice. |
| Manufacturer name | This must be the values obtained from Attribute 0x0004 of the Basic cluster (see sleeper). You need to use exactly the same value and it is recommended to either copy&paste or drag&drop it. |
| Model ID | This must be the values obtained from Attribute 0x0005 of the Basic cluster (see sleeper). You need to use exactly the same value and it is recommended to either copy&paste or drag&drop it. |
| Vendor | This should represent the vendor as stated on the packaging (e.g. SilverCrest). |
| Product | This should represent the product identifier as given on the packaging (e.g.) as well as the device category. Please refer to Supported DDF devices for examples. |
| 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. |
TODO
| Content | Description |
|---|---|
| Type | WIP |
| Unique ID template | States (in green) and Configs (in blue). WIP
|
TODO
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.
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
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 to add the attribute to the list. Lastly, configure the attribute with the values of choice and repeat the steps where necessary.
