Capability lockCodes (update)

(Duncan) #1

In preparation for the long-delayed official lock code management solution, we’re making some changes to how the “Lock Codes” capability works. The main difference is that we’re removing the actual unlock codes from the events and storage for security reasons.

Also, the setCode command will add an optional name argument that will let you give meaningful names to your codes so you know which code to delete or change when you need to. We decided to store this at the device level so you can eventually manage codes directly in the device preferences.

The proposed spec is below – let us know if you see anything missing or any issues that may hurt its usability.


lockCodes – JSON object mapping code IDs to code names. If a code hasn’t been set it won’t appear in the mapping. Example:

{ 1: "Code 1", 2: "Code 2", 3: "Alice", 4: "Bob", 8: "Carla" }

This means the lock has codes 1, 2, 3, 4, and 8 set, 1 and 2 were likely the default codes so they were automatically given default names.

codeChanged – An event attribute (i.e. current value is not relevant) with string value "$id $change_type" where change_type is one of ["set", "changed", "deleted", "failed"] and id is either the integer code ID (0 for the master code) or “all”. Examples: “3 set”, “5 changed”, “all deleted”, “3 failed” – the “failed” status is sent when we try to set a code but the lock rejects it, for example because it was the wrong length or duplicated another code.

codeLength – The integer length of code string that the lock accepts, most locks default to 4 but have the option to increase it with the setCodeLength() command.

maxCodes – Reports the number of code slots the lock has, which is also the maximum code ID that can be set.


setCode(int id, String code, String name) – Programs code code into code slot id – if the code is successfully set on the lock, it will update the lockCodes attribute value to indicate that code id is named name. The code parameter is generally a string of numerical characters, such as “0485” or “7777”. A codeChanged event will also be sent with the result of the operation, which is useful if you are editing an existing code or if the setCode fails.

deleteCode(int id) – Deletes code id from the lock and removes its name from lockCodes

checkCode(int id) – Will query the lock to determine if code id is set in order to update the lockCodes information. For example, if you delete code 4 using the lock’s keypad when your SmartThings hub is offline, we will not know that the code is no longer set until a call to checkCode(4).

checkAllCodes() – Basically calls checkCode(id) for each code id in sequence to fully refresh the lockCodes information to accurately represent the current status of the lock.

setCodeLength(int length) – Most locks allow you to change the code length – they require that all codes are the same length so the keypad knows when to tell you that you entered the code wrong. Therefore changing the length will generally delete all existing codes, so it should be used carefully.


Sounds like a good direction.

Did anything change overnight in the official device handler?

My Yale zwave lock began making voice announcements today, something it has not done since the original installation 8 months ago. Battery life is over 50%. We have not made any changes to the lock or codes. We do not use any custom SmartApps or device type with the lock.

edited to add And after 6 hours of voice notifications, now they’ve stopped. No changes on our part, standard device type.

(Kevin Shuk) #3

This isn’t how the Yale locks work, at least. Can’t speak for other mfrs/models. The Yales accept 4-8 character codes, and use the asterisk to denote the end of the code, so you can have mixed code lengths (I think this approach gives about an 11%-ish bump in keyspace)

But as long as my handler can noop on it, that’s fine as it supports other types of locks that care.


Perhaps this should be a pair of attrs: minCodeLength and maxCodeLength? With the Yale, min=4; max=8. For a uni-length model min=max=4 (assuming it is indeed 4). If the unit supports having the code length set, then, both min and max would change accordingly (yet be equal).

I like this - this was how I’d originally developed my Yale handler, but excised names to the app level specifically because support for managing codes HAD to be at the app level.