Device Definition

For developers: the driver `definition` provides the hub with information about your driver

Device Definition

The driver definition provides the Hubitat Elevation hub with information about a driver you wish to create. The format is slightly different from an app as the definition must appear inside of a metadata block. Additionally, it allows you to define the capabilities, commands, and attributes associated with the driver.

Structure

metadata {
    definition(
        // ...
    ) {
        // ...
    }
}

Definition Parameters

Required Parameters

  • name: The name of the driver as will be displayed in the Type (driver list) on the device detail page and other places
  • namespace: A unique identifier for the developer (driver name plus namespace combinations must be unique), typically a username associated with that developer (often their GitHub username)
  • author: A string identifying the developer, sometimes a real name or company name (unlike the name and namespace, this is used only for display purposes)

Optional Parameters

  • importUrl - The URL where the Groovy code for this driver can be found (will auto-populate URL field when user selects Import button on driver code page)
  • singleThreaded - If true (default is false), simultaneous execution of a particular driver instance is prevented. The hub will load driver data (including state), run the called method, and save the data (including state) completely before moving on to any additional calls that may have been queued in the meantime. This applies to "top level" methods only. More details: https://community.hubitat.com/t/2-2-9-singlethreaded-option-for-apps-drivers/80969

Capabilities

A device driver can provide one or more capabilities. Capabilities are defined by the Hubitat environment. When you specify that a driver supports a specific capability, you must also implement any commands it requires. The list of supported capabilities can be found in the Driver Capability List

Syntax

capability "Capability Name"

Fingerprints

Fingerprints provide a way for you to tell Hubitat how to identify a Zigbee or Z-Wave device based on certain properties and characteristics of the device.

To generate a fingerprint for a device already paired to the hub, switch to the "Device" driver, run the "Get Info" command, and observe the "fingerprint" output in "Logs." These can also be built manually if you know the required information ("clusters" corresponds to "command classes" for Z-Wave). The "deviceJoinName" parameter is currently not used and may be omitted, although some authors prefer to set it to the manufacturer and model of the device for their own convenience. The "controllerType" parameter is also optional but is recommended (in particular because Zigbee and Matter fingerprints can be quite similar, and this will avoid the platform choosing the wrong protocol).

Zigbee Example

fingerprint profileId: "profileId", inClusters: "clusters", outClusters: "clusters", manufacturer: "manufacturerId", model: "modelId", deviceJoinName: "name", "controllerType": "ZGB"

Z-Wave Example

fingerprint deviceId: "id", inClusters: "clusters", outClusters: "clusters", mfr: "manufacturerId", prod: "productTypeId", deviceJoinName: "name", "controllerType": "ZWV"

Commands

Sometimes you will work with a device that has a command that does not exist in one of the existing capabilities. Hubitat gives you the ability to define custom commands to support these scenarios. Commands can also have parameters allowing you to define how data is passed to the command.

Parameters

parameters - a list of the parameters to pass to the command. Each parameter is, itself, a map that defines details about the parameter. See below for information on defining parameters.

Defining Parameters

The simplest way of defining parameters is to just specify a list of types. The parameters can be of type STRING, NUMBER, DATE, ENUM, JSON_OBJECT, or COLOR_MAP. When specified as a list of types, no validation is performed.

An expanded format also exists that allows you to provide more details about the parameter such as its name, whether or not it is required, and in the case of an enum, the available values. In this mode each parameter is specified as a map with the following entries:

  • name - The name of the parameter (used for display only). If the name ends with an asterisk (*), the parameter is considered required.
  • type - The type of the parameter, which can be any of STRING, NUMBER, DATE, ENUM, JSON_OBJECT, or COLOR_MAP. Note that a driver can only have a single command that accepts a COLOR_MAP.
  • description - The description of the parameter, shown in the tooltip when the user hovers over the parameter.
  • constraints - A list of the valid options for an ENUM

Syntax

command "commandName"

command "commandName", parameters

Simple example:

command "myCommand", ["number", "string"]

Expanded format example:

command "myCommand", [
   [name:"My first parameter*", type:"STRING", description:"Description of this required string parameter"],
   [name:"Color", type: "ENUM", description: "Description of this second parameter", constraints: ["red","blue","green"]]
]

Attributes

Sometimes you will work with a device that has an attribute that does not exist in one of the existing capabilities. Hubitat gives you the ability to define custom attributes to support these scenarios.

Syntax

attribute "attributeName", type  // type must be one of the below

attribute "enumAttribute", "enum", values

Parameters

type - The type of the attribute. Commonly used types include string, number, or enum.

values - If the type is enum, you must also provide a Groovy list of values that the enum accepts.

Example

definition(
    name: "My First Driver",
    namespace: "myfirstdriver",
    author: "John Smith"
) {
    capability "Actuator"
    capability "Switch"

    command "myCommand"

    attribute "myAttribute", "string"
    attribute "enumAttribute", "enum", ["value 1", "value 2"]
}

For more information on attribute data types, see: Attribute Object.