Connecting calendars
Every calendar source Mirra can read — an iCal link, a CalDAV account, Google, Microsoft 365 — with the steps for each, what actually syncs, and what quietly breaks it.
The Calendar integration and its four widgets are on every plan. Nothing on this page is plan-gated.
What a connected calendar feeds
A calendar connected here is not a setting on one widget. It feeds four widgets — Agenda, Week calendar, Month calendar and Coming up next — as well as the spoken briefing when somebody appears in front of a mirror, and the assistant when it is asked what is on today.
Every source ends up as the same list of events, so nothing downstream cares which one it came from. Whatever the provider, Mirra fetches the same window: forty-five days back and seventy days forward. That is sized for the widest thing that reads it, the month grid — opened on the 1st it shows a few days of last month, and opened on the 31st it still has to fill the whole of this one plus the start of the next. Every provider uses the same numbers deliberately; when they drifted apart, the same event was present or absent depending on which account it lived in.
Calendars are merged and sorted together, and a failure in one never takes out the others. A feed that cannot be read is reported as unreadable rather than as empty — on a wall those look the same and it barely matters, but on a meeting-room door an empty agenda is a claim that the room is free.
The sources that exist, and which ones your install has
Four ways in are offered to a household, plus two that belong to particular situations. Two of the four are inert unless whoever runs this install has registered an application with the provider — that is a one-off job for the operator, not something a household can do, and there is no way for you to supply your own client ID.
Where it has not been done, the Connect button is disabled. A household sees only that it is not available yet, with a nudge towards the iCal option, which needs nothing from anybody. A super admin additionally sees which environment variables are missing.
Mirra asks for read-only access from both Google and Microsoft, and there is no write path in the product. It cannot create, move or delete anything in your calendar.
Adding an iCal feed
The cheapest thing that works, and the one to reach for when a Connect button is disabled. Google and Outlook will both give you an .ics link for the same calendar.
Go to Integrations → Calendar
Or open /integrations/calendar directly.
In "Add a calendar", press iCal URL
The two buttons at the top of the form choose which kind you are adding.
Give it a name
This is what appears beside events on the wall — "Family calendar" rather than the URL.
Paste the link
In Google: Settings → your calendar → "Secret address in iCal format". In Outlook: Calendar settings → Publish. It must be an http or https URL; webcal:// links need the scheme changing to https.
Press Add calendar
Mirra reads the feed before saving it, so a bad link fails here rather than on the wall. If it cannot be read you get "Couldn't read that calendar — check it's a valid iCal/ICS feed." and nothing is stored.
An iCal feed is cached for five minutes per URL, shared across every screen in the household. Recurring events are expanded properly, and occurrences the organiser deleted from a series are skipped. A single unreadable event is dropped rather than being allowed to take the whole feed with it — one event with a language tag on its title once emptied an entire calendar off a wall.
Adding a CalDAV calendar
For Nextcloud, Fastmail and iCloud. You need the URL of one calendar collection — the account root will not do, because Mirra asks that one URL for the events in the window rather than walking the account to discover what is in it.
Find the collection URL in your provider
It looks like https://cloud.example.com/remote.php/dav/calendars/you/personal/ — one calendar, with a trailing slash.
In "Add a calendar", press CalDAV
The form grows a username and a password.
Fill in the name, URL, username and password
Use an app-specific password if your provider offers one — it means revoking Mirra's access does not mean changing the password you use everywhere.
Press Add calendar
Mirra makes a real request for the window before saving. A wrong URL or a refused password fails here, with the reason: "Couldn't read that CalDAV calendar. Check the collection URL and credentials."
Mirra does not expand recurring series for CalDAV itself — it takes whatever the server returns for the window. Most CalDAV servers expand a recurring series in a time-range query, but a server that does not will show a weekly meeting once, at its original date. If that is what you are seeing, the same calendar published as an .ics feed will behave.
Connecting Google
One click for a household, once the install has been registered with Google. Mirra asks for the read-only calendar scope and nothing else.
Press Connect Google Calendar
On Integrations → Calendar, under "Connect an account". If the button is disabled, this install has no Google registration — use an iCal link instead.
Sign in and approve
Google shows its own consent screen, asking for read-only access to your calendar. Declining is not a failure; you come back and are told the sign-in was cancelled.
You are returned to the page you started from
With "Google Calendar connected." A connection begun from the screen editor returns to that screen rather than dumping you on a settings page.
Only the account's primary calendar is read, up to a hundred events in the window. Other calendars in the same Google account — a shared family calendar you have subscribed to, a work calendar — are not included. Add those separately with their secret .ics addresses.
If Google does not return offline access, Mirra refuses to save the connection rather than pretend it worked: without it the calendar would stop working within the hour. You will see "Google didn't grant offline access, so the calendar couldn't be kept in sync." This normally means the operator's Google Cloud project needs attention. A project still in Testing also expires its refresh tokens after seven days, so a calendar that works for a week and then dies is that, not you.
Connecting Microsoft 365 or Outlook
The same shape as Google. Mirra asks for Calendars.Read and offline access, and the connection is named after the mailbox it belongs to — "Outlook — you@example.com" — so a household with two Microsoft accounts can tell them apart.
Press Connect Outlook Calendar
Under "Connect an account". Disabled means this install has no Microsoft registration.
Choose an account
You are asked which account to use, so signing in a second mailbox does not silently reuse the first.
Approve read-only access
The consent screen names Calendars.Read. Mirra never asks for write access, so nothing in the mailbox can be altered.
You are returned with "Outlook Calendar connected."
Mirra then subscribes to change notifications in the background. That step is allowed to fail quietly — the calendar works either way, and a housekeeping sweep picks it up within the hour.
Some organisations block ordinary employees from consenting to Calendars.Read, which is Microsoft's default for new tenants. In one of those you will see "Need admin approval" on Microsoft's own screen, and no amount of retrying will get past it. That is a decision by your IT department, not a fault in Mirra.
Signing in to a calendar from the screen itself
Where nobody wants to open the portal, a screen can show a short code and whoever is standing in front of it finishes on their phone. This is Microsoft's own pattern for devices that are awkward to type on, and it is available for Microsoft accounts only.
The portal drives the whole flow and the screen only displays two strings. That is not a preference: Microsoft's device-code endpoint cannot be called from a browser at all. It is also the better split, since the screen never holds a client secret and the resulting token is written straight into the database by the process that obtained it.
Open the screen's page in the portal
Screens → the screen you want.
Press "Sign in to a calendar on this screen"
The code and the address appear on the wall, and on the page as well — somebody starting this from a laptop should not have to walk to the screen to read the code they are about to type.
On a phone, go to the address shown and enter the code
Then sign in to the Microsoft account as usual.
The code clears itself
A calendar named after the mailbox appears in the list. If nobody finishes, the flow gives up after about fourteen minutes and the screen clears rather than sitting on a dead code. Cancel stops it immediately.
This does not get past an organisation that blocks Calendars.Read — and it is worse there, because the refusal appears on a wall where nobody can read the reason. It is a convenience for households and small teams rather than an answer for a managed tenant.
How often a change reaches the wall
Every calendar widget refetches every five minutes, so any change anywhere reaches a screen within that. Nothing here is dependent on the push described below, which is a freshness improvement on top of a poll that never stops.
Microsoft calendars — personal Outlook accounts and meeting rooms — are also subscribed to for change notifications. Microsoft tells Mirra within seconds that something in the mailbox changed, Mirra asks a single narrow question of Microsoft in reply — is any of it inside the window a screen is showing? — and only then does it tell the screens to look again. A work mailbox changes constantly and most of it is a meeting in October; waking every screen in the building for each one would turn freshness into flicker.
For a personal Outlook calendar, every paired screen in the household is told. A room's change is addressed only to the screens assigned to that room — and nothing in the portal assigns one, so in practice a room's changes still arrive on the five-minute poll. See Meeting rooms and room panels.
The card says which you have: "Connected via Microsoft — changes appear within seconds" when the subscription is in place, and "Connected via Microsoft" when it is not. Subscribing needs the install to have a public https address for Microsoft to reach, which a laptop does not, so on a development install the plain wording is correct rather than broken.
Mirra keeps no copy of your calendar. Every event on a screen was read from the source on that screen's own request; there is no shadow database of your meetings to leak or to go stale. The one exception is a meeting a screen was invited to by email, which has no remote to re-read and so has to be stored.
When a calendar stops working
Calendar widgets show "Calendar unavailable" when a source could not be read, which is deliberately different from showing nothing. Nothing means nothing is booked; unavailable means we do not know.
These are the usual causes.
Remove the broken calendar
On Integrations → Calendar, press Remove on its row. For an Outlook calendar this also cancels the change-notification subscription at Microsoft, so we stop asking about a mailbox you have disconnected.
Add it again
Reconnect with the same steps as before. There is no repair action — reconnecting is the repair.
- Access revoked at the provider. Removing Mirra from your Google or Microsoft account's connected apps stops the reads immediately. Nothing in Mirra changes on its own — you have to reconnect.
- A password changed. A CalDAV connection stores the password you gave it; changing the account password, or revoking an app password, refuses every read from then on.
- A secret .ics address regenerated. Resetting the secret address in Google, or unpublishing in Outlook, leaves Mirra holding a URL that no longer resolves.
- A Google project still in Testing. Refresh tokens expire after seven days, so the calendar works for a week and then does not.
- A calendar removed at the source. A collection that no longer exists reads as unavailable rather than as empty, which is the honest answer.
Mirra will not tell you that an iCal, CalDAV, Google or Outlook calendar has broken. Those four never write their own status, so the Integrations card keeps saying "connected" while the wall says "Calendar unavailable". If a calendar has gone quiet, check the wall rather than the card.
Related
- Integrations: what they are, and turning them onAn integration is an outside source that several widgets draw on — this explains what turning one on and off does, and why Mirra refuses to turn one off while its widgets are still on a scene.
- Meeting rooms and room panelsA door panel can read a room mailbox's own calendar through one administrator consent — this covers the consent, the Exchange grant that actually gives access, adding rooms, and what is and is not built.
- The agenda widgetWhat the agenda draws from, how far ahead it looks, how it picks between your calendars and a meeting room's, and why an empty agenda is not the same as a broken one.
- Every widget there isThe complete list of widgets Mirra ships with, grouped the way the scene editor groups them, with what each one shows and what it needs before it will show anything.
- A calendar is empty or out of dateWhy a calendar widget shows nothing — an expired authorisation, a changed password, the wrong kind of URL, a date range with nothing in it, or a refresh that has not come round yet.
- The assistant: how a conversation worksHow you summon Mirra, what happens between hearing you and answering you, which tools it can reach, where the transcript goes, and what a conversation costs against your monthly allowance.
- Running Mirra yourselfWhat the three parts of Mirra are, the environment variables they need, what production refuses to start without, and how to turn a Raspberry Pi into a screen.