-
Notifications
You must be signed in to change notification settings - Fork 496
DDF cheat sheet
All DDF provided directly with deCONZ typically reside in /usr/share/deCONZ/devices/
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 ):
As simple as that: Select a node in deCONZ GUI with a left-click (this is important). Then right-click on the node to bring up the context menu as below, now select Edit DDF.
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. |
![]() |
This allows you to adjust the device type and the unique ID of a subdevice/resource. See Edit subdevice area (middle) for an overview of the associated options/fields. |
![]() |
This allows you to to configure the individual resource items exposed via REST API. Basically, this determines what is done on reception of data and/or what is written to the device. See Edit resource item area (middle) for an overview of the associated options/fields. |
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. |
In the middle, the individual items chosen on the left side can be configured.
Content | Description |
---|---|
Type | This determines the current type of a subdevices. Generally, there is a distinction between light and sensor subdevices or resources. Note that sensor resources always begin with "ZHA" whereas light resources do not (see also Available items area (right)). Another characteristic worth to mention is that whatever device type a vendor has defined for an endpoint can be overwritten to what is getting chosen in the DDF. So, when the vendor chose the device type for an endpoint is "On/off light" for something which is actually a cover controller, you can just use "Window covering device" to have it appear as such in the REST API. |
Unique ID template | This is the unique identified given for a subdevice. It typically consists of the MAC address (represented by $address.ext), followed by the associated zigbee endpoint (as hex value) and optionally, for sensor resources/subdevices, the associated zigbee cluster (as hex value). In case a subdevice/resource does not occur in the REST API, it is recommended to check if the endpoint is set correctly. E.g., a value of "0xFF" is invalid and must be corrected. |
In the middle, the individual items chosen on the left side can be configured.
Content | Description |
---|---|
Description | A description on what the resource item is intended for or what it is supposed to represent. |
Public item | This setting determines if the selected resource item is exposed via REST API or not. This is typically set to true. In some cases, this setting is not available meaning it is not supposed to be touched by the user. |
Awake on receive | This setting is important for deCONZ, as it determines if anything can be written to or read from the device. It applies for battery powered sensors and should answer the question, if the device can further interacted with if it sends anything on its own. However, it is admittedly challenging for a user and even for developers unless a zigbee sniffer is involved. In some cases, this setting is not available meaning it is not supposed to be touched by the user. |
Static default value | The value entered here will be persistent, no matter what happens and therefore will not change in the REST API. In some cases, this setting is not available meaning it is not supposed to be touched by the user. |
Default value | This is the value a resource item assumes, typically after the device has been paired and before any data has been received. In some cases, this setting is not available meaning it is not supposed to be touched by the user. |
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.
Home Remember : Not all devices listed here are supported by deconz.