AK Google Calendar plugin introduction / instructions / screenshots

[alexbk66]

AK NetCam	AK Weather	AK Web I/O	AK Bond	NeoSmart Blinds	Arylic Linkplay	AK SwichBot	EspHome~~	AK_Modbus
EnphaseEnvoy	AK IKEA	ControlByWeb	AK_Shelly~~~	AK Remootio	AK Traccar	AK AndroidTV	Konnected	AK_YoLink
AK PumpFuse	AK GoogleCast	GoogleCalendar	AK Sonoff	SmartDevice	HeatmiserNeo	HomeAssistant	Link&Link	AK_Yamaha

Google Calendar plug-in for: - Displaying calendar events, - Triggering HS events based on upcoming calendar event (reminder, start, and end). - HS Event actions for creating Google calendar events (both Event Start and Event End). https://shop.homeseer.com/products/alexbk66-ak-google-calendar-software-plugin-for-hs4

Features: https://www.youtube.com/watch?v=3mDa1kY4c7k

1. The plugin creates a parent root device for each Google Calendar you have ("real" calendars). In addition it creates two "virtual" calendars with configurable time range for each (i.e. default Today and Tomorrow calendars)

2. HS Event Triggers: Calendar Event Reminder, Calendar Event Started Calendar Event Ended Lots of global variables for use in Actions (Note: the variables are set when the event happens, so they are relevant only after the event, and will be overwritten by next event):

3. HS Event Actions: Create Calendar Event Set Event End I.e. instead of creating two separate calendar events for Gates Open / Gates Close - one event is created with event end time corresponding to Gates Close:

4. All calendars settings:

[alexbk66]

1. Configuring Google Credentials

NOTE: New HS feature "Run as Service" prevents authorisation prompt. To configure Google credentials HS must run as normal process, not as service. First time you start the plugin - it will pop up authorization prompt in browser. Note: For this reason you have to use web browser on same computer where HS server is installed and logged in in your browser with your Google email. For Headless/Linux please see this post !

[alexbk66]

2. Configuration Options

The plugin creates a parent root device for each Google Calendar you have setup (real calendars). In addition it creates two calendar groups with configurable time range for each (i.e. default Today and Tomorrow virtual calendars). General Configuration: 1. Event display date separator - to display event start date/time on new line use "<BR>". To display date in brackets use one of "(", "[", "{". If left blank - no event start date displayed. 2. Date and Time display format - see Custom date and time format strings 3. All Day Event start time (offset from 0:00 - positive or negative)

For all calendar groups (both real and virtual calendars) you can configure: 1. Number of events you want to display (default 5). Plugin will create a child device for each calendar event. To disable this calendar set Events to 0. 2. Update rate (default 15 minutes). This only matters for detecting newly creating events. The plugin will automatically reduce the update delay closer to the event. To disable this calendar can set Update rate to 0:00. 3. Show Started Events - events in progress started, but not ended. If unchecked - the started event will disappear from HS. For each real calendar additionally: 1. Include in Today 2. Include in Tomorrow If you want to show events from this calendar in Today/Tomorrow calendars

For each virtual calendar additionally: 1. Range Start - when the time range for this calendar start, i.e. default 0:00 for Today and "1 Day" for Tomorrow 2. Time Range - default 1 Day for both, can be changed, i.e. to 7 days to show one week events. 3. Range Type (Fixed/Moving) - i.e. for Today calendar if "fixed" is selected - the display range will be always fixed from 0:00 to 24:00. For "moving" range show the events starting from "now" for the next 24 hours.

Note: Most of these settings are also available from "My Calendars" page:

[alexbk66]

3. Creating HS Event Triggers/Actions

HS Event Triggers:

Calendar Event Reminder: If GC event has reminder (notification) set - trigger HS Event at the reminder time. Each Google Calendar can have "default" notification (used for each new event) and "event specific" notification (added manually after the event is created). Hence the HS event trigger configuration has two options: "Use default calendar reminders" and "Use event specific reminders". Calendar Event Start (Occures): Triggered when GC Event starts (or before the event if Trigger Before 'hh:mm:ss' is set in the HS event configuration). Calendar Event End Calendar Event Contains condition Note: if you want to trigger HS event some time before the GC event starts, you can use either Calendar Event Reminder trigger (and set the notification time in the GC event configuration); or Calendar Event Start (Occures) trigger (and set the Trigger Before 'hh:mm:ss' time in the HS event configuration).

Note 1: Since HST didn't port timepicker control to HS4 - you need to enter time span as text, i.e. if you want to trigger event 15 minutes before - enter 0:00:15 Note 2: For "Calendar Event End" trigger you must enable "Show already started events" in each calendar settings. Please read Important Notes below.

When the event triggers - plugin creates many global variables for using in actions (using format $$GLOBALVAR:name:):

Note 1: Global Vars are set only when event triggers - so the contents of the variables reflects only one event, until next trigger when they become overwritten. Note 2: To see what variable values are set you can enable the calendar Log and see all variables in HS log when event is triggered.

HS Event Actions:

(1) Create Google Event Note: The event text can use HS Replacement Variables, i.e. device value / status. Say you want to keep track of your gate state in the Google calendar. You use "Create Calendar Event" action when your gates are open

Note the event-action id above (3-3436) you need for "Set Event End" action later. (2) Set Google Calendar Event End When the gates close - you use "Set Even End" action (make sure you select the id 3-3436):

[alexbk66]

4. Important Notes

1. Trigger functionality depends on the calendar configuration and works only for Calendar events displayed in HS. For example if you create a trigger for Event Reminder in Today Calendar and the Calendar Event starts tomorrow (so isn't displayed in Today calendar) and the event reminder is set for "One Day before the event" - it won't trigger. In other words, the Event Reminder trigger for Today Calendar only triggers for events starting today (i.e. within 24 hours)

2. For same reason if you want to use Event End Trigger - then "Show Started" option should be enabled for this calendar.

3. And for the same reason if you disable updates for particular calendar (by setting number of events or update frequency to 0) - triggers for this calendar won't work.

4. Event Reminder Triggers work only for the reminder set explicitly for the event - not the default reminders. Google Calendar API provides only reminder "overrides" by default. It is possible though to get the default reminders to work if required - please add Feature Request.

5. For some calendars Google doesn't send the clean Name, instead it provides an ugly looking ID. In this case I recommend in Google calendar settings set the calendar description field to the display name you want to see in HS - the plugin then will use the description instead of the name.

[alexbk66]

Scripting Support



From Ver 4.0.4.9 (BETA) - Added Scripting support ("CreateCalendarEvent", "EndCalendarEvent")

Note 1: Additional parameters can be added on request

Note 2: The first PluginFunction argument is the plugin name - not ID - i.e. "AK GoogleCalendar"

Function	Examples (C# script)	Arguments (object[])
CreateCalendarEvent Create event in Google Calendar. Returns Event ID (required for EndCalendarEvent)	&shs.PluginFunction("AK GoogleCalendar", "", "CreateCalendarEvent", new object[] {"jgcuopiksi78f231qq5t23b2pg@group.calendar.google.com", "Test Event"}); &shs.PluginFunction("AK GoogleCalendar", "", "CreateCalendarEvent", new object[] {3652, "Test Event", "Extra description"}); &shs.PluginFunction("AK GoogleCalendar", "", "CreateCalendarEvent", new object[] {3652, "Test Event", "Extra description","2/16/2008 12:15:12 PM", "2"});	1. Required. Calendar ID (can see on the calendar settings page). Can also pass Calendar root device RefID, or calendar name. 2. Required. Event summary (name) 3. Optional. Event description. 4. Optional. Event start Date/Time string i.e. "2/16/2008 12:15:12 PM" See for examples. 5. Optional. ColorID - event color index (one based) - you can see the order on HS event Action creation page, i.e. "2" for Aquamarine.
EndCalendarEvent Set end time of the Event, with optional additional description.	&shs.PluginFunction("AK GoogleCalendar", "", "EndCalendarEvent", new object[] {3652, "fp1r99gohnk7kevslv8o50fe1g"}); &shs.PluginFunction("AK GoogleCalendar", "", "EndCalendarEvent", new object[] {"jgcuopiksi78f231qq5t23b2pg@group.calendar.google.com", "fp1r99gohnk7kevslv8o50fe1g","Test Event Done"});	1. Required. Calendar ID (can see on the calendar settings page). Can also pass Calendar root device RefID, or calendar name. 2. Required. Event ID - returned from CreateCalendarEvent 3. Optional. Additional description, see screenshot above.

[alexbk66]

Note on plugin loosing Google authorization.

Some users report that the plugin sometimes looses authorisation and needs to re-authenticate.

While I can't (yet) get to the bottom of the issue, I made a lot of improvements to detect if authorisation is lost.

When authorisation is lost - the main plugin root device should change to "Not Authorised" state. Then it should also pop-up Google login prompt (which won't work if HS is running as service).

There's also "Authorise" button on main plugin root device (in case the prompt didn't pop-up automatically).

Please note that after every service reset the plugin will poll all calendars, so don't set the "service reset timeout" too low. Probably once or twice a day should be sufficient.

Also, if "Reset above timer on successful comms" is enabled - then timer will restart after every successful poll. In this case it's probably safe to set "service reset timeout" just a bit longer then calendar polling period (i.e. 15 minutes) - so it should only fire if there's no reply from Google.

Note: it's probably a good idea to setup a HS event in case the main plugin root device state becomes "Waiting Authorisation" or "Not Connected" to inform that the plugin needs attention.

[alexbk66]

Ver 4.0.0.12 - Added support for Replacement Variables in "Create Calendar Event" action

[alexbk66]

Ver 4.0.0.18 - Added "Contains Text" Condition sub-trigger

Ver 4.0.0.20 - Added "Waiting Authorisation" root state so you can get notification and execute some action if requires Google Authentication

[alexbk66]

Finally Google approved my application, so users don't need to create their own app / credentials.

[The Profit]

alexbk66 Congrats! For users that have had this plugin installed already, do we need to do anything other than update the plugin?

[alexbk66]

alexbk66 Congrats! For users that have had this plugin installed already, do we need to do anything other than update the plugin?

If you want to use my client id/secret (most probably) - you need to delete them in the plugin settings (set to empty string).

Also delete just in case C:\Program Files (x86)\HomeSeer HS4\Bin\AKGoogleCalendar\token.json

[The Profit]

If you want to use my client id/secret (most probably) - you need to delete them in the plugin settings (set to empty string).

Also delete just in case C:\Program Files (x86)\HomeSeer HS4\Bin\AKGoogleCalendar\token.json

I've just updated to version 4.0.2.3 and already have a client ID and secret under the "Enable the Google Calendar API" section, will these work or will it only work under your client id and token? The plugin seems to be updating and working fine at the moment.

[alexbk66]

I've just updated to version 4.0.2.3 and already have a client ID and secret under the "Enable the Google Calendar API" section, will these work or will it only work under your client id and token? The plugin seems to be updating and working fine at the moment.

Yes, it should have your client ID/secret if you configured before, I didn't want to delete them in case users want to use their creds.

But if you delete both of them - the plugin should use my creds.

[alexbk66]

Ver 4.0.4.1 (BETA) - Fixed Calendar Event Reminder trigger