Control Locks based on Calendar Events using HomeSeer

[toonwolf]

Denne guiden beskriver "The ToonWolf solution". Grunnen til at den er skrevet på engelsk er fordi Planyo som er brukt i dette eksempelet har vist interesse for denne løsningen. Det som jeg mener er "unikt" med denne løsningen er at den er så åpen! Andre tilsvarende løsninger er utviklet enten mot et spesielt system eller en lås. Med GCalSeer og HomeSeer står du mye friere. "Ulempen" med slike åpne løsninger er ofte at de krever mer tilpasning for å fungere med akkurat ditt system, men om du er interessert i hjemmeautomasjon og har litt kunnskap bør det være mulig å tilpasse dette. De fleste "store" leverandører av bookingsystemer tilbyr også tilsvarende løsninger i en eller annen form, ulempen med disse er jo selvfølgelig at du "låser" deg mot dette systemet og det vil være mye vanskeligere å bytte til et annet system siden du også må bytte lås, lysstyring osv. Om du ikke har behov for akkurat dette så viser det hva som er mulig å få til med HomeSeer og GCalSeer. Kanskje du blir inspirert til å gjøre noe annet? Takk til @Guahtdim og @Moskus for hjelp til å utvikle denne løsningen.

 

Control Locks based on Calendar Events using HomeSeer

 

In this documentation you will find instructions for how to control one or more electronic code locks based on events in one or more online calendars. You will also learn how you can add and remove codes to electronic locks based on reference numbers.

 

These instructions are based on using the reservation system Planyo with a booking reference number starting with a “R” followed by a 7 digit number, but can be used with any other booking system that creates a random booking reference number. The reason why I made this guide is because I could not find a good automatic code lock system that could be used with Planyo. You can also in theory create your own random codes and use these instructions to create an automatic system for other booking systems that does not provide a reference number.

 

Disclaimer

 

This documentation is provided “as is” and is free for anybody who would like to use it. You may not sell or copy this documentation. Please contact the author of this documentation @toonwolf for more information. The HomeSeer plug-ins GCalSeer and TwilioSeer is developed by @Guahtdim and is provided free of charge. The script used to create PIN codes in the locks was created by @Moskus

 

Who is this guide for?

 

You would like to:

 

• Automatically unlock or lock a code-lock x minutes before or after the event/booking starts and/or ends

 

and/or

 

• Give your customers the option of unlocking an electronic lock based on a number in their booking reference. You can decide for how long before and after the code shall be valid. A SMS is sent to the customer x minutes before the event starts with the code

 

You can use these as separate methods for controlling lock’s or in conjunction. Example: You would like one of your lock’s to be open during daytime or specific activities, or you would like your customer’s to only have access to another lock with a valid code. It is not required, but a good understanding of HomeSeer and home automation systems is recommended and will really help as 99% of this guide involves working with devices and events in HomeSeer.

 

What you need

 

• a booking system that supports synchronizing booking’s as events to either Google Calendar or Outlook Office 365 Calendar. Planyo with the Google Calendar extension is used in this documentation
• a licence for HomeSeer and a PC to run it on (HS normally cost USD 250,- for a license, but normally goes on sale twice a year. You can get 50% off during May and November.
• The HomeSeer plug-in’s GCalSeer and TwilioSeer. GCalSeer and TwilioSeer is under development, and the latest version is therefore only available for download from hjemmeautomasjon.no (Norwegian home automation forum). All of these plug-ins are provided free at no cost. This guide does not explain how to install and configure any of these plug-ins.
• An electronic code lock with Z-wave communication compatible with HomeSeer. In this example an ID Lock 150 is used, but it should work with any other electronic code lock controller as long as it’s compatible with HomeSeer. An example of such a controller is UMV3 from Danalock that can be used to control any electronic lock
• A BudgetSMS account

 

Automatically unlock and lock a Code Lock x minutes before and after the event/booking starts and ends.

 

This is the easiest and most convenient way of giving your customers access to your premises. However this is not as “secure” as the second option that require your customers to unlock using a code created from their booking reference.

 

The behavior of the GCalSeer plug-in will be:

 

• The plug-in will check if there are Calendar Events that matches the rules set by the IF command.
• In this example “trigger-words” in Calendar Events are used to trigger HomeSeer Events, but you can choose other options like “Any Event”

 

1. Create a VIRTUAL DEVICE used to TRIGGER events
   
   Create a Virtual Device in HomeSeer for each lock you would like to control. Name it “LockControl (name of lock)”. In this example I have created a virtual device with the name “VT-ANK-IDLOCK-UNLOCKED”.
   
   This virtual device will be used to control events that automatically unlock/lock the lock.
    
2. Create EVENTS used to UNLOCK and LOCK the Lock
   
   Create an Event that sends parameters 5 and 1 with value 0 that will Unlock the lock and prevent it to automatically lock after it has been unlocked, and also not to lock when the door is opened and closed. If you are using a different lock than the ID Lock 150 you will have to send other parameters to the lock.
   
   In this example I have created an event with the name“ANK LOCK ID150 set UNLOCK and MANUAL”. Also in this example a Fibaro RGB Controller is used to control a LED strip that will show if the door is locked (red) or unlocked (green). Another event is triggered that will play a message over loudspeakers that the door has been unlocked. The wait command is used to give the lock time to handle the different commands. If you would like to be notified when the event runs then you should add an action like “send pushover message”.
   
   Copy the event you just created and edit the new event with the following values:
   
   Notice that in this event you are locking the Lock and also turning off “always open” making it so that the lock will automatically lock if it is unlocked by sending parameter 5 and 1 with value 1 to the lock. This event will be triggered once the virtual device “VT-ANK-IDLOCK-UNLOCKED” changes and becomes “Off” (the end time of the event with offset value)
    
3. Create EVENTS that will trigger on events from calendar(s)
   
   Create an Event using an “IF” from the “GCalSeer” plug-in. This plug-in is used to trigger the event based on events from your Calendar(s). You can choose to trigger the event to unlock on any event or by using certain “trigger-words”
   

• In this example we are using “trigger-words” entered into “the text: box. You can have several words separated by a | Example: WORD1|WORD2|WORD2
• Choose “now” in Occurs and Offset Trigger “before” and how many minutes before the event you would like the lock to automatically unlock. In this example the event will trigger 15 minutes before the start time of the Calendar Event
• The “And if” ANK VIRTUAL VT-ANK-IDLOCK-UNLOCKED has a value equal to Off is used to prevent this event to run in loop
• You can send a push-message to your phone when this event runs using Pushover
• finally this event will set the virtual device “VT-ANK-IDLOCK-UNLOCKED” to value “On”. This will trigger the other event you made earlier that will unlock the door, and also turn off automatic locking making sure the lock is unlocked as long as the event is active 
  
  Copy the Event you just created to make a new Event that will trigger AFTER the found event with offset x minutes after the end time of the event. In this example the Calendar Event will be triggered 15 minutes after the event time. Adjust the values to “Trigger” AFTER and “Do not trigger on adjacent events”. If you you have adjacent event, you do not want the lock to unlock/lock in the middle of another event! Change the “And If” to “On” to prevent the event from running in a loop.
  

CONCLUSION

 

You have now created 1 virtual device and 4 separate events that will automatically unlock and lock your electronic code lock x minutes before and after an event occurs in your electronic calendar. There is no need for your customers to use a code to unlock your door. The lock will be unlocked during the whole event so if you think this solution is not “safe enough”, then read on to learn how to create events that will extract the booking reference from your event and create a 4 digit code for the electronic lock.

 

Create user codes from a booking reference number in Planyo

 

With this method you can give your customers or guests the option of unlocking an electronic lock based on a number in their booking reference. You can decide for how long before and after the code shall be valid. A SMS is sent to the customer x minutes before the event starts with the code that will be programmed by HomeSeer into the lock.

 

A code (the last four digits of the booking reference) will only be written once to a virtual device. If two identical codes are created during the same period, then only one virtual device will be updated.

 

The behavior of the GCalSeer plug-in will be:

 

• All events with reference numbers are checked by using the reg. ex code. If the plug-in finds a reference number matching the code, then the code is extracted
• If the code has already been added on one or more virtual devices, the plug-in will quit since the code is already set. The plug-in is active in 1 minute to make sure all events are checked
• If the code is not found on any virtual device then the code will be added to the device that has not been updated for the longest time.
• If the plug-in is set to delete after the event ends, then the code is set to 0 in the matching virtual device

 

The plug-in will only update virtual devices once, even though the trigger runs several times within the minute it matches.

 

Make the necessary changes in Planyo

 

If you are using Planyo as your booking system and would like to control locks based on reservations, then you will have to make some modifications in order to 1.) trigger events in HomeSeer and 2.) make information from the booking in Planyo available in your Google Calendar so that GCalSeer can extract the information. You need the Planyo Google Calendar extension for this to work.

 

Depending on what you will use this for you will need to add a “trigger-word” to the Calendar Event. We are using this for allowing automatic loan of rackets and balls. When someone book a Tennis Court they can tick a box “Gratis ulån racketer” (free loan of tennis rackets) and this will add information to the booking and in turn add this in the Calendar Event as “Gratis utl  n racketer”. Here is an example of how a customer will see this on the booking page

You can easily add this tick box in Planyo by modifying the Reservation form layout (Site Settings | Reservation form layout) and add a new item. Choose “Checkbox (Yes/No” and enter the name like this

 

You also need to make modifications to the Google Calendar extension in Planyo

 

1. Go to the Google Calendar Extension
2. “Go to the setup script”
3. “click to change the configuration”

 

Make the following changes in the description template for exported reservations. 

 

[fname]$(first_name)[/fname]

[lname]$(last_name)[/lname]

$(email)

[phone]$(phone)[/phone]

 

Add as many placeholders as you need. A minimum should be $phone as this will be used to send out SMS with the Lock code. The [xxxx]yyyyyy[/xxxx] is a datatag used by GCalSeer to extract and identify the information from the Calendar Event. This is how the template should look like after you have finished adding the variables from Planyo:

 

Here is an example of a calendar event where the customer has chosen “Gratis utlån racketer” in a reservation in Planyo:

Create Virtual Devices in HomeSeer

 

You must create several Virtual Devices in HomeSeer. The number of virtual devices depends on how much information you will be using and also how many calendar events you are likely to have in the same period. If there is a chance there are 2 or more events at the same time, you should at least have 3-4 groups of virtual devices. If you all your virtual devices are “busy” as placeholders for the information from your calendar events then you will run into problems.

 

Each virtual device will be a “placeholder” for the extracted Code, Emailadress, Firstname, Lastname and Phonenumber from your Calendar. The number of virtual devices you need depends on how many events you have or codes you will create.

You also need to change the “Status Graphics” for virtual devices. I recommend you start off by creating one virtual device with these settings and then copy them.
 

Create your first virtual device

You need one “single value” with value 0 that will be a “Off” status. Then you need a “range value” with the start 1 and 9999 as value. enter “On” as prefix. This will automatically turn the virtual device “on” whenever a code has been extracted from the event and the virtual device has been updated with the value (lock code)


If you would like it to look “pretty” you can also add status graphics for the virtual device making it easy to see when the code is active. Enter “0” for the off.gif and range “1” to “9999” for the on.gif

 

When you are finished you can copy this virtual device to as many as you need. I have chosen to have 3 groups of codes. “Group 1” consist of the following virtual devices:

 

• “VT-LOCK-GROUP1-CODE” (placeholder for the lock code)
• “VT-LOCK-GROUP1-EMAIL” (placeholder for the email of the customer)
• “VT-LOCK-GROUP1-FNAME” (placeholder for the firstname of the customer)
• “VT-LOCK-GROUP1-LNAME” (placeholder for the lastname of the customer)
• “VT-LOCK-GROUP1-PHONE” (placeholder for the lastname of the customer)

 

The number in the name example VT-LOCK-GROUP1-CODE (634) is the device number in HomeSeer that you can add in the name. Makes it easier to identify the device for later.

 

Then you need to copy and make as many virtual devices as you need. I have a total of 15 virtual devices in 3 different groups

Then you need to create a virtual device that will trigger your events. I use this for racket loan in our Tennis Club and this virtual device will be turned on if a calendar event is found with the word “UTLRACK” in a calendar event

 

Create Events in HomeSeer
 

You also need to create at least 3 events in HomeSeer depending on how many groups of virtual devices you have. If you have 3 groups (recommended), you need 8 events:

 

Event 1: This event will trigger on a calendar event START and add found codes and update information (datatags) from your calendar to virtual devices in your groups. GcalSeer will automatically choose the group that does not have any data. If it finds that the information already exist, then GCalSeer will not run

Event 2: This event will ADD code from GROUP 1  to the lock and send SMS

Event 3: This event will REMOVE code from GROUP 1 from the lock

Event 4: This event will ADD code from GROUP 2  to the lock and send SMS

Event 5: This event will REMOVE code from GROUP 2 from the lock

Event 6: This event will ADD code from GROUP 3  to the lock and send SMS

Event 7: This event will REMOVE code from GROUP 3 from the lock

Event 8: This event will trigger on a calendar event END and will check your group for matching datatags, if GCalSeer find a match, then it will delete values from the virtual devices in the group. This in turn will trigger removal of the code from the lock. 

 

Before you create these event you need to have installed the HomeSeer plug-in GCalSeer

 

Create Event that will be triggered by Calendar event START and update virtual devices (Event 1)

This event will extract information from the Calendar Event 30 minutes BEFORE the event starts and update virtual devices (reservation number, name of customer and phone number) and turning the virtual devices ON.

 

1. Create an event using the GCalSeer plug-in that will trigger on Calendar Event Start. If you would like to trigger on all events choose “Any Calendar Event”, If you would like to only trigger on a reference number starting with the letter “R” followed by a 7 digit number you must choose “A calendar event has a summary text matching a regular expression: R\d{7}.
   
2. Select the calendars the event should look in by choosing the calendars
3. Choose Trigger when event occurs “now”
4. If you would like to use “offset”, select how many minutes or hours before the event starts you would like the code to be active. In this example the event will trigger 30 minutes before the event starts in order to send a SMS with the code to be used for unlocking the door
5. Choose “Use regular expression handling”. This will enable you to add the handling logic that will extract the information from the calendar event. Add the handling logic you require. As a minimum you need to add the 4 last digits of the reference number as this will be used to create the lock-code and the phone number that will be used to send the code using SMS (TwilioSeer)
6. Add a new handling logic by choosing “RegExp”, in the Regular expression box enter “R\d{3}(?<Number>\d{4})”.
7. The booking reference number is found in the Summary. Select “Summary” in “Inspect summary or description”
8. Choose “Number” in Regexp group name
9. In “Devices to update” enter the reference number of the Virtual Devices for the codes you created earlier in this guide separated by a comma. Example 634,635,699. This handling logic will extract the 4 last digits in the 7 digit booking reference and update the above mentioned virtual devices if the event is triggered.
   
10. You also need to at least add the phone number that will be used to send the lock code. Add a new handling logic but this time choose “IdentifierTag” and [] as “bracket types”
11. Choose “phone” as Tag name
12. The phone number is found in the description of the calendar event so choose “Description” in “Inspect summary or description”
13. In “Devices to update” enter the reference number of the Virtual Devices for the phone numbers you created earlier in this guide separated by a comma. Example 703,704,705. This handling logic will extract the phone number and update the above mentioned virtual devices if the event is triggered.
14. Finally you need to set the regular expression (code) as “master” making all the other “slaves” of the master handling logic. 
     

When you are finished the IF condition should look like this

 

Collapse the event in order for HomeSeer to validate your event

 

There is no need to add “Then” logic in the event as the “If” logic of GCalSeer will update the virtual devices. You will now create an event that will be triggered when the virtual devices used to store the lock codes is updated (turned on).

 

Create Events triggered by virtual device turned on

 

This event will update one lock 30 minutes before the event starts with a code that is extracted from the last four digits from the reservation number in Planyo and send this to the customer by SMS. If you have 3 groups of virtual devices (recommended), you need one event for each group. First create an event for the first group. When you have done this copy the event for group 2 and 3

 

1. Create a new event and choose IF “VT-LOCK-GROUP1-CODE” changes and becomes a value in the range of On to On. This event will then be triggered whenever the virtual device for the lock codes is updated (turned on)
2. Add a new Then “Run a Script or Script Command”. I recommend you create a new script in the “/scripts/” folder in your HomeSeer folder and select this. In this example a script by @moskus will be used to add the value from Virtual device “634” (VT-LOCK-GROUP1-CODE) to code location “82” and named “VT-LOCK-UTLRACK-GROUP1-CODE”.
   
   Variables you need to change:

 

• “Dim interfaceID As String = "955BFE54AEE6" is used to identify the ID of your Z-wave node and can be found in the Z-Wave.ini file located in \Config folder of you HS3 installation folder. Search for “Unique”. If you have more than one Z-wave controller, you will need to find the correct value of the controller of the lock you would like to update.
• “Dim place As Integer = 82” is the code location in your lock
• “Dim PINstring As String = hs.DeviceString(634)” is the reference ID of the virtual device
• “Dim nodeNumber As String = ZwaveUtil_GetNodeIdByRef(647)” iis the device reference number of the lock.

Sub Main(ByVal inputArgs As String)

        hs.WriteLog("Add user", "Adding user...")
        Dim interfaceID As String = "955BFE54AEE6"
        hs.WriteLog("Add user", "InterfaceID: " & interfaceID)
        Dim place As Integer = 82
        Dim PINstring As String = hs.DeviceString(634)
        Dim nodeNumber As String = ZwaveUtil_GetNodeIdByRef(647)
        Dim configResult = hs.PluginFunction("Z-Wave", "", "AddUserCodePin", {nodeNumber, place.ToString, PINstring, "VT-LOCK-UTLRACK-GROUP1-CODE", interfaceID})
        hs.WriteLog("Add user", "Done with result " & configResult.ToString)
        hs.Writelog("Add user debug", "nodeNumber: " & nodeNumber & ", place: " & place.ToString & ",  PINstring: " & PINstring)
    End Sub

    Public Function ZwaveUtil_GetNodeIdByRef(ByVal deviceId As Integer) As Integer
        Dim nodeId As Integer = -1
        If (deviceId > 0) Then
            Dim device As Scheduler.Classes.DeviceClass = hs.GetDeviceByRef(deviceId)
            If (device IsNot Nothing) Then
                Dim pdata As HomeSeerAPI.PlugExtraData.clsPlugExtraData = device.PlugExtraData_Get(hs)
                If (pdata IsNot Nothing) Then
                    nodeId = pdata.GetNamed("node_id")
                End If
            End If
        Else
            Throw New System.Exception("Device not found: " + deviceId)
        End If
        Return nodeId
    End Function

Also select “Wait for script to finish before continuing” and  “Only allow one instance of the script to run at a time”

 

• Add a Then “TwilioSeer: Send a SMS
• In he the “Sms text:” box enter whatever text you would like to be sent. Here is an example Hi $$DSR:693:. Your code is $$DSR:634:# and is valid 30 mins before/after your reservation. This will send a text message with the lock code (634) and the firstname (693) will be added to the SMS message
• In “Advanced options” choose “Send to number found in a device”
• In “Time to live” choose 5 minutes. TwilioSeer will then try to resend the SMS for 5 minutes if it cannot be sent when the event is run
• In “Device for picking up receiver phone number” choose the Virtual device that is the place-holder for the phonenumber from the calendar event
• In “How to interpret the found number:” choose “Planyo format - (ex (47) 12345678)
  

Create Event triggered by virtual device turned off

 

This event will remove the code from one or more locks 30 minutes after the event has ended.

 

Create a new event and choose IF “VT-LOCK-GROUP1-CODE” changes and becomes a value in the range of On to On. This event will then be triggered whenever the virtual device for the lock codes is updated (turned on)

 

Create Event that will be triggered by Calendar event END and update virtual devices

 

This event will extract information from the Calendar Event 30 minutes AFTER the event starts and REMOVE values from virtual devices (reservation number, name of customer and phone number) and turning the virtual devices OFF. When the virtual devices are turned off this will trigger another event that you will create later that will remove the code from the lock.

 

1. Copy the event you created in the previous step. Use the “Copy this Event” in HomeSeer
   
2. In your new Event Select “Trigger after” in Offset
3. Edit all Handling logic and select “Delete found result” and click “Save updated”
   

 

Edited October 31, 2019 by toonwolf