Guide · Your other devices
The device that won't show up on your TV
Theatrium shows what's already in your Apple Home. So when a smart plug, blind, older bulb or camera never appears on the dashboard, it's usually because it never made it into Apple Home in the first place — the brand simply didn't build in HomeKit support. There's a free, well-established fix called Homebridge, and there's also a good chance you don't need it. Four questions will tell you which.
Open the Home app on your iPhone or iPad. What do you see?
It's the app with the orange house icon, built into every iPhone. If you can't spot it, swipe down on the home screen and search for "Home".
Is there smart-home kit in your house that isn't in that list?
Things you control with the manufacturer's own app rather than Apple's. These are the usual suspects:
Do you use Home Assistant?
Home Assistant is free software that runs on a small computer in your house and speaks to almost every smart-home brand there is. Theatrium works beautifully with it — and it's a bigger commitment than most people want.
Which computer in your home could stay switched on?
Homebridge is a small program that has to keep running — when it sleeps, those devices drop off your dashboard until it wakes. This one answer decides how easy the rest will be, so it's worth a moment's thought.
You don't need Homebridge
Everything you own is already in Apple Home, which is all Theatrium needs. If something still isn't appearing on the TV, it's almost always one of two small things rather than a missing bridge:
- The accessory has no room assigned. Theatrium builds the dashboard out of your Apple Home rooms, so anything roomless has nowhere to land. Fix it in the Home app.
- This Apple TV isn't a Home Hub yet, or is signed into a different iCloud account from your home.
You'll need to borrow an iPhone — once
Apple Home can only be set up and added to from an iPhone or iPad; there's no way to do it from the Apple TV or a computer. Homebridge is paired by scanning a code in the Home app, so you do need one of those in your hands.
The good part: it's a one-time job. Once Homebridge is paired and your accessories are in Apple Home, everything keeps working from the Apple TV alone. Borrowing a family member's iPhone for ten minutes is genuinely enough.
If that isn't practical, Home Assistant is the better path for you — it's set up entirely from a web browser on any computer, and Theatrium reads it just as happily.
Add the device to Home Assistant instead
You already have the more capable tool. Putting Homebridge in the middle would mean running two bridges to do one job, and every extra link is another thing to go wrong.
- In Home Assistant, go to Settings › Devices & services and add the integration for your device's brand. There are well over a thousand.
- In Theatrium, set your data source to Home Assistant. It finds your server on the network and fills in the address itself — you sign in by scanning a code with your phone, with no access token to create.
- You also get what only a server can give: history sparklines, who's-home, weather and system metrics.
Home Assistant does more. Homebridge does less, faster.
Both will get your missing device onto the TV. They're aimed at different appetites, and it's worth picking deliberately rather than drifting.
- Home Assistant — a proper home server. Supports nearly every brand, and unlocks Theatrium's richest dashboard: history graphs, presence, weather, system metrics, media from any speaker. Expect an evening to set up, and it becomes something you tend to now and then.
- Homebridge — one narrow job, done well: it makes non-HomeKit devices appear in Apple Home. About thirty minutes, three pasted commands, then you can forget it exists. It won't give you history or presence, because Apple Home doesn't have them.
If the honest answer is "I just want that one plug on my TV screen", Homebridge is the right size of solution.
Homebridge on your Mac
This is the easiest version of this job. A Mac that stays on is an excellent host: pairing with Apple Home is reliable, which is the part that actually matters, and the whole thing takes about half an hour.
- You'll paste three commands into Terminal. Everything after that is done by clicking in a web page.
- Two pop-ups will appear during setup. Say yes to both — one of them is the single most common reason people get stuck.
- You'll pair with Apple Home before adding any devices, so if anything is wrong you find out in ten minutes rather than two hours.
Homebridge on Windows — with one honest caveat
You can install Homebridge straight onto Windows and plenty of people run it happily. But there's a catch we'd rather tell you now than let you discover at 11pm:
Homebridge's own documentation warns that some iPhones cannot connect to Homebridge running natively on Windows 10 or 11. The install looks perfectly successful, and then the pairing step simply never finds the bridge. It isn't a setting you can change, and nobody can tell you in advance which side of that line your network falls on. The official advice is to run it on Linux instead.
So here's the sensible approach: try it — you'll know inside ten minutes, because pairing is deliberately step 5, before you've invested any effort in plugins. Uninstalling takes one command and leaves nothing behind.
If pairing does fail, don't fight it. A Raspberry Pi is the well-trodden road for Windows households: about £50, no command line whatsoever, and it can sit in a cupboard drawing less power than a phone charger.
Homebridge on a Raspberry Pi
Genuinely the gentlest route, and the one we'd suggest to anyone without a Mac. The Homebridge team publish a ready-made image, so there is no typing and no Terminal — you write it to a memory card with an ordinary app that has buttons.
- What to buy: a Raspberry Pi 4 or 5, its official power supply, and a microSD card (32 GB is plenty). Around £50–£75 all in.
- What you do: install Raspberry Pi Imager on your Mac or PC, choose the Homebridge image, write the card, put it in the Pi, plug the Pi into power and — ideally — an Ethernet cable.
- Then: open the Homebridge dashboard in your browser and rejoin this guide at step 4. Steps 1 to 3 are the bit you've just skipped.
- It sips electricity, so leaving it on permanently costs pennies, and nothing else on your desk gets disturbed.
Something has to stay awake — but it needn't be a computer you use
Homebridge only helps while it's running, so an always-on host isn't optional. That sounds like bad news and usually isn't, because the cheapest option is also the best one for this job. In rough order of what we'd suggest:
- A Raspberry Pi (~£50). Set up with a normal app, no command line, lives in a cupboard, costs pennies a year to run. It isn't a computer you use — it's an appliance you forget about.
- A NAS you already own. Synology and QNAP boxes are already on all the time and both can run Homebridge. If there's one in the house, that's your answer.
- Check for a hub from the brand itself. Some manufacturers sell a bridge that speaks HomeKit natively — Philips Hue's bridge is the best-known example. If your devices have one, it beats Homebridge outright: no computer, no maintenance, no pairing quirks. Worth ten minutes of searching before you buy anything else.
- Or let it go for now. Theatrium is still worth having on whatever is in Apple Home, and Apple TV-only mode gives you weather, radar, webcams, markets, news, a calendar, the clock and the full visualiser with no smart home at all.
How it works
Where Homebridge fits
One picture is worth the whole explanation. Homebridge adds a single translating hop, and everything downstream of it carries on exactly as before.
Check whether your brand sells a HomeKit hub. Some manufacturers — Philips Hue most famously, but also Aqara, SwitchBot and others — sell a bridge that speaks HomeKit natively. If yours does, buying it beats Homebridge outright: no computer to keep awake, nothing to maintain. Ten minutes of searching for "your brand + HomeKit" can save you this entire page.
The install
Nine steps, in order
Pick your computer and the page will show only the instructions that apply to you. Please don't skip ahead — step 5 is a deliberate checkpoint that catches problems while they're still cheap to fix.
Install Node.js
Homebridge is written in JavaScript, and Node.js is the thing that runs it. It's a normal, signed installer from a long-established project.
- Go to nodejs.org and download the LTS version — LTS means "long-term support", the stable one. Take the
.pkginstaller for macOS. - Open the downloaded file and click through, entering your Mac password when asked.
- Now open Terminal: press
⌘ Space, typeTerminal, press Return. A window of plain text appears — that's where things get pasted.
- Go to nodejs.org and download the LTS version — the stable one. Take the
.msiinstaller for Windows. - Run it and click through, accepting the defaults.
- Now open the Node.js command prompt as an administrator, which genuinely matters: click Start, type
Node.js command prompt, right-click the result, choose Run as administrator, and click Yes.
node -v
✓ You should see a "v" and some numbers, like v22.14.0. Any version number means it worked. If you get command not found or not recognized, close the window, open a fresh one and try again — the installer's changes only reach newly opened windows.
Install Homebridge itself
One command fetches Homebridge and its web dashboard — the friendly screen you'll use for everything from here on.
sudo npm install -g homebridge homebridge-config-ui-x
It will ask for your Mac password. As you type it, nothing appears on screen — no dots, no stars, no cursor movement. That's normal, not a fault. Type it and press Return.
npm install -g homebridge homebridge-config-ui-x
✓ A minute or two of scrolling text, ending in a summary of added packages with no red ERR! lines. Yellow warnings are fine and can be ignored.
If you've read an older tutorial elsewhere, it may include --unsafe-perm in this command. That's no longer needed and on current versions can cause an error — use the command exactly as written.
Set it to start by itself
This turns Homebridge into a background service, so it starts with the computer and keeps running with no window open.
sudo hb-service install
On macOS Sequoia and newer, a box appears asking whether node may find devices on your local network. Click Allow. If you miss it or click Don't Allow, Homebridge runs perfectly but is completely invisible to your iPhone, with no error message to explain why. You can set it at any time: System Settings › Privacy & Security › Local Network, then switch node on.
hb-service install
A Windows Defender Firewall box will pop up about node or Node.js JavaScript Runtime. Tick Private networks and click Allow access. If you dismiss it or click Cancel, your iPhone will never find Homebridge. If you get it wrong, the firewall fix is in troubleshooting.
✓ The text ends by telling you Homebridge is installed as a service, and gives you a web address. It's now running.
Open the dashboard and make your login
Good news: the command line is finished. Everything from here happens in a browser.
- On that same computer, open Safari, Chrome or Edge and go to
http://localhost:8581 - Create your username and password, and write them down. There's no "forgot password" email, because there's no email and no account anywhere — this login exists only on your own machine.
- If it asks you to sign in before offering to create an account, the older default is username
adminand passwordadmin. Sign in, then change it immediately under Users.
✓ You're looking at the Homebridge dashboard: a status panel, a QR code, and a menu across the top. This page is your control centre from now on — bookmark it.
localhost only works on the computer itself. From your phone or another laptop, use that computer's address on your network instead, like http://192.168.1.42:8581 — the dashboard's status screen shows you the right one.
Pair with Apple Home — now, before adding any devices
This is the checkpoint. Pairing is the step most likely to fail, and it costs nothing to test while your setup is still empty.
- The dashboard's status screen shows a QR code.
- On your iPhone, open Home, tap + › Add Accessory, and point the camera at it.
- Your iPhone will warn you this is an Uncertified Accessory. Expected — Homebridge isn't a commercial product with Apple's licence. Tap Add Anyway.
- Give it any room. It's only the bridge itself, not something you'll interact with.
✓ "Homebridge" now appears in your Home app, and the dashboard shows it as paired. Stop and confirm this before going on.
Don't add devices and hope it settles down — it won't. Go to When something goes wrong and work through My iPhone can't find Homebridge. On Windows, this is also where you learn whether the native-Windows limitation affects you.
Add your devices, one plugin at a time
A plugin is a small add-on that teaches Homebridge to speak to one brand. All of this is clicking — no more commands.
- Click Plugins and search for your device's brand:
tuya,ring,tado,broadlink,roborockand so on. - Prefer results marked Verified, and among similar options take the one with more downloads and a recent update. A plugin nobody has touched in three years will usually disappoint you.
- Click Install. A settings window opens — normally you enter the same account details you use in that brand's own phone app.
- Save, then Restart Homebridge when prompted. Add one plugin, restart, confirm it worked, then add the next. If something breaks you'll know exactly what caused it.
✓ Your devices appear in the Home app within a minute of the restart, and you can switch them on and off from there.
One rule worth keeping: never edit config.json by hand, and never open it in a word processor — smart quotes and auto-formatting corrupt the file and Homebridge will refuse to start. Everything you need is in the dashboard's own settings screens.
Tidy up names and rooms in the Home app
Theatrium builds its dashboard from Apple Home's own rooms and names, so five minutes here decides how good it looks on your wall.
- Give every new accessory a real room. Anything left roomless may not appear where you expect it.
- Rename anything cryptic.
TY-0x8813-Socket-2becomes Reading Lamp. These are the names you'll read from across the room. - Theatrium's Light Sync drives two colours — one for your overheads, one for your lamps — so it helps to have your lights split sensibly between overhead and accent lighting.
✓ Everything has a sensible name and sits in the right room.
Point Theatrium at Apple Home
The part you came for.
- Open Theatrium on your Apple TV. On first launch, choose Apple Home on the "Choose your backend" screen. Already past setup? Settings › Connection and switch the data source.
- tvOS asks permission once — accept it. First load takes ten to twenty seconds while your accessories stream in.
- Your rooms, lights, climate, cameras, locks, covers, sensors and scenes appear — the Homebridge ones now among them.
- Set up Light Sync in Theatrium's settings and tune the intensity to taste.
✓ The device that started this whole exercise is on your TV, and you can control it from the sofa.
Make it stay working
Homebridge only helps while it's running. Ten minutes now prevents the most common complaint of all: "it worked yesterday".
- Stop it sleeping. System Settings › Energy (or Battery › Options on a laptop) › turn on Prevent automatic sleeping when the display is off. On a desktop Mac, also enable Start up automatically after a power failure.
- Log in automatically. System Settings › Users & Groups › Automatic login. Without it, Homebridge may not come back after a power cut until somebody types a password.
- Closing a MacBook's lid suspends Homebridge. Leave it open, attach an external display, or use a desktop Mac.
- Stop it sleeping. Settings › System › Power › set Sleep to Never when plugged in.
- Windows Update restarts interrupt Homebridge. Set your active hours so restarts land when nobody's watching Theatrium.
- Homebridge runs as a Windows service, so it starts at boot without anyone signing in.
- Turn on backups. In the dashboard: menu › Backup/Restore › Scheduled Backups. A backup restores your plugins, your settings and your Apple Home pairing, so you never have to re-add every accessory by hand. This is the most valuable five minutes on this page.
- Update occasionally. The dashboard tells you when Homebridge, a plugin or Node.js has an update. Do Homebridge and plugins first, Node.js only when the dashboard specifically asks — and take a backup before any of it.
- Give the computer a fixed address in your router settings (a "DHCP reservation" or "static lease"), so the dashboard is always at the same address.
Troubleshooting
The seven things that actually break
Nearly every failed setup is one of these. Work down in order — the earlier ones are more common and quicker to rule out.
Nothing loads at localhost:8581
Homebridge isn't running. Ask it directly:
sudo hb-service restart hb-service logs
hb-service restart hb-service logs
Read the last twenty lines or so. Homebridge is usually explicit about what upset it, and the culprit is very often the most recently added plugin. Press Ctrl + C to stop watching the logs.
Also check the number: it's 8581, not 8851 or 8518.
My iPhone can't find Homebridge when I try to pair
This is the big one. Try these in order — each is a genuinely different cause.
- Same network? Your iPhone and the computer must be on the same Wi-Fi — not a guest network, not an IoT-only network. Separate 2.4 GHz and 5 GHz names on the same router are usually fine; separate networks are not.
- Any VPN running? Turn off VPN software on both the iPhone and the computer, then retry. VPNs routinely block the discovery traffic pairing depends on.
- Mac only — Local Network permission. System Settings › Privacy & Security › Local Network › make sure
nodeis on. This silently breaks pairing and is the most common Mac cause by a wide margin. - Windows only — firewall. Control Panel › Windows Defender Firewall › Allow an app through firewall › find Node.js JavaScript Runtime and tick Private. If it isn't listed, add it.
- Change how Homebridge announces itself. In the dashboard: menu › Settings › Homebridge Settings › mDNS Advertiser. Switch from Ciao to Bonjour HAP (or back), restart, try again. Free, quick, and it fixes a surprising share of cases.
- Windows only — install Apple's Bonjour. Some Windows users report success after installing Apple's Bonjour Print Services for Windows, which adds Apple's own discovery service to the machine. Worth a try before giving up.
- Router features. Look for anything called AP isolation, client isolation or IGMP snooping, and turn the first two off. Mesh kit from different manufacturers mixed together is a known source of this.
On Windows, know when to stop. If you've worked through all of the above on a native Windows install and your iPhone still can't see the bridge, you've most likely hit the documented Windows limitation — Homebridge's own guide warns about exactly this and recommends Linux instead. It isn't your fault and no setting will rescue it. Uninstall and move to a Raspberry Pi.
The Home app says it's already added, or pairing won't take
This happens after a reinstall, or when an earlier attempt half-succeeded: Homebridge and your Home app disagree about whether they know each other.
- In the Home app, remove any existing Homebridge accessory.
- In the dashboard: menu › Settings › Unpair Homebridge / Reset Pairing, then restart Homebridge.
- A fresh QR code appears — pair again from step 5.
Your plugins and their settings survive this. Only the Apple Home pairing resets, so you may need to reassign rooms afterwards.
Devices show as "No Response" in the Home app
- Is the computer awake? Overwhelmingly the usual answer. Revisit step 9.
- Did the computer's network address change? Give it a fixed address in your router.
- Is one plugin dragging everything down? Open that plugin's settings, look under Bridge Settings and enable Child Bridge. It then runs in its own process, so its problems stay its own. You'll need to pair that child bridge in the Home app, exactly as in step 5.
- Is your Apple TV acting as Home Hub? Check Home Settings › Home Hubs & Bridges in the Home app — you want this Apple TV listed as Connected.
Devices are in the Home app, but Theatrium doesn't show them
- Assign a room to every accessory. Theatrium builds its dashboard from your rooms, so a roomless accessory has nowhere to appear. This fixes it most of the time.
- Force-quit and reopen Theatrium so it re-reads your home.
- Confirm Theatrium's data source is Apple Home — Settings › Connection.
- If a device is in the Home app, in a room, and Theatrium still doesn't list it, that's worth telling us about — some accessory types don't have a card yet.
It worked yesterday and now it doesn't
In order of likelihood: the computer slept or shut down; an update restarted it mid-flight; the network address changed; a plugin auto-updated and broke. Restart first, then read the logs — they cover all four.
sudo hb-service restart
hb-service restart
I want to undo all of this
Removing Homebridge is quick and leaves nothing behind. Remove the Homebridge accessory from your Home app first, then:
sudo hb-service uninstall sudo npm uninstall -g homebridge homebridge-config-ui-x
hb-service uninstall npm uninstall -g homebridge homebridge-config-ui-x
Node.js can then be removed like any other app if you'd rather not keep it. Nothing about your existing Apple Home, your Apple TV or Theatrium is affected.
Keeping it safe
Four house rules
- Never share your pairing QR code or setup PIN. Anyone who has it and can reach your network can add your home to their own Home app. Blur it before posting dashboard screenshots in forums.
- Never open port 8581 to the internet. The dashboard is designed for your home network only. To reach it while away, use your home network's own VPN — don't forward the port on your router.
- Judge plugins before installing them. They're written by volunteers and run with real access to your accounts. Prefer Verified ones, check when they were last updated, and be wary of anything asking for credentials to something valuable.
- Take a backup before every change. One click in the dashboard, and it turns a bad evening into a two-minute fix.
Still stuck
Asking for help well
Whether you ask us or the Homebridge community, these five facts get you a real answer instead of twenty questions.
- Computer
- Mac, Windows or Raspberry Pi — and its OS version
- Node version
- run
node -v - Homebridge version
- shown on the dashboard status screen
- Furthest step reached
- e.g. "step 5, iPhone never finds the bridge"
- End of the log
- run
hb-service logsand copy the last 30 lines
Homebridge problems — installing, plugins, pairing, a device that won't reach the Home app — are best taken to the Homebridge community, who know their own software far better than anyone else does. Theatrium problems — something is in your Home app and in a room but doesn't show on the TV, or Light Sync isn't behaving — come to hello@theatrium.info or r/TheatriumApp.
One thing worth saying plainly: Homebridge is an independent open-source project — not part of Theatrium, and nothing to do with Apple. We're glad to help you get it talking to Theatrium, but we don't control it, and a plugin that stops working is between you and that plugin's author.
Commands and warnings on this page follow the official Homebridge installation guides for macOS and Windows. Homebridge changes over time — if something here disagrees with the official wiki, trust the wiki.