Foreword

This was originally published here on October 21, 2017. Here’s the original post:

A while ago, I posted a thread for syncing an iCloud calendar with MagicMirror in the MagicMirror forum. Unfortunately this solution was just a workaround and you needed to use a Mac which is also synced with your calendar. It was far from being a nice solution.

I just found out, that the tool I was using (vdirsyncer) also supports syncing with iCloud. I wrote a detailed walkthrough for this.

I’ll re-post this part from the original post:

Why doing it this way?

I don’t want my calendar to be available via a public URL like mentioned in the iCloud calendar thread. Even though the public sharing address is quite long, web crawlers can still find them and your private life is publicly available. I just don’t like that scenario. So I wanted a solution that uses encryption and authentication against all services.

So here’s a really nice solution to sync the mirror with iCloud (privately):

Get app-specific password from iCloud

vdirsyncer needs an app-specific password to connect to iCloud. You can create one in your AppleID settings like descibed in Apple’s support document for using app-specific passwords: https://support.apple.com/en-us/HT204397

Create one and write it down for later.

Install and set up vdirsyncer

vdirsyncer needs to be installed on the machine that hosts your mirror software. On my raspbian system, vdirsyncer was not available via apt. So I had to install it via pip.

Installation of vdirsyncer

Now, we get vdirsyncer and it’s dependencies:

sudo apt-get install libxml2 libxslt1.1 zlib1g python3
pip3 install --user --ignore-installed vdirsyncer

(This is the quick and easy way, it should suffice for most users. For a more clean way to install it, please refer to https://vdirsyncer.pimutils.org/en/stable/installation.html#the-clean-hard-way)

Now, change the first line of your vdirsyncer executable to use only python3 (I didn’t have to do that in newer versions, so maybe ist already like this…):

nano ~/.local/bin/vdirsyncer

And change the first line to #!/usr/bin/python3

I needed to create a symlink to the vdirsyncer executable. So we’re doing this:

sudo ln -s /home/pi/.local/bin/vdirsyncer /usr/bin/vdirsyncer

Now you should be able to use the vdirsyncer command from the command line.

Create a folder for the calendar file

As mentioned in this post, we can put the calendar file into the modules folder to access it via the calendar module. So we create a folder for our calendars:

mkdir /home/pi/MagicMirror/modules/calendars

Configure vdirsyncer

Create a config file in ~/.vdirsyncer/config and open it with nano:

mkdir ~/.vdirsyncer
touch ~/.vdirsyncer/config
nano ~/.vdirsyncer/config

Here’s an example configuration to use with iCloud. Just copy it into your opened file in nano and enter your previously created iCloud credentials.

# vdirsyncer configuration for MagicMirror.
#
# Move it to ~/.vdirsyncer/config or ~/.config/vdirsyncer/config and edit it.
# Run `vdirsyncer --help` for CLI usage.
#
# Optional parameters are commented out.
# This file doesn't document all available parameters, see
# http://vdirsyncer.pimutils.org/ for the rest of them.

[general]
# A folder where vdirsyncer can store some metadata about each pair.
status_path = "~/.vdirsyncer/status/"

# CALDAV Sync
[pair iCloud_to_MagicMirror]
a = "Mirror"
b = "iCloud"
collections = ["HERE-GOES-THE-UUID-OF-THE-CALENDAR-YOU-WANT-TO-SYNC"]

# Calendars also have a color property
metadata = ["displayname", "color"]

[storage Mirror]
# We need a single .ics file for use with the mirror (Attention! This is really slow on big amounts of events.)
type = "singlefile"
# We'll put the calendar file to a readable location for the calendar module
path = "/home/pi/MagicMirror/modules/calendars/%s.ics"

[storage iCloud]
type = "caldav"
url = "https://caldav.icloud.com/"
# Authentication credentials
username = "YOUR-ICLOUD-EMAIL-ADDRESS"
password = "HERE-GOES-YOUR-APP-SPECIFIC-ICLOUD-PASSWORD"
# We only want to sync in the direction TO the mirror, so we make iCloud readonly
read_only = true
# We only want to sync events
item_types = ["VEVENT"]
# We need to keep the number of events low, so we'll just sync the next month
# Adjust this to your needs
start_date = "datetime.now() - timedelta(days=1)"
end_date = "datetime.now() + timedelta(days=30)"

Make sure, you use the start_date and end_date parameters to keep the number of calendar events low. I tried syncing with 700+ events and it is really really sloooooow! Especially when using the singlefile option for the mirror.

Add your iCloud credentials like shown in the config file.

Running vdirsyncer as a systemd.timer for automatic sync

Install the vdirsyncer.service and vdirsyncer.timer files to /etc/systemd/user:

curl https://raw.githubusercontent.com/pimutils/vdirsyncer/master/contrib/vdirsyncer.service | sudo tee /etc/systemd/user/vdirsyncer.service
curl https://raw.githubusercontent.com/pimutils/vdirsyncer/master/contrib/vdirsyncer.timer | sudo tee /etc/systemd/user/vdirsyncer.timer

By default, the syncer is started every 15 minutes. You can change it by configuring the times in the vdirsyncer.timer file:

sudo nano /etc/systemd/user/vdirsyncer.timer

Now we activate the timer in systemd:

systemctl --user enable vdirsyncer.timer

Let vdirsyncer discover the collections and do the inital sync

Now, we have to find out which collection we want to sync. Let vdirsyncer discover everything:

vdirsyncer discover

You should get an output like this (depending on the number of calendars you have in iCloud):

Discovering collections for pair iCloud_to_MagicMirror
Mirror:
iCloud:
  - "25CB285C-E163-4E0E-B420-C3FB469B7C00" ("Calendar 1")
  - "9221FEE8-E8B4-4D07-9402-8638529919EC" ("Calendar 2")
  - "953A5477-E405-4ED6-A5C3-473444EACC95" ("Calendar 3")
warning: No collection "HERE-GOES-THE-UUID-OF-THE-CALENDAR-YOU-WANT-TO-SYNC" found for storage Mirror.
Should vdirsyncer attempt to create it? [y/N]:

Press N for now and press return.

Now replace the HERE-GOES-THE-UUID-OF-THE-CALENDAR-YOU-WANT-TO-SYNC in the config with the UUID of the calendar you want to sync. We assume, we want to sync “Calendar 2”.

So line 19 of your config should look like this:

collections = ["9221FEE8-E8B4-4D07-9402-8638529919EC"]

Now, we can run the discover again and make the first sync:

vdirsyncer discover

You should get something loke this:

Discovering collections for pair iCloud_to_MagicMirror
Mirror:
iCloud:
  - "25CB285C-E163-4E0E-B420-C3FB469B7C00" ("Calendar 1")
  - "9221FEE8-E8B4-4D07-9402-8638529919EC" ("Calendar 2")
  - "953A5477-E405-4ED6-A5C3-473444EACC95" ("Calendar 3")
warning: No collection "9221FEE8-E8B4-4D07-9402-8638529919EC" found for storage Mirror.
Should vdirsyncer attempt to create it? [y/N]:

Choose y and press enter. Now we can start the sync with:

vdirsyncer sync

You should find a single calendar file in /home/pi/MagicMirror/modules/calendars/ with the UUID of your calendar as filename like 221FEE8-E8B4-4D07-9402-8638529919EC.ics in this example.

Add the calendar file to the calendar module of the mirror

Now we just have to add the URL to the calendar file to our calendar module of the mirror like this:

{
    module: 'calendar',
    position: 'top_left',   // This can be any of the regions. Best results in left or right regions.
    config: {
        maximumNumberOfDays: 10,
        maximumEntries: 7,
        calendars: [
                {
                        url: 'http://localhost:8080/modules/calendars/221FEE8-E8B4-4D07-9402-8638529919EC.ics',
                        symbol: 'calendar'
                }
        ]
    }
},

If everything went well, your MagicMirror is now automatically syncing your iCloud calendar with it’s calendar module 🙂