Goal
Let Domoticz see and be able automate from events in any Google Calendar (private or public). You won't have to create a special calendar for your home automation and you won't put automation related logic in the calendar.
Why would I want to do automate my Google Calendar
Your imagination is the limit
Maybe you would like to:
- Slowly dim up the light in your bedroom based on a work schedule in Google Calendar
- Disarm the entrance door if someone booked the laundry facilities room
- Turn Your partners "motorvärmare" (block heater) on 3 hours in advance of her his/her working schedule
- Turn on Your TV when Tampa Bay Buccaneers are playing
- Turn of the house heating whenever there is a public holiday in Thailand
- Be informed in your Sono's system one hour in advance if you are going to attend a meeting
Stage of development
The initial code from which BGCD derives, has been tested by many users on another HA platform. It's currently running well on Domoticz on Raspberry Pi and Synology hardware. There are currently no known issues. Don't use this software in situations where a software failure or a drop of internet connection can lead to any kind of damage or disturb your relation to your wife (or husband).
Your feedback is important. Please report any problems that you may encounter. You might as well post a reply here also if you haven't got any questions or encounter any problems.
Components used
- Domoticz
- Raspberry Pi running Debian Wheezy or a NAS running Synology*
- Running Domoticz installation
- Stable Internet access
- A personal or a public Google Calendar
Synology (Only if your Domoticz is running on a Synology NAS) (Skip this block if You are using a Raspberry Pi)
1) Add a user variable named GCalHostAndPort of the type string and enter localhost:8084 as the value.
2) The folder /home/pi/domoticz/scripts/lua/ does not exist. When that folder is mentioned in this guide,
use folder /usr/local/domoticz/var/scripts/lua/ instead.
3) The folder for the credentials file /home/pi/domoticz/GCal3/ will not exist. When that folder is mentioned in this guide,
use folder /usr/local/domoticz/var/GCal3/ instead
Google Credentials
You will need explicit credentials (service account) as well as an ID that identifies the calendar you wish to access.
You will also need to share the calendar with your service account. Stuart made an excellent description to help you do that. It's published here with his permission. Download the Setting up a Google V3 API Service Account.PDF
When you have finished, you should have a credentials file named GCal3.json
Next get a Calendar ID for the calendar you wish to use. Again we rely on Stuart's work. Download the V0.9 - GCal3 PDF and follow page 1-2 and You'll have the calendar ID ready.
Setting Up Domoticz
For each calendar that You wish to access: Create two virtual Sensors of the type "Switch" and one of the type "Text" (See the FAQ configuration section if You are not sure how to do that)
Name the first virtual switch device GCalCheck MYCALENDARNAME. (Replace MYCALENDARNAME with whatever you call your calendar) This device will be referred to as the "Check Switch" You will use this switch later whenever you manually want to make the script check for calendar updates.
Name the second switch device GCal MYCALENDARNAME. (Replace MYCALENDARNAME with whatever you call your calendar) This device will be referred to as the "Calendar Device"
Name the text device Status MYCALENDARNAME. (Replace MYCALENDARNAME with whatever you call your calendar) This device will be referred to as the "Text Device"
(You are free to name the devices to whatever You like but if You start with something similar as described above you are more likely not to become confused later, especially if you decide to access multiple calendars. It's recommended to start with a single calendar first)
Download the attached file Calendar.zip and go to Setup -> More Options -> Custom Icons and upload it.
Edit the Calendar Device, choose the Calendar Icon as the Switch Icon.
Now edit the Switch Device, set an off delay of 2 seconds.
Download the gcalconfig.zip file. It contains 1 lua script file in which you will make your configuration. Extract the file into the /home/pi/domoticz/scripts/lua/ folder.
Also download the latest GCalDom-*-*-*.zip file. It contains a couple of lua script files. Extract the files into the Lua scripts folder, /home/pi/domoticz/scripts/lua/
Now, edit the gcalconfig.lua script. Fill in the names of the 2 virtual switches and the text device that You entered above. You must also enter the correct idx-numbers for each device. If You go to the Setup / Devices page, You can find the idx numbers.
Note! It's simply necessary to spell the names Exactly as you entered them when naming the virtual devices, otherwise it will not work. Also, note that if You later decide to rename your virtual devices you'll have to remember to edit the configuration file.
(Below is part of the configuration file)
Code: Select all
-- User configuration START
checkSwitches = { names={"GCalCheck MYCALENDARNAME"}, idxs={"11"} },
calendarDevices = { names={"GCal MYCALENDARNAME"}, idxs={"53"} },
textDevices = { names={"Status MYCALENDARNAME"}, idxs={"52"} }
-- User configuration END
Multiple Google Calendars? No problem ... Here is an example using two calendars. Just repeat the names separated by comma. Then repeat the idxs and remember to have the same order as the names....
You can use a maximum of 24 calendars.
Code: Select all
-- User configuration START
checkSwitches = { names={"GCalCheck MYCALENDARNAME", "GCalCheck MYOTHERCALENDARNAME"}, idxs={"11", "12"} },
calendarDevices = { names={"GCal MYCALENDARNAME", "GCal MYOTHERCALENDARNAME"}, idxs={"53", "52"} },
textDevices = { names={"Status MYCALENDARNAME", "Status MYOTHERCALENDARNAME"}, idxs={"48", "49"} }
-- User configuration END
If you have protected Domoticz with Username/Password, you must temporarily put it back to default (no password required) before doing the next step. You may activate password protection again later.
Push the "Check Switch" to run the script for the first time.. If everything goes well 25 user variables with names like "GCalnnSomeText" will be created. nn corresponds to the device idx number of the Calendar Device. (If no user variables were created, check again that your Domoticz site is not password protected)
Now, put the credentials file named GCal3.json that You prepared earlier in /home/pi/domoticz/GCal3/
Setting up user variables (The mandatory ones)
(where nn is the device number of Your Calendar Device)
- Set the user variable named GCalnnCalendarID to the Calendar ID that you've noted above.
- Set the user variable named GCalnnInterval to how often you want the script to synchronize with google calendar. Keeping the default value of 180 minutes is a good practice since we don't want to SPAM Google with too frequent request. (You risk to have Your service account shut down) The script will always update whenever there is an event start, an event ending and at midnight. If You have several calendars you can set this variable slightly different from each other to avoid race conditions.
(where nn is the device number of Your Calendar Device)
- Set the user variable named GCalnnignoreAllDayEvent to true or false (Don't use quotation marks and don't capitalize).
- Set the user variable named GCalnnKeyword to only trigger on certain Calendar Events.
- Set the user variable named GCalnnexactKeyword if you only want to match the exact keyword given.
- Set the user variable named GCalnnStartDelta and GCalnnEndDelta in minutes if You want to trigger earlier or later than what is entered in the calendar. Can be very useful. Value can be negative.
- For even more options, it's all documented in Setting up a Google V3 API Service Account.PDF that You've already downloaded.
Therefore, if You need to remove the text from a text user variable You can write Code: Select all
Empty StringYou are ready to go.
Push the "Check Switch" to run the script again. If everything goes well you can see information about upcoming events in the "Text Device". If not, You will probably see some useful debug information in it. If things are not working as expected read about debugging and troubleshooting below.
Turn off debugging
If everything works just as you expected, You should turn off the debugging messages. They are enabled by default. Set the user variable GCalnndebug to 0.
Automate things...
Use Blockly to trigger on the state of the "Calendar Device". It will be "On" when a calendar event is active. It will be of when there is no calendar event active. If You prefer to write your own device scripts you can do that too of course.
Advanced scripting (Json encoded array of pending valid events)
As You may have noticed, there is no user variable named GCalnnjsonEvents. It's because of a length limit in Domoticz. I have chosen to store the jsonEvents in /home/pi/domoticz/GCal3/events.json You may script whatever you wish using that file.
GHANGE LOG
V 1.0.2 New location of the credentials folder for Synology systems.
Better detection of path for Domoticz install directory and script directory.
Setting the package.path before including files using "require" for
improved compatibility.
V 1.0.1 Removed the check for openssl since the command differ on different unix systems.
Added CalendarID as part of the json Events file name to allow multiple instances.
Fixed so that the events.json file is written using valid json syntax.
V 1.0.0 Fixed: Text device did not update if authentication used on Domoticz.
V 0.1.4 Corrected so that the preferred debug level always is fetched from the user variables.
V 0.1.3 Changed so that calendar data refreshes using a time script instead.
V 0.1.2 Introduced separate "at" queues for each calendar.
V 0.1.1 Fixed format when no more events were found.
Corrected the version displayed in debug messages.
Added a script for initialization of the calendar scripts after system boot.
V 0.1.0 Initial version
UPGRADE INSTRUCTIONS
To upgrade from a previous version, just download the latest GCalDom-*-*-*.zip and extract the files into the /home/pi/domoticz/scripts/lua/ folder (overwriting the older ones). DO NOT download gcalconfig.zip again!
Only If You are upgrading on a Synology system V 0.1.1 or older:
run command mv /root/GCal3 /usr/local/domoticz/var/GCal3
Only If You are upgrading from V 0.1.2 or older:
If You installed the "at" package just for the purpose of this calendar script you may now remove it if you wish.
(sudo apt-get remove at). You may also delete the script file systemstartgcal.lua if you wish, it's not needed.
DEBUGGING AND TROUBLE SHOOTING
BGCD has three levels of debug messages (1-3). A value of 0 will turn off debugging. Initially the user variable GCalnndebug is set to 3. (Make sure to set it to value 0 after debugging as it clutters the log) Open the Domotic Debug in a new browser window. (Setup->Debug) Resize and put the new debug window side by with your ordinary Domoticz browser window so that you can see all the debug messages. Press the Check Switch to see what will occur in the debug window.
If You need help it's very likely that we'd like to see some BGCD related debug output from your debug window.
If You have problem to get BGCD running initially, the most likely cause is that You've misspelled something or entered wrong device idx in the gcalconfig.lua. Then go to Setup -> Devices. (Filter to see only your 3 BGCD virtual devices by entering the Calendar name in the search box). Check again that the 3 device names You've entered into gcalconfig.lua match exactly as they appear in your device listings. Also check the idx-numbers. They must match.
If still nothing happens when you push the Check Switch the Text Device only shows "Hello world", post a request for help in this thread and copy the contents of Your gcalconfig.lua together with the output from listing your 3 BGCD virtual devices.
UNINSTALLING
- Delete the file named script_device_gcal.lua (You will find it in directory /home/pi/domoticz/scripts/lua)
- Delete the file named script_time_gcal.lua (You will find it in directory /home/pi/domoticz/scripts/lua)
- Delete the file named gcalconfig.lua (You will find it in directory /home/pi/domoticz/scripts/lua)
- Delete the directory named GCal3 (You will find it in directory /home/pi/domoticz/)
- Delete all the Domoticz user variables that have names that starts with GCal. (You can filter the devices in Domoticz)
- Remove the virtual switch device GCalCheck MYCALENDARNAME. (Replace MYCALENDARNAME with whatever you called your calendar)
- Remove the virtual switch device GCal MYCALENDARNAME. (Replace MYCALENDARNAME with whatever you called your calendar)
- Remove the virtual text device Status MYCALENDARNAME. (Replace MYCALENDARNAME with whatever you called your calendar)
