Difference between revisions of "Device Definition"

From Hubitat Documentation
Jump to: navigation, search
(Fingerprinting needs some work, I can't find any good info in the community forum that defines how fingerprinting works)
 
(Replaced content with " <big>'''We're moving!''' Please visit http://docs2.hubitat.com for the latest documentation.</big> <big> This document is available at: http://docs2.hubitat.com/en/devel...")
(Tag: Replaced)
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
==Overview==
 
The driver definition provides the Hubitat Elevation hub with information about a Driver you wish to install. The format is slightly different from an App as the definition must appear inside of a <code>metadata</code> block. Additionally it allows you to define the capabilities, commands, and attributes associated with the driver.
 
  
==Structure==
+
<big>'''We're moving!''' Please visit http://docs2.hubitat.com for the latest documentation.</big>
metadata {
 
    definition(
 
        ...
 
    ) {
 
        ...
 
    }
 
}
 
  
==Entries==
+
<big>
:: author - The author of this driver
+
This document is available at: http://docs2.hubitat.com/en/developer/driver/definition
:: description - A text description of the app that is displayed in the popup when the '''Add User App'' button is clicked
+
</big>
:: importUrl - The URL where the Groovy code for this app can be found
 
:: name - The name of the app
 
:: namespace - The namespace within which the Groovy class for the application will be stored
 
 
 
==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 on the [[Driver_Capability_List|Driver Capability List]]
 
 
 
===Syntax===
 
:: <code>capability "Capability Name"</code>
 
 
 
==Fingerprints==
 
Fingerprints provide a way for you to tell Hubitat how to identify a Zigbee or ZWave device based on certain properties and characteristics of the device.
 
 
 
===Zigbee===
 
 
 
====Syntax====
 
::<code>fingerprint profileId: "profileId", inClusters: "clusters", outClusters: "clusters", manufacturer: "manufacturerId", model: "modelId", deviceJoinName: "name"</code>
 
 
 
===Zwave===
 
====Syntax====
 
::<code>fingerprint deviceId: "id", inClusters: "clusters", outClusters: "clusters", mfr: "manufacturerId", prod: "productTypeId", deviceJoinName: "name"</code>
 
 
==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 <code>string</code>, <code>number</code>, <code>date</code>, <code>enum</code>, and <code>json_object</code>. When specified as a list of types, no validation is performed.
 
 
 
:: An example of this simple format is:
 
:: <code>command "myCommand", ["string", "number"]</code>
 
 
 
:: 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. If the name ends with an asterisk (*) the parameter is considered required.
 
:: type - The type of the parameter which can be any of <code>STRING</code>, <code>NUMBER</code>, <code>DATE</code>, <code>ENUM</code>, <code>JSON_OBJECT</code>, or <code>COLOR_MAP</code>. Note that a driver can only have a single command that accepts a <code>COLOR_MAP</code>.
 
:: description - The description of the parameter that is shown in the tooltip when you hover over the parameter.
 
:: constraints - A list of the valid options for an <code>ENUM</code>
 
 
 
===Syntax===
 
:: <code>command "commandName"</code>
 
:: <code>command "commandName", parameters</code>
 
 
 
==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===
 
:: <code>attribute "AttributeName", "type"</code>
 
:: <code>attribute "EnumAttribute", "enum", values</code>
 
 
 
===Parameters===
 
:: type - The type of the attribute. This can be <code>string</code>, <code>number</code>, or <code>enum</code>.
 
:: 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"]
 
}
 

Latest revision as of 04:00, 25 September 2022

We're moving! Please visit http://docs2.hubitat.com for the latest documentation.

This document is available at: http://docs2.hubitat.com/en/developer/driver/definition