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.
Attributes
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.
Commands
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.