Plugins/iCal.html

iCalendar integration into Domoticz

iCal Multi Purpose Multi Language Python Plugin for Domoticz

Main Features

• iCalendar integration: work with Google Calendar / Outlook.com / local : any ics file
• Generate Holidays : customizable by adding day from your calendar
• Generate At work switch : manage your work time, to help to design custom scenario
• Can execute Domoticz command on device : switch / push / rgb / level

Extra:

Should it Rain in next Hour ??

• Device specific to French people: data received from Meteo France / predicate rain for the next hour

And all of that: in your native language ( if language managed by googletrans python module )

iCal sources download

Installation

For Windows users

Download Setup.exe ( setup.exe /? for more options )

Run it as Administrator-- if something goes wrong screen will become "Red"

The download link provide to you all sources & necessary files.

For others

example on ubuntu 7.10:

Connect terminal session Type this commands :

sudo pip3 install googletrans
sudo pip3 install holidays
sudo pip3 install colour
sudo pip3 install icalendar
sudo pip3 install recurring_ical_events

go to your Domoticz folder, under plugins create iCal

mkdir iCal

you should now have something similar : ~/domoticz/plugins/iCal

got to iCal folder and copy these files inside it:

en_en_lng
iCal.sh
plugin.py
iCal.py

put the *py and *.sh as executable

chmod +x *.py
chmod +x *.sh

restart domoticz

sudo systemctl restart domoticz

All

Python version 3.x required & Domoticz version 4.102x or greater.

go to Domoticz / Setup / Hardware and select '

iCal Calendar tool for Domoticz

Configuration

for the configuration, lets focus on specific parameters to this plugin, for others, see Domoticz documentation.

• Name : Name you want to give to the Hardware
• Type : select iCal Calendar tool for Domoticz

• IP Address : Domoticz IP address or Loopback address, not need to modify, only if you know what you do.
• Domoticz Port : port that has been set for Domoticz, not need to modify, only if you know what you do.
• Listener Port : Port that will be used by the plugin listener. Used for communicate between process. Change only if already used by some other.
• Country, Province : used by the Holidays Device to calculate automatically all public holidays for this specific country. Province is optional and not available for all country e.g. France, Metropole or only France work
• State : can be necessary for some country like US. Used for Holidays.
• ics data gather command : enter here the URL to download the ics file or any script you want to execute to do the same job.
• Default to AtWork : if True, no need to put special keyword (#wrk#) to manage calendar entry as a work time period.
• Debug : value are , False, True, Medium. Level of information to put on Domoticz log for debug; In production, you need to put it on False.

User Guide

This plugin provide several Domoticz devices. All of them are optionals, this mean once installed, the one you do not want to keep/manage, just remove it. If all devices are removed, you will be warned into Domoticz log to remove the plugin. Access to an online or local Calendar is also optional.

iCalendar

One main device, iCal Status, give you the possibility to put the plugin in pause mode, this mean nothing will be downloaded/managed by the plugin until you click on it again, this put the plugin into resume mode. This mode will do a complete refresh of all plugin devices, and after back to normal working mode. You can use this feature every time you want to force a data refresh for testing for example. This device will also display usefull information on what's happend and what task is running.

By using the googletrans module, this plugin will create devices, labels & messages in your native language. The language will be stored in the uservariables and depend of course of the Lon/Lat you have set into Domoticz. This uservariable can be changed so you can always switch back to some other language if you want. Click here to see languages.

All necessary information are stored locally, this mean that plugin continue to work even if you have network/Wan problem. External network is needed only to refresh/update data from Calendar, this will be done automatically once Wan is coming back. But if you manage only local Calendar, this mean than no Wan connection is needed.

The refresh time is by default set to 60 minutes and stored into uservariable. You can change it and put any suitable value for you, but be warned that you need to let enough time to the plugin to do it's tasks between two refreshs. A low value is not really recommended for online calendar e.g Google / Outlook.

The main tasks are done by a second process that the plugin.py launch when necessary. In this way, Domoticz should never been blocked by long running transactions. The listener is used to receive feedback from this second process and store the information. This resolve also the problem that the plugin framework do not accept some modules, the modules are loaded by the second process which take care of all main tasks.

• How this work ?

The parameter ics data gather command say to the plugin how to store locally all information. If it begin with 'http', plugin will made a web request and download the file into plugins/iCal folder, otherwise, will launch a 'shell' process, in this case, this need to be writen by you (caution: should be non blocking shell, see plugins/iCal.sh). The file need to be on plugins/iCal folder and name need to follow this convention: <<HardewareID>>iCal.ics, where <<HardewareID>> need to be replaced by the ID that Domoticz had given to your just created Hardware.

Data are read after ( EVENT entries ), seaking for special keywords into the description field (need to be first entry in first line) :

 #cmd#  --> execute Domoticz command on device

 #hol#  --> add day to Holidays

 #wrk#  --> this is a work time

 ###    --> to bypass this entry

• #cmd#

You have the possibility to instruct the plugin to schedule command on any Domoticz device.

If you want same command for more than one Domoticz device, just enter them as a list :

e.g. #cmd#DeviceName{,dev2,dev3,...}:switch:On/Off{:0}

Actual commands are:

 switch : #cmd#DeviceName:switch:On/Off{:0}

This take the start / end date&time of the calendar entry and create corresponding timers. For the end, plugin will 'toogle' the start command: this mean if start command is 'On', 'Off' will be put for the end. If you don't want the end timer, just put ':0' at the end of the #cmd# keyword.

 level  : #cmd#DeviceName:level:999{:0}

This take the start / end date&time of the calendar entry and create corresponding timers.For the start, this will put at 999 level the device. For the end, plugin will put 'Off' the device. If you don't want the end timer, just put ':0' at the end of the #cmd# keyword. Valid level value is : 1 --> 100.

 rgb    : #cmd#DeviceName:rgb:color{:0}

This take the start / end date&time of the calendar entry and create corresponding timers.For the start, this will put the device at requested color. For the end, plugin will put 'Off' the device. If you don't want the end timer, just put ':0' at the end of the #cmd# keyword.

Color name can be entered in native language if this one is managed by googletrans or in english. Not all color name are managed, see this link : W3c Color Naming

 push   : #cmd#DeviceName:push:On/Off

This take only the start date&time and put in timer requested command ( 'On' or 'Off' only ).

DeviceName need to be replaced by your Domoticz device name you want to manage.

Let's suppose we have a device named MyBulb and you want to switch it < On > at 21:00 and < Off > at 23:30 on Tuesday, June 5th

We will use the switch cmd for this purpose and put on the description this entry : #cmd#MyBulb:switch:On

Google calendar look & feel

• #hol#

Add a day into Holidays. This need to be a full day entry. See Holidays for more information.

Google calendar look & feel

• #wrk#

Manage your work time. This is an optional keyword if parameter AtWork is True, in this case all calendar entries are considered as work time (except #cmd# and #hol#)

See AtWork for more information.

• ###

This special keyword instruct the plugin to bypass the calendar entry. Usefull if you want to create some templates in your calendar.

Caution: for #cmd# keyword: plugin create automatically all the timers, but if you change or remove any entry in Calendar, you need to do that manually in your Domoticz system. Main goal of this plugin is to manage Holidays and work time...

Configure for Google Calendar

This come from Google support

See your calendar (view only)

If your calendar application doesn't have a full sync option, or if you want a read-only view of one calendar, you can sync your calendar to the application using a link to ICAL.

   On your computer, open Google Calendar.
   In the top right, click Settings Settings and then Settings.
   Open the Calendars tab.
   Click the name of the calendar you want to use.
   In the "Private Address" section, click ICAL.
   Copy the ICAL link that appears in the window, or click the ICAL link to download an ICS file. 
   Paste the link or upload the file as directed by your other calendar application.

Note: Only you should know the Private Address for your calendar. Don’t share this address with other people. If you accidentally shared your calendar's Private Address, click Reset Private URLs to create a new Private Address.

The ICAL link need to be put on the ics data gather command parameter.

In the same way, you can find the same instruction if you use Outlook.com.

This plugin has been tested and should work with it. In fact, should work with any application, online or local, that provide an ics file export.

At Work

Device to manage your work time

This is a simple switch On/Off device. When you 're at Work it will be set to On otherwise to Off. By parsing iCal data, the plugin search for this special keyword : #wrk# (or someting else, even nothing, but not #cmd# and #hol#: depend if AtWork parameter is set to True). Once data retreived, timers will be created to suit the Calendar entries.

Holidays

Automatic calculation of Holidays

Selector switch, each level represent a public Holiday.

Country, Province & state are the plugin parameters used by the holidays module. If the country is not managed by the holidays module, a device is created anyway with blank entry. Go here to see Country, Province & state list : Countries

In all case, you can add your own holiday days by creating in your calendar an entry ( all day ) with this special tag: #hol#.

This need to be put in the first line of the calendar entry description. You will be warned if you do not select all day for this kind of entry and this will not work as you suppose.

Holidays are re-calculated twice by day, at 00:00 and 12:00. If you want to force the re-calculation, just do that with the status device.

Device will be put 'Off' if it's not a Holiday day, otherwise will be put on the right Level.

Seasons

Device to show on which season we are

This is an automatic calculation of seasons.

This depend on which hemisphere you are. In some country, rules are not the same, this is the case for RU, CN, AU, ZN, this device take care of that. The Lat/Lon set in Domoticz settings is used to determine country / hemisphere.

Once this device is created, no more action will be managed by the plugin.

you can always change timers in case not fit your needs/reallity. To initialize the device, you need to select your actual season.

Should it rain next hour ?

This one is specific to French people as data are retreived from Meteo France.

This is an Alert device with only two status :

• 1: Green, to indicate no rain in next hour.

• 4: Red, to indicate rain possibilities.

Refresh interval is every 15 minutes. Location is automatically retreived from the Long/Lat data set in Domoticz parameters and stored into Domoticz uservariable to not have to calculate every time. This give you also the possibility to change it in case something wrong but allow to have more than one for different location if needed.

Remove the plugin, best way.

this plugin create some uservariables/files for internal work. Clean way to remove it is by first, remove all the devices, second, wait one / two minutes, in Domoticz log you can see a message than you can remove the plugin. e.g.

 2018-06-05 19:12:10.960 (Outlook.com) ----- iCal Plugin information ---------
 2018-06-05 19:12:10.960 (Outlook.com) No devices in plugin system....
 2018-06-05 19:12:10.961 (Outlook.com) plugin can be removed now .. or update HW to re-create them
 2018-06-05 19:12:10.961 (Outlook.com) ----- End iCal Plugin information -----

From this point, you can also re-create all your devices by going to Hardware tab, select your HW and click on refresh. This should put the devices labels in your native language (if managed) in case of translation problem (take care this remove all history and should be used only during the first time installation)

Technical information

Development/test platform

Win 10 x64

Python v 3.5.3 x86

Domoticz Beta min: V3.90xx

Main module:

icalendar

Additional modules:

holidays
googletrans
colour
recurring_ical_events

All python modules installed by using : pip3 install <module name>

Junction - Windows:

link/junction need to be created for c:\program files(x86)\Domoticz to avoid space problem when call cmd file