Home Assistant

How Mirra reaches your home

Home Assistant lives on your own network. Mirra's portal lives in a data centre. Those two facts shape everything here: nothing in the cloud can open a connection to a machine in your living room, and Mirra does not ask you to make one possible.

A paired screen does it instead. The screen sits on the same network as Home Assistant and holds the connection to it. When you tap a light in the portal, or ask the assistant to turn something off, the request travels portal → relay → screen → Home Assistant, and the answer comes back the same way. There is no port forward to open, no tunnel to run, no reverse proxy to maintain and no public hostname to expose.

Two things follow, and both are worth knowing before you start. Control keeps working during an internet outage, because the screen and Home Assistant are talking to each other locally and neither needs Mirra to change a light. And nothing at all reaches your home while every screen is asleep — Mirra will say so rather than pretend otherwise.

Only a screen can see your home network, so anything needing a look at it — testing the connection, refreshing the entity list, running a light rule — needs at least one screen awake. If none is, you are told that specifically rather than given a vague failure.

Connecting Home Assistant

Setup is an address and a long-lived access token, saved once. Both are stored encrypted and handed only to your own paired screens; the portal never dials Home Assistant itself.

The address is the one a screen on your network would use — http://homeassistant.local:8123 is the usual answer. A Nabu Casa address or another public hostname works only if the screen can reach it, and it puts a round trip through the internet into something that was otherwise happening entirely inside your house.

Saving tells every paired screen to reconnect with the new credentials, so a corrected address takes effect without anybody restarting anything.

1. Open Integrations, then Home Assistant

   The Home Assistant card links straight to it — Set up Home Assistant while nothing is connected, Manage once something is.

2. Create a long-lived access token

   In Home Assistant, click your profile at the bottom left, then Security, then Long-lived access tokens, then Create token. Copy it before you close the dialogue; Home Assistant shows it once.

3. Fill in the two fields

   Put the address into Home Assistant URL and paste the token into Long-lived access token.

4. Press Connect

   The button reads Update connection once a connection exists. The panel then shows what it is connected to and how many entities have synced.

5. Turn the integration on

   Saving a connection does not by itself put Home Assistant widgets into the scene editor's palette. That is a separate switch — Turn on, on the Home Assistant card under Integrations.

Home Assistant URL

The address a screen on your network would use. It must begin with http:// or https:// (ws:// and wss:// are accepted too). The screen converts it to a WebSocket address and appends /api/websocket for you, so you do not need to include that.Default: Empty. The placeholder shows http://homeassistant.local:8123.

Long-lived access token

The credential the screen authenticates with. Required the first time, and it must be at least ten characters. On a later save you can leave it blank to keep the token already stored, which is what makes correcting a typo in the address painless.Default: Empty. Blank on an update means keep the current token.

The token carries whatever the Home Assistant account that created it can do, so create it on an account whose reach you are comfortable with. Disconnecting in Mirra forgets the token; it does not revoke it. Revoking is done in Home Assistant, and that is what actually cuts access off.

Checking it from a screen

Once a connection is saved, a Test from a screen panel appears with one button per paired screen — Test via Kitchen, Test via Hall, and so on. Pressing one asks that particular screen whether it is connected, and waits for the answer.

Per screen rather than per household, because that is the question that actually matters. A house with a mirror in the kitchen and one in a spare room may well have only one of them on the same wireless network as Home Assistant. A single household-wide answer would hide precisely the case you are trying to diagnose.

1. Press Test via, followed by the screen's name

   The result appears under the buttons a moment later.

2. Read the result

   Connected to Home Assistant, in green, with the version number where the screen reported one, means that screen has an authenticated connection open. Not connected, in red, is followed by the reason — those reasons are listed further down this article.

What appears in the entity list

The main part of the page is everything your screens have reported, grouped by the area Home Assistant files it under. An entity with no area of its own inherits the area of the device it belongs to; anything left over is grouped under No area. Each row is the friendly name and the current reading, with its unit where it has one.

What Mirra stores is deliberately thin: the entity id, the friendly name, the domain, the state, the area, the unit and the device class. That is enough to draw a picker, to let the assistant know what your house contains, and to run the insight rules. It is not enough to be a copy of your home.

Everything else stays inside the house. Raw attributes never leave your network — not album art, not what somebody is listening to, not a camera's access token. The widgets that need those run on the screen, which already has them. Camera images travel camera to Home Assistant to screen, and never touch Mirra at all.

Two other kinds of thing are folded into the same list, because every entity picker in the scene editor reads it. WLED segments you have added to Mirra directly appear as lights. Cameras you have added to Mirra directly appear as cameras. A WLED controller you have chosen to reach through Home Assistant is left out of the WLED half, so you see one strip rather than two.

Keeping the list fresh

The list is a snapshot, not a live window onto Home Assistant. A screen pushes what it can see shortly after it connects and then every sixty seconds, and Mirra keeps the newest report.

That is invisible right up until the moment it is not. You add a camera in Home Assistant, come straight to Mirra to put it on a wall, and it is not in the picker — at which point "is this list stale, or did I set the camera up wrong?" is unanswerable, and people go looking for a fault that is not there. So the page says when the list was taken, in words rather than a timestamp, and gives you a button.

Refresh now buys no capability at all. The same thing happens by itself within a minute. It only ends the wait.

1. Press Refresh now

   Mirra asks the most recently seen screen, on the grounds that it is the best available guess at one that is awake. That screen is not necessarily the one nearest Home Assistant, and if it cannot answer you are told so.

2. Wait for the list to redraw

   The button reads Refreshing while it waits. The request is awaited all the way to the screen and back, so when the list reloads it is genuinely fresh rather than hopefully fresh.

3. Read the failure, if there is one

   No paired screen to ask means you have not paired one yet. Couldn't refresh, followed by a reason, means the screen it picked did not answer.

Every entity picker in the scene editor carries the same reminder — that the list came from your screen's last sync — with a link back to this page. Entities that vanish from Home Assistant are dropped from Mirra's list on the next sync from the screen that reported them.

The widgets this connection unlocks

Fourteen widgets read this connection. The scene editor groups them by what you are trying to do rather than by how they are built.

Home is the general one: give it a list of entities and it lists them live, toggling lights and switches when you tap them. The rest exist for what a list does badly — a single reading you want legible from across the room, a control you want to reach without hunting for it, or a summary that is worth more than its rows.

• Show one thing — State, Dial, Trend.
• Control one thing — Switch, Button, Slider.
• Rooms and devices — Thermostat, Camera, Now playing.
• The whole house — Home, All secure?, Low batteries, Scene buttons, Energy now.
• Two more that work on Home Assistant lights are core rather than part of this integration, so a household with only WLED — or only Govee, or only Hue — can place them as well: Light, and Light scenes.

The scene editor refuses to place any of the fourteen while the Home Assistant integration is switched off, and refuses to switch the integration off while its widgets are still on a scene — naming the scenes you would have to clear. Turning an integration off never takes anything off a wall for you.

Insights

Every time a screen syncs its entities, Mirra runs a short list of rules over the snapshot and puts anything worth saying at the top of this page. These are plain rules with fixed thresholds rather than anything clever, which is what makes them cheap enough to run on every sync and predictable enough to publish in full.

• Something open with rain coming — a door, window or cover left open when the chance of rain in the next few hours is 50% or more. The forecast is taken from the location set on a weather widget in one of that screen's scenes. With no weather widget there is no forecast, and this rule stays quiet.
• Left open with the house empty — the same doors, windows and covers, when the house counts as empty.
• Lights on with the house empty — two or more lights on with nobody about.
• A door unlocked late — any lock reading unlocked between 22:00 and 06:00.
• A battery running out — anything with a battery device class reading 15% or less.
• A freezer warming up — a temperature sensor with "freezer" in its name reading above −12. The classic expensive thing to miss.
• Unusually high power draw — a power sensor measured in watts reading 4000 W or more.

The same condition is not repeated within six hours. Warnings — the amber Heads up ones — are also sent as a push notification to phones signed in to the household; the quieter Note ones stay on the screen and this page. The page loads the twenty most recent and shows the first eight.

"The house is empty" means the screen doing the sync has recorded nobody in front of it in the last twenty minutes. Presence needs that screen's camera turned on. A household with no presence detection at all therefore counts as permanently empty, so the two empty-house rules can fire while somebody is plainly standing in the room.

When a connection fails

The messages are deliberately different from one another, because they mean different things and want different fixes.

• Home Assistant rejected the access token — the token is wrong, expired, or has been revoked. The screen stops retrying at this point, on the grounds that a bad token will not fix itself. Create a new token, save it here, and the screens reconnect.
• Could not reach Home Assistant — the address did not answer. A wrong hostname, a closed port, no route from that screen's network, or a certificate the browser will not accept for a WebSocket connection. A screen whose clock is badly wrong produces this too, because a perfectly valid certificate looks expired to it.
• That screen is offline, so I can't reach the home network — the screen has no connection to Mirra at all. It is asleep, unplugged, or off the internet.
• The screen didn't answer in time — the connection was open but nothing came back within twelve seconds.
• Couldn't reach the screen, or Relay is not configured — the fault is on Mirra's side of the round trip rather than in your house.

A screen that loses Home Assistant retries on its own, backing off from two seconds up to a minute, and reconnects without anyone pressing anything. The rejected token is the one failure it will not keep trying, which is why that particular message is worth acting on rather than waiting out.

Disconnecting

Disconnect Home Assistant sits in the Danger zone at the foot of the right-hand column. It asks you to confirm, then removes the stored address and token, deletes every synced entity, and tells every screen to drop its connection.

Disconnecting deletes the synced entity list. Widgets on your scenes that name a Home Assistant entity are left exactly where they are — nothing is taken off a wall — but they will have nothing to talk to until you reconnect, and their pickers will be empty in the meantime. The token is forgotten rather than revoked; if revoking is what you meant, do that in Home Assistant as well.