Use Buttons As PIN Input ("Security Keypad") e.g., Aeon Aeotec Minimote, ZWN-SC7 Enerwave 7 Button; trigger to Routines, lock/unlock, arm/disarm, mode, lights

This is a pre-release BETA: Testing and feedback is highly encouraged.

Description

Use Buttons As PIN Input
Assign a multi-button controller (e.g., Aeon Labs Minimote) to be a security ‘PIN code’ input pad, which triggers a switch, lock, mode, or Hello Home action.

App Name: Use Buttons As PIN Input
Category: Safety & Security
File Name: ButtonsAsPIN.app.groovy
License: See repository and/or source code header comments.
Version: v0.1.4-beta (non-production pre-release) as of latest update.
Published/Submitted to SmartThings Marketplace: no
Published to “Browse SmartApps” in IDE: yes
Releases URL: https://github.com/CosmicPuppy/SmartThings-ButtonsAsPIN/releases/latest
Master URL: https://github.com/CosmicPuppy/SmartThings-ButtonsAsPIN

SmartApp Code Snippet (Copy code from here to paste into IDE…):
See much later post in this Topic Thread: Code has been updated to fix bugs
. Use Buttons As PIN Input ("Security Keypad") e.g., Aeon Aeotec Minimote, ZWN-SC7 Enerwave 7 Button; trigger to Routines, lock/unlock, arm/disarm, mode, lights


Notes / Discussion

  1. I have only tested with the 4-button Aeon Minimote. If you have other types of multi-button devices, I would love if you could test with these and we can work together on required code modifications.

  2. PIN Combinations are thus currently restricted to selections of digit values from 1 to 4 (the app does not currently incorporate the option of “held” buttons as digit values 5 to 8, though this would be a minor enhancement). Configuration consists of selecting the number of digits in the “PIN” (min 3, max 9), and then setting the PIN via selection of each digit into each sequence slot, via the pulldown (enum) user interface.

  3. After PIN definition, user configures light/switch/lock toggles, mode set, and/or Hello Home Action that will be called upon correct PIN entry detected.

  4. The “toggle” concept is based on the Smart Button Controller SmartApp by SmartThings and has some behavioral ambiguity that is noted in comments in the code. I recommend that a well-written Hello Home action is specified instead of individual devices. The Hello Home action could use mode or state to decide if the PIN entry is deactivating an alarm, unlocking a door, etc., and/or the opposite. Perhaps I will change the configuration pages such that Hello Home Action is the first and most prominent choice.

  5. Detection of correct PIN is based on last “n” button presses detected, where “n” is the PIN length set by the user. There is no concept of “start / end / clear” or “activate / deactivate”. I considered various possibilities, but the essence of this SmartApp is simplicity even if that reduces the level of security of the code and/or the overall functionality.

  6. In order for button input to be reliably captured by the App, buttons should not be pressed faster than are acknowledged by the device. The Aeon Minimote flashes the upper right red LED a few moments after a button is pressed – it is then ok to press the next button in the PIN sequence input attempt. In reality, not waiting for acknowledgement will work in a lot of cases – there is some buffering that takes place. Uncaptured (lost) button presses are likely to occur for sequences that repeat digits (e.g., {1,1,2} requires waiting for acknowledgement between the first two presses but not between second and third presses). I presume the Aeon Minimote firmware must do some de-duping. See the source code for additional notes on this phenomenon – The SmartThings event storage for the device only seems to “fill up” in this case of repeat digits, though I could not get consistent results from trying to read those events. I also suspect that if the user does not wait for acknowledgement, Z-Wave and/or Zigbee does not guarantee the order that button presses will reach the hub, since the messages pass through the mesh, etc… (Perhaps someone here is familiar with the protocol in detail and can confirm under what circumstances input sequence is or is not preserved…?).

  7. Does the term “PIN” in the name of this SmartApp reflect its functionality? Should the name and/or description, etc., use other wording such as “security keypad” or … other suggestions / ideas?

  8. What about the choice of icon? (Current icon: See the silver 8-button open padlock on blue background, above).


Security Level (Complexity) of the PIN:
Based on 4 buttons and a PIN length of 3, sequence order is important, and repeated numbers are permitted: There are 64 possible PIN permutations (e.g., {1,1,1}, {1,1,2} … {1,2,3} … {1,2,4} … {4,4,4}).
The formula for the permutation count is: N^L (N=number of buttons, L=PIN length): 4^3 = 64.
A PIN length of 4 digits might be customary: 4^4 = 256 permutations.
The App permits up to a length of 9 digits in the sequence: 4^9 = 262144 permutations.

Note: Since this App only looks at the last “L” button presses in a rolling buffer, an efficient “shortcut” input sequence can be used to input all possible permutations by taking advantage of the “overlap”. These are called De Bruijn Sequences.


NB: The Aeotec / Aeon Labs Minimote is discussed in various Community Forum topics
Click to Aeotec official product page.
Some of these units are available quite cheaply (~$25-$30/each, or 3 for $70) on eBay and/or Amazon, perhaps because they are overstock of the older model (but have user upgradable firmware via USB). http://smile.amazon.com/Aeon-Labs-DSA03202-v1-Minimote/dp/B00KU7ERAW/ref=sr_1_1?ie=UTF8&qid=1419249253&sr=8-1&keywords=minimote


Thank-you!
…CosmicPuppy (Terry) - @tgauchat

9 Likes

Since this App only looks at the last “L” button presses in a rolling buffer

Correct me if I’m wrong, but it seems to me that your app can get out sync. Let’s say I chose 4-digit pin, then I accidentally press a button. Now, when I try to enter my pin, it will never match because of that extra digit that was stuck in the buffer. You need to clear the buffer after certain period of inactivity to avoid this.

I don’t think so geko.

Based on what he’s saying, I think that the code only looks at the last n-button presses and if that ever equals the pin, then it unlocks the door. For example, if my pin is: 2431… then the app looks at the last 4 button presses:

I punching in: 2 4 3 1: Valid… unlock happens. The buffer now contains those numbers: 2 4 3 1.

I leave, lock up, but the remote in my pocket. When I come up, as I’m getting the remote out of my pocket, I hit the 3 button. Now, the buffer contains: 4 3 1 3. Obviously, not a valid code. Now I type in my PIN. As I do, each keypress pushing the buffer along:

Press 2, buffer = 3 1 3 2 - Not a valid code, no unlock.
Press 4, buffer = 1 3 2 4 - Not a valid code, no unlock.
Press 3, buffer = 3 2 4 3 - Not a valid code, no unlock.
Press 1, buffer = 2 4 3 1 - Valid Code! Unlock.

I might be wrong, but I think that’s how the app is designed.

1 Like

Looks like a cool app, @tgauchat

What’s your thinking in how this would be used. Would a person carry the remote with them, or would it be mounted outdoors somewhere? My concern with taking it with them when they leave it two fold:

First, what kind of battery life do these things have when NOT connected to a hub? I’ve got one in my house that I use a Garage door opener for two of the buttons, and alarm arming system with the other two. I might have a defective unit but I’ve found battery live is pretty bad. It needs to be charged like every couple of weeks. If it isn’t connected to a hub, does it constantly ping the hub? If so, this might burn through the battery really quickly.

Second, how long does it take to re-establish connection to the hub? If someone has to wait for a couple of minutes outside for it to “reconnect” and only then punch in the code, that could be an annoyance.

(Obviously these things are well out of your control, but thought I’d ask if you happened to do any testing under these conditions.)

1 Like

Sorry for so many replies in a row, but these are different thoughts so didn’t want to “muddy the waters” by putting them together in the same message.

Suggestion: Is there a way to determine failed code attempts? It might be nice to have a lock out feature where after x-number of failed attempts the app will reject any code entry for y-number of minutes.

If my understanding of the way the buffer works is correct (see earlier reply to geko), then it would be a little complex because there aren’t “entry events” (ie, a complete code entered), but I think it would be possible to count each button press at 1/nth of a code entry. Then you’d lock out after x*n button pushes (Where x = number of fail attempts the user selected and n = pin size) where no valid code was entered.

1 Like

Thanks for your observations…

@chrisb actually responded with the actual behavior of the SmartApp, such that it avoids the problem you suspected: Use Buttons As PIN Input ("Security Keypad") e.g., Aeon Aeotec Minimote, ZWN-SC7 Enerwave 7 Button; trigger to Routines, lock/unlock, arm/disarm, mode, lights - #3 by chrisb

I call this a “rolling buffer”, and it is set to the user selected PIN Length. The oldest button press digit is discarded when each new press event is received.

This behavior described by Chris can be observed in Live Logging if log.debug is enabled: I log.debug output the contents of the buffer after each button event so that you can observe the rolling effect, and perhaps see if any button presses were dropped in transmission.

There is just one note:
I actually do clear the input buffer; only and immediately after the correct PIN is detected.

This is to avoid a particular situation that occurs if digits at the end of the PIN are the same as at the beginning of the PIN.

e.g., If the PIN is {1,1,1,1}, then the buffer could contain [1,1,1,1] and actions are triggered. If the buffer wasn’t cleared, then if the next button pressed is “1”, the buffer would again contain [1,1,1,1] and immediately match the PIN again. Similarly with a PIN of {2,3,2,3} … the buffer would go: [2,3,2,3] to [3,2,3,2] and then [2,3,2,3] – therefore matching the PIN without only 2 digits input.


So the rolling buffer “last L digits” approach is solid…?

Well, as I mentioned in the Topic overview, if you are concerned about level of security of the code based on the number of buttons and PIN length, it is essential to understand the particular risk of this approach in how it reduces the maximum number of attempts required to hit every possible sequence. This link on De Bruijn Sequences explains it very well. There are still a substantial number of unique sequence permutations, but it is advisable to use a bit longer PIN length than if a “start and/or end” indicator is used.

The actual count of distinct permutations can be calculated with the formula: k=number of buttons:4, n=PIN length:
de Bruijn sequence - Wikipedia

1 Like

I will be updating the README.md and the Topic post with some typical “Use Cases” that I had in mind when developing this App. But some short answers below…

  1. The primary use case I had in mind is to imitate the “traditional” Home Alarm Deactivation keypad panel. I’m sure you know these wall mounted central control units that folks have to run to input their PIN within 60 seconds or so of opening the front-door when they return home in order to avoid the sirens going off and police being called. In this Use Case, a button controller (like a Minimote) would live inside the house near the entry door(s).

  2. Taking the device with you would add a level of security (and it is certainly possible to give every member of the family their own Minimote, with the same or different PINs). This would turn the Minimotes into 2-Factor authentication devices (i.e., something you have + something you know). I don’t think battery life would be an issue: As far as I can tell, the Minimotes do not poll or ping the Hub – they are passive devices that only connect with the hub and send events when a button is pressed. Does this sound like the actual behavior?

  • Why would a button device be polling or pinging the hub as you suggest it might?

Presuming no unnecessary polling, the documentation rates the battery life at:

"5 months before requiring a recharge (based off a typical usage of 10 radio commands a day)".

Great suggestion … I already have some sort of “failed attempts handling” features in mind.

A threshold for failed attempts tolerance can certainly be based on a count of button presses between PIN match successes, and that could be a factor of the PIN length (a longer PIN means that “legitimate” incorrect sequences are more likely to be input, and the more complex PIN also tolerates more brute force attempts). It can be a user configurable quantity.

The question remains as to what action(s) should be triggered by too many failed attempts? One or more of:

  1. Set off a “silent alarm” in the form of a Push Notification and/or Text Message, neighbor and police notification, …

  2. Set off an audible alarm, as if an actual security breach has occurred.

  3. Lock out (i.e., “ignore”) further attempts for a period of time (60 seconds? 5 minutes?).

  4. Add dynamic complexity, such as requiring that the correct PIN sequence be input 3 times consecutively with no errors. I rather like this option as it is somewhat intuitive. If an intruder is trying to brute force the PIN, then they are unlikely to attempt the same sequence more than once. If we dynamically activate “3 times mode” after a number of failed attempts, then it adds considerable security – while: still keeping the system “intuitive” for the valid user. What’s the first thing anyone is going to do if their PIN code entry fails to trigger? Try again, of course! And if they know that in certain circumstances inputting the PIN 3 times is required, then that is a rather natural procedure to follow, right?

…CP / Terry.

NB: I have updated the official pre-release to: v0.1.2-beta
(latest always shared in the IDE list or get release or master from GitHub link)

Key Changes (more detail pending…):

  • Support for ZWN-SC7 Enerwave 7 Button Scene Controller; based on driver and testing by @mattjfrank; Other button controllers supported with correct number of buttons if they supply attribute: numButtons string (otherwise, default is buttons #1 to #4 only).
  • Preferences GUI format changes.
  • Added instance naming: NB: Multiple instances can be mapped to the same Button Controller; just use distinct, non-overlapping PINs. Each PIN can be assigned the same or different actions. For example:
  • give out different PINs to different people so that you can disable one if required.
  • give different actions to different PINs, effectively allowing your 4 button controller have a distinct PIN for each of 16, 64, or more actions; though you need to install a separate instance of the SmartApp for each PIN.

…CP / Terry.

1 Like

Awesome app. I think integrating this keypad function into the Smart Alarm app would make a lot of sense.

1 Like

All you need to do is to use this app to switch modes.

1 Like

Yup – that’s definitely the way that Modes are typically used and why I included them in “ButtonsAsPIN”.

However, beware that Modes have a slight security risk; they are not limited to specifically authorized SmartApps or OAuth’d services (unlike individual Device Instances), so…

Read more here:

Yeah I’m doing that already but since the smart alarm app already has controller support adding in the pin function makes sense.

@tgauchat - Hi, I am very new to Smartthings. I got my security system up, and all I am missing is the remote portion. I have the Aeon Labs G1.1 and bought it exclusively for your program. The only problem is that I got to the “Safety & Security” category and I don’t see the app to install. Am I missing something?

Thanks for your help.

1 Like

Hi Brian … welcome to SmartThings!

I presume you are looking for this SmartApp directly on your mobile device? You won’t find it available there, yet, as it is not a certified published SmartApp (SmartThings takes a while to add SmartApps and SmartDevice Types to the stock libraries).

So you need to login to the API/IDE page and paste the code as a new personal SmartApp, and use the Publish “For Me” option … then it will appear under “My Apps” on your phone.

There are probably some Topics here on the forum that describe those general SmartApp - IDE Installation steps in more detail… Ah … but wait, there’s actually a video by another Community Member! (Thanks @scottinpollock!):

You are welcome to Private Message me with any questions, Brian, and we can even Skype a bit to walk through the installation.

https://www.youtube.com/watch?v=D6rG4mk164M&feature=youtu.be

Thank you so much! I actually got the app installed in “my apps”. One question. The question in your app “activate for specific modes.” Is this the mode that my security system will go into if I successfully put the right pin code in? Currently, the alarm is set to go off in away mode when a sensor is tripped and does not go off when in home mode. Thanks for all your help, and writing this app :smile:

Glad you got the SmartApp installed, Brian!

That particular option in the SmartApp is one that is common to many SmartApps … it is a filter to restrict the app from being active “at all” except during the specified Mode(s). I am not sure if this option will remain in my app because it is not particularly useful in this context. The most common use of the Mode filter in a SmartApp, of course, is to ensure that Motion or Contact sensor Alarms are only active at Night or Away; and Light activation apps are only active at Night, etc…


I believe that the Use Buttons As PIN SmartApp lets you choose various Action Types on the 3rd Preferences Panel, and the Actions Types include:

  • Trigger Hello Home Action
  • Set / Change Location Mode

NB: The second choice of directly setting a Mode is not currently working on my mobile installation – perhaps it is related to some of the recent platform bugs.

So … Before configuring my SmartApp, you can use the Dashboard / Hello Home, Gear, Add An Cction to Create a Hello Home Action called “Disable Alarms” or similar and Hello Home Actions have a parameter to set the Mode.

Let me know any questions or if you’d like a walkthrough.

Hi all, I’m new but looking to setup a Smart Things system on my new home. I landed here because a keypad system is critical for me. My Mother In Law will need to use the security system and would not likely be comfortable with smart device control. Has anyone looked into the following pinpad controller and determined if it will work with the above App:

http://resolutionproducts.com/products/keypads-and-peripherals/pinpad/

It seems to connect with a lot of Z-Wave devices but Z-Wave compatibility wasn’t advertised. As it has some additionally buttons, it could basically act like a typical security system input. Thanks for all the great work you guys are doing.

-Matt

Hmmm… Nice find; but the specs are rather sparse. Only certain types of Z-Wave Scene Controllers are compatible with SmartThings (long story … Ummm… there’s some good threads on that issue). Any pricing? Sometimes it’s worth the money just to try.

The 2GIG brand seems to have the greatest likelihood because a lot of 2GIG is Z-Wave.

But…

If it is compatible with this below, then it won’t work, these are low frequency RF 345Mhz transmissions to a central panel, not Z-Wave or ZigBee. I think those frequencies are typical of standard alarm system panels… SmartThings is a new generation. Haven’t found a good keypad yet. The MiniMote’s not bad though!

http://www.smarthome.com/2gig-technologies-2gig-pad1-345-wireless-keypad.html

This is fantastic. Thank you for sharing.

I am new to ST so please excuse me. Would this setup allow me to arm / disarm the Smart Home Monitor?

You also say it is beta? But will it work? Please excuse the basic questions!

Thanks.

1 Like