Zigbee Lock User Code addition

flynhawaiian · November 18, 2015, 7:21pm

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}"
}

github.com

SmartThingsCommunity/SmartThingsPublic/blob/master/devicetypes/smartthings/zigbee-lock.src/zigbee-lock.groovy#L71


			state "battery", label:'${currentValue}% battery', unit:""
		}
		standardTile("refresh", "device.refresh", inactiveLabel:false, decoration:"flat", width:2, height:2) {
			state "default", label:'', action:"refresh.refresh", icon:"st.secondary.refresh"
		}


		main "toggle"
		details(["toggle", "lock", "unlock", "battery", "refresh"])
	}
}


// Globals - Cluster IDs
private getCLUSTER_POWER() { 0x0001 }
private getCLUSTER_DOORLOCK() { 0x0101 }
private getCLUSTER_ALARM() { 0x0009 }


// Globals - Command IDs
private getDOORLOCK_CMD_LOCK_DOOR() { 0x00 }
private getDOORLOCK_CMD_UNLOCK_DOOR() { 0x01 }
private getDOORLOCK_CMD_USER_CODE_SET() { 0x05 }
private getDOORLOCK_CMD_USER_CODE_GET() { 0x06 }

flynhawaiian · November 19, 2015, 10:37pm

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

tpmanley · November 20, 2015, 6:03am

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.

Sticks18 · November 20, 2015, 2:45pm

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

flynhawaiian · November 20, 2015, 3:54pm

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.

Sticks18 · November 20, 2015, 3:59pm

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.

flynhawaiian · November 20, 2015, 4:00pm

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

Sticks18 · November 20, 2015, 4:02pm

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

flynhawaiian · November 20, 2015, 4:39pm

Is there a time cluster server in smart things?

tpmanley · November 22, 2015, 8:59pm

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?

flynhawaiian · November 23, 2015, 2:33am

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?

tpmanley · November 23, 2015, 9:22pm

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.

Tab13tab13 · November 30, 2015, 2:05am

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!)

flynhawaiian · December 15, 2015, 11:03pm

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…

Raj_Wasson · March 24, 2016, 2:09pm

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

Lgkahn · March 24, 2016, 3:23pm

just use this smartapp works great

[Depricated] Lock Code Manager Community Created SmartApps

There’s a new app! Please go to this thread for the new Lock Manager App, which is in active development. ##Legacy App: This app is no longer being maintained. Support and bug fixes are no longer being provided. Welcome to Lock Manager! Now with custom device type! Use the attached device type zwave-lock.groovy for added functionality. Minimal changes to SmartThings code. More reliable code set/delete. Codes will be reconciled on each poll() event. App will function without custom device type, but not as well. Features: Assign Codes to Multiple Users. Manage Multiple Locks. See what codes are active. See how many times a code is used (reset usage manually) Be notified when a user uses their code. Delete codes after they are used*. Optionally Schedule Users so that they only have ac…

Sticks18 · March 24, 2016, 4:10pm

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.

Lgkahn · March 24, 2016, 4:32pm

you’re right… my bad … sorry

jhamstead · September 19, 2016, 3:49pm

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.

Capabilities: Existing and Process to Add New. Note: Capabilities ~= Interfaces?: Capabilities MUST be very strictly defined and enforced (attributes / commands / events)? Devices & Integrations

One currently “live” and confusing / inconsistent example in the Capabilities Taxonomy is “capability.lock” vs. “capability.lockCodes”. I can’t quite understand why the latter needs to include the commands of the former: "lock()/unlock()"… [image] Does this imply that Lock Codes should inherit Lock? At least in this case and in the SmartThings environment, that is unnecessary because a single Device Type can serve multiple capabilities (i.e., both Lock and Lock Codes. Or is this an “error” in the the Lock Codes capability (or my understanding of it…): Specifically, is it possible and/or even common and likely to have SmartApps which use all the characteristics of Lock Codes except attribute: “lock” and methods commands: “lock()/unlock()”? Or is this NOT possible? The answer to tha…

RBoy · September 20, 2016, 4:39am

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

Zigbee Lock User Code addition

Customers

Developers

Download the SmartThings App