Part 3: Adding lockCodes capability
So, the SmartThings documentation says that lockCodes is a proposed capability (not production), but I'm pretty sure it is in use by other drivers, and also calling
smartthings capabilities -s shows that lockCodes are "live", not prosed or deprecated, so I'm going for it.
As always, I look for examples. zwave-lock in the SmartThings community edge drivers repo is a good reference.
several hours later....
I fought this a lot today, and made what I feel like is zero progress. I feel like I'm missing something fundamental.
I was able to add the capability to the driver fairly easily. I setup command handlers for basically all of the commands (just empty shells so that I can see when they are being called). However, I cannot figure out how to get the lockCodes attributes set, or send the right events to have this work. Here's current state:
Open the Life / Smart. Lock Guest Access app from mobile device/emulator. OK.
See my keypad "lock" listed. OK
This fires the reloadAllCodes commandHandler. Not sure what to do with it right now as the codes are NOT stored on the ring keypad (zwave command class USER_CODE is not supported). But I can see it being fired.
Go to to Lock codes from the top left dropdown.
I don't see any codes defined yet. That's fine.
I hit "+ Invite guest", add a name, select my keypad lock, and a 4-digit code.
When I hit "Create code"
"Creating lock code..." with 1 green dot and 3 blue dots spinning, then after some time (~15 seconds?) an error message pops up "Something went wrong while creating the lock code. Try again".
My lockCodes.setCode command hander is firing.
I've tried firing events from device:emit_event for both lockCodes and codeChanged attributes, but that didn't seem to make any difference.
I've tried digging into default zwave lockCodes code and mimicking that code, such as doing set_field on the device for fields _lock_codes and _code_state, with the same data structure, and that didn't seem to make any difference either.
I've done 6 &7 together - no dice.
Current thoughts:
I need to spent more time getting my environment/autocomplete setup to make this easier.
Are the default zwave handlers/configuration for the device, driver, or capability doing something special/automatic in tandem that I haven't been able to tap into yet? Like are there events, variables, fields, whatever that I need to be working with that I just haven't found yet?
Are the default zwave handlers/configuraiton for the device, driver, or capability getting in my way -- and is there a way to bypass that. I'm wondering if the fact that zwave command class USER_CODE isn't supported by my device some assumed or default behavior isn't happening.
Is there a better documentation anywhere? It's great that the capability metadata/structure is defined, but there is nothing indicating expectations on what, say, reloadAllCodes or setCode is actually supposed to do, or what events they should fire, etc. If that documentation does exist I haven't been able to find it.
Maybe I should look at the existing integration tests and understand them, and possibly clone/create them for my driver to make iterations quicker.
Another day ...
I finally hit upon the right combination of things to do to create the codes. Once I got that working, tweaking it for my needs, as well as implementing deleting and renaming was fairly easy and straight-forward. Here's the secret as far as I can tell, which boils down to knowing the lockCodes interface definition (at least as far as it makes it work with Smart Lock Guest Access app, but I can't find any actual documentation on):
Emitting the event lockCodes.lockCodes with the full list of codes seems to be a thing to do... although it really seems like SLGA really hooks into the lockCodes.codeChanged events the most. I really don't think this event is necessary for SLGA but I'm going to keep doing it anyway. Maybe other components need initialized with that full list before knowing what to do with the individual slot-changed messages.
When publishing via event lockCodes.lockCodes, it appears the data structure {1="name", 2="name2", 3="name3"} is expected. I will be storing the PIN as well with each code, but I'll strip it out when sending this event -- for both security and consistency reasons.
The event lockCodes.codeChanged seems to do the heavy lifting, although sending messages like "3 deleted" instead of good data structure seems a bit odd to me. But it seems to work.
For my personal preferences, I am NOT using the 'baked in' data structure that is saved on the device table (fields _lock_codes, _code_state, _checking_code) since it does NOT contain a PIN field. Instead I will code everything to use a structure [{codeSlot, codePIN, codeName}, ... ]. When outputting via emit event, I will NOT publish the PINs for security/consistency reasons. Example code from the driver table:
That's a big milestone. Pausing here to celebrate for a minute. Next Steps:
Clean up the code (majorly)
remove or deal with comments
organize the code (e.g. separate out zwave functionality from capability logic, move to different files?)
Clean up the settings page of the app (remove single-pin preference, mostly)
Clean up the device page of the app (lots of junk there that isn't needed/wanted, in weird order, etc).
Can I change the device icon and "button" in the app?
I'm not under-estimating the cleanup of those pages because it seems intertwined with the profile.yml and defined capabilities. Yikes.
Look for missed functionality
Look into writing tests for the driver. At first glance it looks wonky but should probably dive into it to understand it.
Start looking into building the app that will manage the scheduling of the codes. I could bake the data into the driver itself, but since there is no UI for that, might as well tackle it as an app or whatever SmartThings calls it.
Comments