Device Description Files (DDF)

Work in progress


This page serves as a Request For Comments (RFC). This API is not yet available in a release.

The /ddf endpoint provides query and management calls for DDF bundles.

DDF bundles

A DDF bundle is a single self contained immutable file which embeds the DDF JSON and all dependencies like scripts and other files, see: specification.

Problems with plain DDF JSON files

While DDF system improved the C++ mess, it still has the same issues which can also be found in ZHA and Zigbee2Mqtt device integrations:

  • Global updates bound to a deCONZ release. When a new release comes out, it’s all or nothing every device gets the newest DDF JSON but also its dependencies like scripts, which may be used and changed for other devices, introducing unforseen bugs.
  • When something breaks, and this happens, perhaps since a script or DDF JSON was updated, there is no way back, other than downgrading of deCONZ.
  • Distributing new DDF files is cumbersome, and when external scripts are referenced even more so.
  • Users have to wait for new deCONZ releases for latest official DDFs updates.

What DDF bundles solve

  • Easy exchange during development, just send the DDF bundle to a user.
  • Decoupling from deCONZ releases.
  • Support for multiple versions for a bundle, e.g. run a new beta version only on one test device.
  • Support switching between bundle versions for a device, e.g. if v1.0.1 doesn’t work user can switch back to v1.0.0.
  • Bundles are immutable and signed, this drastically reduces the chance of breaking a device integration.
  • A bundle can’t break another one, even if it’s using the same external dependencies.

From a users perspective there won’t be all or nothing updates dependend on a deCONZ version. Instead DDF updates are explicit like this simplified UI:

DDF update available for “Kitchen motion sensor” (model id: SML003).
Currently installed version: v1.2.1
Update to version v1.2.5? (yes/no/all)


Currently this page only describes how to query bundle information and upload bundles. To actually assign/pin DDF bundles to a device uniqueid, the /devices endpoint needs to be extended.

DDF bundle pinning

  • Initial behaviour when a device is joined it is automatically be assigned to a suitable bundle, with priority on the newest bundle that is signed with a “stable” signature and if not found the latest “beta” or unsigned bundle.
  • Manual update Once a device is pinned to a bundle, updating to a new DDF bundle version needs to be done explicitly. Like PUT /api/<apikey>/devices/<uniqueid>/usebundle/<sha256>, where the bundle with SHA-256 hash itself was Uploaded before.
  • Auto updates are enabled for latest_prefer_stable and latest policies. Each deCONZ release does contain the latest official beta and stable signed DDF bundles. These can also be updated by loading fresh ones from the DDF store which doesn’t depend on a deCONZ release.

Bundles are assigned according to a policy which is given as a per device attr/ddf_policy item.

Policy Description
latest_prefer_stable (default) Use latest DDF bundle: beta signed one if no stable available.
latest Use latest DDF bundle either beta or stable signed.
pin Use and stay on bundle given by <sha256-hash>.
raw_json For development like before bundles existed just use raw .json DDF files.

Get all DDF bundle descriptors 

GET /api/<apikey>/ddf/descriptors[?next=<token>]

Returns the descriptors of all available DDF bundles.


next — The token returned from the last request to query the next descriptors. The first and the last request doesn’t specify the token. The response uses pagination and only returns max. N records since in future many thousands of bundles may exist.


HTTP/1.1 200 OK

  "377955a530cb7b35917021a47aca7f7ee13fc4d89ecf969da29098f77ad75c1a": {
    "uuid": "b5b20dff-da08-45f9-b9b6-4f430ccd9ed4",
    "product": "Aqara Vibration Sensor DJT11LM",
    "version_deconz": ">2.27.0",
    "last_modified": "2023-02-02T13:35:59.000Z",
    "device_identifiers": [
    "file_hash": "929df9c00f39bd01aea2278b624bfddac03b7dd5aa06ee1e97f9811cc2f6abc5"
  "next": 42

Response fields

The keys in the returned object are the SHA-256 hashes of the immutable data in the DDF bundles (hash over DDFB section). The file_hash is the SHA-256 hash of the complete DDF bundle file.

The next key is returned for any but the last response, and if present needs to be specified for the following request to gather the next records.


The next key is an opaque value and likely NOT be incrementally plus 1. Thus the first response may return "next": 24 and the second "next": 63.

See Get DDF bundle descriptor for a full description of the attributes.

Possible errors

403 Forbidden

Get DDF bundle 

GET /api/<apikey>/ddf/bundles/<sha256-hash>




The full DDF bundle as <sha25-hash>.ddf file.

Possible errors

403 Forbidden

404 Not Found

Upload DDF bundle 

POST /api/<apikey>/ddf/bundles

Uploads a DDF bundle so it can be used by DDF system.


The DDF bundle is uploaded as multipart/form-data, which is used by HTML form input elements with type="file" (see: MSDN).

Example request data

POST /api/12345/ddf/bundles HTTP/1.1

Content-Type: multipart/form-data;boundary="abcdef"

Content-Disposition: form-data; name="ddfbundle"; filename="example.ddf"

    ....... DDF bundle data .....


HTTP/1.1 200 OK

[ { "success": { "id": "12f39fa2bc4db1990715318e749d6270139609c68fb651a70c59339a91207450" } } ]

The returned id is the DDF bundle SHA-256 hash.

Possible errors

400 Bad Request

403 Forbidden