Zigbee Lock User Code addition

Devices & Integrations
1

I’ve been working on a way to add user code support to the existing zigbee lock device. Using smartthings device: zigbee-lock found in the github, link below. I’ve deciphered what the codes are to send to the lock, but am just a little unsure about the actual implementation.

I’ve written a basic piece of the code, but I absolutely have no idea if it will work. Thoughts and help would be appreciated. I’m starting with “set codes”. Trying to send a code of 12345678 to the yale touchscreen deadbolt lock with zigbee.

private getDOORLOCK_CMD_USER_CODE_SET() { 0x05 }

def userset() {
def cmds = zigbee.zigbeeCommand("${CLUSTER_DOORLOCK}", “${DOORLOCK_CMD_USER_CODE_SET }”, “{12345678}”)
log.info “userset) – cmds: $cmds”
//return cmds
"st cmd 0x${device.deviceNetworkId} 0x${device.endpointId} ${ DOORLOCK_CMD_USER_CODE_SET } {12345678}"
}

2

anyone have an idea? It would be really nice to get this feature working. If someone can help me that would be grand!

3

That looks like the right command but it takes a few additional parameters, specifically:

  • User ID - unsigned 16-bit integer
  • User Status - unsigned 8-bit integer
  • User Type - 8-bit enumeration
  • PIN - string

The user ID can be 0-250 for the Yale lock. 0 is the master key, so you can use 1-250 for a user key.

User Status can only be 1 (Occupied/Enabled) or 3 (Occupied/Disabled) per the HA spec so I think you want to use 1.

There are a few possible different user types, but you probably want to use 0 for unrestricted user which is the default.

Given that, I think the command you need to send looks something like this:

st cmd 0x${device.deviceNetworkId} 0x${device.endpointId} ${CLUSTER_DOORLOCK} ${DOORLOCK_CMD_USER_CODE_SET} {010001000812345678}

Note that I’m using the st cmd instead zigbee.zigbeeCommand because we’re in the process of rolling out a change to that function and it’s better not to use it until we lock it down and document the API.

Unfortunately I tried the above command and I got back a Default Response of 0x80 indicating the command is malformed. Hopefully you’ll have better luck than I did. I’ll try to get some time to look at it on the sniffer and see where I screwed up. I think it’s probably with the formatting of the PIN code.

1 Like
4

I see you used little endian for the UserID, which is typical of zigbee. Is it possible you need to the same for the string somehow?

I don’t think I’ve ever had payload fields greater than 2 octets, so I’m not positive how to properly format anything longer.

REVISED: I take all that endianness stuff back. Looks like each character needs to be an octet. The 08 is the length in octets, so using a string to hex converter the PIN portion of the payload is:

08 31 32 33 34 35 36 37 38

5

So would we need to put in a function to deal with the conversion from string to hex? Looking at the Zwave code it relies on decrypting and encrypting the string from a code given from the lock itself. I’m not sure the zigbee protocol uses the same method, but it doesn’t appear so to me.

There is something investing as well… Does “send pin over air” need to be turned on? I’m guessing at some point there also has to be reading of the current pin codes via “get pin codes”?

I wish I had the zigbee Home Automation v1.2 specification document, but they seem to keep that stuff locked up for some strange reason.

6

It’s a pretty easy conversion for numbers. Just add a 3 before each number. You’ll see the same thing when the lock sends a code back.

The “send PIN over the air” needs to be true for the lock to send a pin to the hub as in “get pin codes”. If it’s false, you’ll just get a bunch of FF octets back instead of actual code characters.

This is from the spec (you can download the spec for free by going to http://www.zigbee.org/zigbee-for-developers/applicationstandards/zigbeehomeautomation/ and clicking download at the very bottom. You just input some basic contact information that isn’t checked or anything and you’ll get a download page):

For example (PIN “1234” ): If the attribute value is True, 0x04 0x31 0x32 0x33 0x34 shall be used in the PIN field in any door lock cluster message payload. If the attribute value is False, 0x04 0xFF 0xFF 0xFF 0xFF shall be used.

7

I think the default is false, I’m wondering if it will have to be turned on each time?

8

No, you should be able to write to that attribute and it will stay 1 unless the lock loses power or is reset.

10

Is there a time cluster server in smart things?

11

The time cluster server in the released firmware doesn’t work correctly but it will be fixed in an upcoming firmware release. However this release won’t support all of the optional attributes on the time cluster so the schedule features of the lock may not work. I expect that we will eventually support more of the optional attributes on that cluster.

Did you have any luck setting pin codes?

12

No not yet I’ve been away this weekend. I’m still wondering what I can do to get that working faster. I wish I could send commands via a Xbee for faster programming :).

Any luck on your end with the sniffer?

13

Yep, I was able to set user code 3 to a PIN of 0123 with this command:

st cmd 0xF95D 1 0x0101 0x05 {0300 01 00 04 30 31 32 33}

Now I can lock and unlock the door from the keypad with that PIN. This PIN is not required for lock and unlock commands sent over the air from the device type handler.

14

Gentlemen, please continue this good work. I ‘inherited’ a Yale YRD-220-HA-619 when our low voltage contractor worked on our house. I very much would like to work the lock via ST just like I would at the keypad…but with a much simpler interface. @flynhawaiian, I am not a programmer, but will be happy to be a real-life tester in the field if you need one. I will have time for this in late December (vacation time comin’ my way!)

15

I’m still working on it, but now my lock has completely stopped working with smart things. Haven’t even done anything different just stopped working 6 days ago. so peeved…

16

Any progress on this. Can I help work on it?

17

just use this smartapp works great

18

That’s for zwave. This thread is for zigbee locks. Should be able to use the same SmartApp once someone creates a working device handler for zigbee locks that includes setting codes.

19

you’re right… my bad … sorry

20

So I’m going to take a stab at writing this. Was looking for some information. Is there more detail on the “lock code” capability? I don’t see it in the documentation anymore. All I can find is this reference.

21

We’ve started taking a stab at this in our lab. Will report back once we see some progress. More difficult than i expected. Need to study the zigbee guide