Zigbee

Welcome to the smartthings wiki!

All about Zigbee

Zigbee protocol for Home Automation...

Each device has a pairing mode that broadcasts out the request to join a mesh

A zigbee controller can create a mesh and allow devices to join that mesh.

This controller sets the master key for encryption and shares it during joining the mesh.

In Smartthings, during the pair process you can see the join and fingerprints in the IDE logs, don't blink you might miss it.

These endpoints are critical to understanding the device and if/how you can communicate with it.

If you miss these endpoints, you can get them by calling this function in the devicetype:

def getClusters() { "zdo active 0x${device.deviceNetworkId}" }

This zdo active command will NOT log the response to the devicetype, instead you have to look in the raw IDE logs (log tab)

For example:

ep_cnt:4, ep:01 C4 C5 C6

This means there are 4 endpoints for this devicetype. 01 is a standard HA type which is then logged like this:

desc: 01 0104 0101 00 07 0000 0003 0004 0005 0006 0008 0000A 00

thanks to @jonhr for the breakdown: 01 = End Point number 0104 = Profile Number: Home Automation profile 0101 = Device Type: Dimmable Light 00 = Version: 00 07 = In Clusters: The next 7 numbers are inbound clusters (server Clusters) 0000 = Basic 0003 = Identify 0004 = Groups 0005 = Scenes 0006 = On/Off 0008 = Level Control 000A = Time 00 = out Clusters: No out clusters (client Clusters)

For example, here is a Control4 keypad packet logged by Smartthings:

(Thanks @urman for the details) catchall: C25D 0001 02 02 0C40 00 7D47 00 00 0000 0A 01 0700421B63343A636F6E74726F6C345F6B65797061643A43342D4B50322D5A0400420830332E32322E3431050020050600212600

C25D = Manufacture Specific Profile, probably control4's. We use HA (Home Automation) 0001 = Cluster 0001. In normal ZigBee this is Power Configuration, but it doesn't look like thats what they are using it for 02 = Source Endpoint ID 02 = Destination Endpoint ID 0C40 = Special Options (not sure what) 00 = ?? 7D47 = Network ID 00 = Cluster Specific (no) Probably because the entire profile is Manufacture Specific. Same for the next. 00 = Manufacture specific (no) 000A = Report Attribtue 01 = Pretty sure this means direction (to the hub) Rest of it = Payload.

The payload is hex encoded and essentially just tells us the device type c4:control4_keypad:C4-KP2-Z and the firmware version 03.22.41 in this case.

You can use this website for converting hex to strings: http://string-functions.com/hex-string.aspx

These catchall check ins happen every so often.

Also, on any button press you will get a similar log entry that will report what the device did.

So in order for the "Thing" to pair up correctly to your custom devicetype you need to match the fingerprint to the endpoints.

So based on that pair log and help again from @johnr this is the fingerprint for the control4 dimmer:

fingerprint endpointId: "01", profileId: "0104", deviceId: "0101", deviceVersion: "00", inClusters: "07 0000 0003 0004 0005 0006 0008 000A", outClusters: "00"

This allows SmartThings to match up the device "Thing" it finds during the pairing process with a custom devicetype. It isn't perfect, but if it doesn't ID, then there is something wrong with the fingerprint.

If you don't get it to fingerprint, you won't get your endpointId and you will have to either fix your fingerprint or manually force your devicetype to the endpointId.

Ideally you want the pairing to work and call up your devicetype, otherwise all kinds of bad things can happen.

Also, never delete your devicetypes of paired devices... Bad things happen.

So now that we have a device paired and we want to focus on writing a custom devicetype, the structure is pretty straightfoward...

The standard devicetype has a parse function... This is where all messages from the zigbee device will be parsed.

From this message that comes back, all information can be parsed and routed to the appropriate actions / events.

Also, there are 3 main methods for sending commands to the zigbee device:

(thanks @urman) rattr - Read Attribute watts - Write Attribute st cmd - Command

They are part of the ZigBee ZCL protocol. You can find more information on a cluster by cluster list of available commands/read/write here:

http://www.zigbee.org/Products/ZigBeeClusterLibraryDownload.aspx