livebox:google_calendar [DBZoo]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== xAP Google Calendar ======

{{ :livebox:google-calendar-logo-150x139.png}} Google Calendar xAP daemon.

<note warning>Around mid Dec 2013, something changed in Google space which stopped this HAH component from finding any events. This might be due to Google moving from V2 of their Calendar API to V3. Until such time as rework can be done, please consider using cron instead.

</note>

This program will monitor a calendar and produce an xAP payload every minute for as long as the activity is running.  The password, once entered, will never be again displayed on the web GUI, this is for security reasons.  However, it can be reset by simply entering another.

The polling period determines how often Google is checked for events.   All events within the polling period will be cached on the HAH.  For example if the current time is 1pm and you check every 1hr, when all events to 2pm will be downloaded and cached on the HAH.  This also means that if you schedule an event at say 1:30pm AFTER the xap-googlecal program has refreshed its cache, this event will not fire.

{{:livebox:xap-calendar.jpg|XAP Calendar setup}}

The /etc/xap-livebox.ini file contains a section that holds the configuration parameters.  Only user, enable and passwd are needed, the others will default if missing to those values supplied in the example.

<code ini>
[googlecal]
enable=1
uid=00DA
instance=GoogleCal
user=user@gmail.com
passwd=secret
ufreq=60
</code>

{{:livebox:googlecal.jpg|}}
===== Scheduling events =====

An entry is setup in the calendar using the following fields.  This example will send the text //"Hello World"// to the LCD.

{{:livebox:googlecal.jpg|Google Calendar Event}}

  * What: <Some text defining your event>
  * Where: XAP   <must be the value xap>
  * When: Start-time to Stop-time
  * Description: An xAP payload using short form notation.
<code>
   xap-header
   {
   target=dbzoo.livebox.controller:lcd
   class=xAPBSC.cmd
   }
   output.state.1
   {
   id=*
   state=on
   text=Hello World
   }
</code>
In the header you only have to specify the xAP message type (class) and the target.\\
The other fields will be automatically populated for you.

The event will fire every minute for the duration of the start/stop time.\\
If you require a single message then make the start/stop time the same value.

Another example, this text in the calendar event description will turn on RF module number 2.

<code>
xAP-header
{
class=xAPBSC.cmd
target=dbzoo.livebox.Controller:rf.2
}
output.state.1
{
id=*
state=on
}
</code>

Notice that there is no automatic generation of an 'off' message at the end of the calendar event. If you want the RF module to switch back off, you must create a separate 'off' event in the calendar.
===== Calendar aliases =====

Leaving out the description of the calendar entry the Google calendar component will interpret the title as an alias.

So now a calendar definition can be as simple as

{{:livebox:gcal-alias.png|}}

This will result in a the following xAP message being transmitted.
<code>
xap-header
{
v=12
hop=1
uid=FF00D900
class=alias
source=dbzoo.livebox.Twitter
}
command
{
text=relay 1 on
}
</code>

It is up to the alias scripts running with [[hah_plugboard_v2]] to determine what action to take.  See twitter for an example of an [[twitter#alias_interpreter]] that can be used by google calendar too.

===== Recording events =====

The Google calender daemon can also act as a service.  This means it will accept an xAP payload and create a calendar event.

Header information
  * the target will be: target=dbzoo.livebox.GoogleApp
  * and the schema is: class=google.calendar

The body has the following elements
<code>
event
{
title=
start=
end=
description=
where=
}
</code>

  * Title is mandatory and contains a brief description of the logged event.
  * Start is mandatory and can use a natural language format for its specification.
  * End is optional and if not supplied the event is assumed to be 1 min long.
  * Description is optional.
  * Where is optional default xap-event.  Useful to set to "xap" if you want to schedule future actions.

**Start / End format**\\
  - We always try to parse as ISO8601 first. We don't support week/day  numbers (1985-W15-5) because they make me shudder. It wouldn't actually be hard to support them.  We support the W3C subset of ISO8601 (see http://www.w3.org/TR/NOTE-datetime) completely.
  - We then try some fancy natural language processing. No ambiguous formats are represented. 4/3/5 is *not* a valid input, regardless of your locale. But most of the phrases accepted by the current getdate *are*. We can also read in RFC822-conformant dates. ("Wed, 22 Aug 2001 19:35:16 -0400") and relative dates ("next thursday"). All non-ISO8601 dates are in *local* time. Thus, the date specification "8pm" is 8pm for *you*, not 20:00 UTC.  You can specify a time zone ("GMT" or "UTC" for example) to force UTC interpretation. I do *NOT* currently support the 'three-letter' time zone codes, like EST, EDT, PST, etc. Time zones in ISO8601 format ("+08:00", "-0400") and military  time zone letters ("A"-"Z", excluding "J"; see http://www.timeanddate.com/library/abbreviations/timezones/military/ ) are accepted.  This is not a fundamental limitation; I'm just trying to avoid accepting potentially ambiguous descriptors ('EST' has different meanings in Australia and the US, for example).

**Full payload example**\\
<code>
xap-header
{
v=12
hop=1
uid=FF123400
class=google.calendar
source=acme.booker.ping
target=dbzoo.livebox.GoogleCal
}
event
{
title=Lunch
start=tomorrow at 12pm
end=tomorrow at 1pm
description=at Benji
}
</code>


===== Troubleshooting =====

I start up Google Calendar in debug mode and it won't connect!
<code>
# xap-googlecal -i br0 -d 7
</code>
This is what I see.
<code>
[alr][googlecal.c:116:internalError] Failed to authenticate
[inf][tx.c:19:xapSend] send
xap-header
{
v=12
hop=1
uid=FF00DA00
class=google.calendar
source=dbzoo.livebox.GoogleCal
}
error
{
text=Failed to authenticate
}

[alr][googlecal.c:457:main] HTTP code: 0 Msg Peer certificate cannot be authenticated with known CA certificates
</code>

Make sure the CLOCK on your Livebox has correctly been set by NTP.