Definition

The definition metadata defines core information about your device handler. The initial values are set from the values entered when creating your device handler.

Example definition metadata:

metadata {
    definition(name: "test device", namespace: "yournamespace", author: "your name") {

        capability "Alarm"
        capability "battery"

        attribute "customAttribute", "string"

        command "customCommand"

        fingerprint profileId: "0104", inClusters: "0000,0003,0006",
                    outClusters: "0019"
    }

    ...
}

The definition method takes a map of parameters, and a closure.

The supported parameters are:

name
The name of the device handler
namespace
The namespace for this device handler. This should be your github user name. This is used when looking up device handlers by name to ensure the correct one is found, even if someone else has used the same name.
author
The author of this device handler.

The closure defines the capabilities, attributes, commands, and fingerprint information for your device handler.

Capabilities

To define that your device supports a capability, simply call the capability method in the closure passed to definition.

The argument to the capability method is the Capability name.

capability "Actuator"
capability "Power Meter"
capability "Refresh"
capability "Switch"

Attributes

If you need to define a custom attribute for your device handler, call the attribute method in the closure passed to the definition method:

attribute(String attributeName, String attributeType, List possibleValues = null)

attributeName
Name of the attribute
attributeType
Type of the attribute. Available types are “string”, “number”, and “enum”
possibleValues
Optional. The possible values for this attribute. Only valid with the “enum” attributeType.
// String attribute with name "someName"
attribute "someName", "string"

// enum attribute with possible values "light" and "dark"
attribute "someOtherName", "enum", ["light", "dark"]

Commands

To define a custom command for your device handler, call the command method in the closure passed to the definition method:

command(String commandName, List parameterTypes = [])

commandName
The name of the command. You must also define a method in your device handler with the same name.
parameterTypes
Optional. An ordered list of the parameter types for the command method, if needed.
// command name "myCommand" with no parameters
command "myCommand"

// comand name myCommandWithParams that takes a string and a number parameter
command "myCommandWithParams", ["string", "number"]

...

// each command specified in the definition must have a corresponding method

def myCommand() {
    // handle command
}

// this command takes parameters as defined in the definition
def myCommandWithParams(stringParam, numberParam) {
    // handle command
}

Fingerprinting

When trying to connect your device to the SmartThings hub, we need a way to identify and join a particular device to the hub. This process is known as a “join” process, or “fingerprinting”.

The fingerprinting process is dependent on the type of device you are looking to pair. SmartThings attempts to match devices coming in based on the input and output clusters a device uses, as well as a profileId (for ZigBee) or deviceId (for Z-Wave). Basically, by determining what capabilities your device has, SmartThings determines what your device is.

ZigBee Fingerprinting

For ZigBee devices, the main profileIds you will need to use are

  • HA: Home Automation (0104)
  • SEP: Smart Energy Profile
  • ZLL: ZigBee Light Link (C05E)

The input and output clusters are defined specifically by your device and should be available via the device’s documentation.

An example of a ZigBee fingerprint definition:

fingerprint profileId: "C05E", inClusters: "0000,0003,0004,0005,0006,0008,0300,1000", outClusters: "0019"

Z-Wave Fingerprinting

For Z-Wave devices, the fingerprint should include the deviceId of the device and the command classes it supports in the inClusters list. The easiest way to find these values is by adding the actual device to SmartThings and looking for the Raw Description in its details view in the SmartThings developer tools. The device class ID is the four-digit hexadecimal number (eg. 0x1001) and the command classes are the two-digit hexadecimal numbers. So if the raw description is

0 0 0x1104 0 0 0 8 0x26 0x2B 0x2C 0x27 0x73 0x70 0x86 0x72

The fingerprint will be

fingerprint deviceId:"0x1104", inClusters:"0x26, 0x2B, 0x2C, 0x27, 0x73, 0x70, 0x86, 0x72"

If the raw description has two lists of command classes separated by a single digit ‘count’ number, the second list is the outClusters. So for the raw description

0 0 0x2001 0 8 0x30 0x71 0x72 0x86 0x85 0x84 0x80 0x70 1 0x20

The fingerprint will be

fingerprint deviceId:"0x2001", inClusters:"0x30, 0x71, 0x72, 0x86, 0x85, 0x84, 0x80, 0x70", outClusters: "0x20"

Note that the fingerprint clusters lists are comma separated while the raw description is not.

Fingerprinting Best Practices and Important Information

Include Manufacturer and Model

Try and include the manufacturer and model name to your fingerprint (only supported for ZigBee devices right now - you can add them to Z-Wave devices as well, but they won’t be used yet):

fingerprint inClusters: "0000,0001,0003,0020,0406,0500", manufacturer: "NYCE", model: "3014"

When adding the manufacturer model and name, you’ll likely need to add the following raw commands in the refresh() command. This is used to report back the manufacturer/model name from the device.

The reply will be hexadecimal that you can convert to ascii using the hex-to-ascii converter (we’ll be adding a utility method to do this, but in the meantime you can use an online converter like this one):

def refresh() {
    "st rattr 0x${zigbee.deviceNetworkId} 0x${zigbee.endpointId} 0 4", "delay 200",
    "st rattr 0x${zigbee.deviceNetworkId} 0x${zigbee.endpointId} 0 5"
}

Adding Multiple Fingerprints

You can have multiple fingerprints. This is often desirable when a Device Handler should work with multiple versions of a device.

The platform will use the fingerprint with the longest possible match.

Device Pairing Process

The order of the inClusters and outClusters lists is not important to the pairing process. It is a best practice, however, to list the clusters in ascending order.

The device can have more clusters than the fingerprint specifies, and it will still pair. If one of the clusters specified in the fingerprint is incorrect, the device will not pair.