Lock Valet

Lock Valet is a plugin for Vera Home Automation controllers that speeds programming of lock codes and schedules for Schlage, Kwikset, and Yale Z-Wave locks (and presumably others yet to be discovered and tested).

Installation

LockValet is currently in pre-release testing. To receive a copy of LockValet and instructions for installing it, contact me.

Operation

Once installed, LockValet will inventory all compatible locks on your Vera, retrieve the codes (if possible), and add them to its configuration. Below is an example display for LockValet's control panel.

Lock Valet Configuration Example

Each code appears together with its schedules. Next to each code is a status icon. Hovering over the status icon will generally give you more detailed information about the status of the code. In the right-most column are the action icons, which allow you do edit and delete the code, enable and disable the code, add schedules, and refresh code (resend them to the lock). The first three codes in this display are locked and protected; see the section below on Protected Codes for explanation.

The lock selector lets you choose the lock for display and editing. It will list all eligible locks on your Vera. If there is only one eligible lock the select automatically chooses it, and its codes and schedules are automatically displayed when you open LockValet's control panel.

By default, lock codes are not shown on screen. If you want to see the codes, click the "Show Codes" checkbox next to the lock selector. Turn them back off by clicking the checkbox again.

Adding a Lock Code

To add a code, click the add icon over the "PIN Code" table heading. This will open code editing in a new slot. Enter your PIN code and a code name, then use the save icon save to store the code. Clicking the cancel icon cancel abandons code editing.

PIN codes must follow the rules for the lock device for length and characters. Schlage locks, for example, permit only 4-numeral PIN codes. Other locks may permit shorter or longer codes, and other characters.

Editing Codes and Schedules

To edit an existing code, click the edit edit icon in the same row as the code. You may then change the code PIN and name as needed. If codes are hidden, the code field will contain the XXXX hiding string; you may leave it this way if you want to leave the code unchanged and just change the code name.

LockValet programs your codes and schedules using a background task running in the plugin. The current Vera UI for locks requests a long (two minutes, as stated) wait between every editing step, so doing multiple code edits or schedule updates can be a length process in the Vera UI.

LockValet allows you to make the changes almost as quickly as you can make them, and the background process takes whatever time is necessary to get the Vera lock device programmed as you've requested.

The only time you may need to wait is if the Vera restarts while you are editing (the interface will inform you). When a restart occurs, your changes are not lost! LockValet will resume making your requested changes from where it left off, ensuring (as much as reasonably possible) that the lock and your edited configuration stay in sync.

Enabling/Disabled Codes

A feature of LockValet that is not native to Vera's lock interface is enabling and disabling of codes. Disabling a code removes it from the lock, but does not discard its configuration in LockValet, so you can re-enable it later. Disabling a schedule overrides all schedules for the code--the code will be unusable even if it is in an active scheduling period. When enabled, the code is restored to the lock, and any schedules associated with the code are then effective.

To disable a code, click the disable block icon. Once the update completes, the code status will show with the "blocked" icon block. The actions icons will now have an enable icon play_circle_outline, which when clicked will re-enable the code.

Hint: when a code is disabled, the lock does not need to be notified of any code or schedule changes for that code, because the code isn't even on the lock. This makes editing even faster! If you have a lot of schedule edits to do on a lock code, disable it first, then do your edits, and re-enable it after.

Schedules

To add a schedule to a code, click the add schedule icon alarm_add. A new schedule row will be opened, allowing you to set the schedule type, and the parameters corresponding to the type.

LockValet currently supports only the two types of schedules supported by Vera: daily and weekly.

A daily schedule makes a code available between a start date and time and end date and time (e.g. from 4:00pm on July 2, 2018 to 11:00am on July 8, 2018). The code is available at all hours of the day and night between the start and end specified. Once the end date/time passes, the code no longer functions. The Cranky schedule in the figure above is an example of how a daily schedule appears when programmed.

A weekly schedule makes a code available between specified times on specified days of the week (e.g. between 9am and noon every Tuesday and Thursday). Weekly schedules recur as long as the code is enabled, until the schedule or the lock code is deleted. The Friendly schedule in the figure above is an example of how weekly schedules appear when programmed.

The current version of LockValet uses Vera-managed scheduling, meaning that the codes and schedules configured in LockValet are configured into Vera's lock device, and Vera manages the timing of activating and de-activating codes. Because Vera does not currently support mixed schedule types on a single code, all schedules for a single code must be of the same type (all weekly, or all daily). Mixed schedule codes are not permitted and will cause errors or unpredictable results if attempted.

Protected Codes

When LockValet inventories locks and codes, it may encounter codes that are not available to the Vera. Typically, these are codes programmed directly on the lock itself, using the lock's keypad. They could also be codes programmed by another system and stored encrypted on the lock. Some brands, such as Schlage, factory program the first two code slots with special master codes. In all these cases, the codes may not be available to Vera, and probably should not be casually changed.

LockValet identifies these special codes and marks them as protected and locked. These codes cannot be changed in LockValet, and LockValet will not attempt any modification of these code slots. You can identify these codes by the lock icon lock in the action area for the code, and the absence of editing and other controls. The codes also typically show as **** or similar, as they are permanently hidden/unknown to Vera and LockValet (i.e. using Show Codes will not reveal them).

Config Backup & Restore

Like any facility, any time you finish important changes (or before you are about to make some risky ones), you should back up your configuration. A link in provided for this purpose in the footer of the configuration/control page. LockValet keeps a single backup on the Vera. You can restore the backup any time by using the "restore" link.

Periodically, it's a good idea to make offline copies of your configuration. To do this correctly, you must copy both the configuration file (/etc/cmh-ludl/lockvalet.json) and the encryption private key (/etc/cmh-ludl/lockvalet.bin). The lock PINs stored in the configuration file are stored encrypted using this private key. If you do not have the private key that matches the configuration file, the configuration backup will not be usable to restore, so always back up both files at the same time. For the moment, backuping up these two files requires that you use one of two methods:

  1. Use an SSH-capable file transfer program (like scp on Linux or WinSCP on Windows/Mac) to connect to your Vera locally (while on the same LAN) to download the two files to your local computer;
  2. Log in to your Vera using SSH and use the scp or ftpput commands to copy the files to a computer on your network that has an ssh or ftp server running (there are also some other similar tools you can use to accomplish the same thing).

Note that although these files are visible in the Vera dashboard under Apps > Develop apps > Luup files, the author has had little consistent success retrieving these files using the "download" links there. If it works for you, great. It's been hit or miss for me, and inconsistency is not something you want in a backup strategy. Be sure to check the files. The private key file should be 32 bytes in length, and is a binary (not human-readable) file. The configuration file is JSON data and can be checked by validation at jsonlint.com.