What Matter is
Matter is a smart-home standard backed by Apple, Google, Amazon, Samsung and hundreds of device makers under the Connectivity Standards Alliance. Its promise: buy a device with the Matter logo and it works with every major ecosystem, locally, without a vendor cloud.
A Matter device talks over one of:
- Wi-Fi — joins your normal wireless network
- Ethernet — same, wired
- Thread — a low-power mesh radio (§ 02)
Either way, control traffic is local IP — UDP over link-local IPv6, discovered via mDNS/Bonjour, the same multicast machinery as AirPlay and HomeKit. No cloud round-trips, no vendor app needed for control.
Thread, and what it has to do with anything
Thread is one of the transports Matter can run over: a low-power, self-healing mesh radio (802.15.4 — the same silicon family as Zigbee) built for battery devices that can’t afford Wi-Fi’s power budget — sensors, buttons, locks.
Thread devices can’t talk IP to your LAN directly; they need a Thread Border Router to bridge the mesh onto your network. You probably already own one — by 2026 almost every ecosystem hub is a TBR:
- Apple — HomePod mini, HomePod 2, recent Apple TV 4K
- Amazon — Echo 4, Echo Hub, Echo Studio, recent Echo Shows, eero
- Google — Nest Hub 2, Nest Hub Max, Nest Wifi Pro
Two distinctions that save a lot of confusion:
- Thread ≠ Matter. Thread is plumbing; Matter is the language. Some Thread devices speak HomeKit-over-Thread or proprietary protocols instead.
- A Matter Wi-Fi device needs no border router at all. It’s just another client on your LAN.
Thread status in this plugin
Works — real hardware
Thread devices ride the normal share-model flow — the same Apple Home → pairing code path as Wi-Fi. Validated on both transports: a Tapo P110M (Wi-Fi, with live energy metering) and an Aqara FP300 presence multi-sensor (Thread, via a HomePod border router — a ten-second join, all four sensors, unprompted live reports).
Here’s why it works. The one Thread operation the plugin’s controller stack (matter-server, matter.js) can’t do is first-admin commissioning — handing a factory-fresh device the Thread network credentials over Bluetooth. In the share model that step is always the first ecosystem’s job: Apple Home (or Alexa, or Google Home — § 07) provisions the device onto its own mesh with its own radios. From then on the device is just an IP endpoint — the ecosystem’s border router routes IPv6 between mesh and LAN, so when the plugin joins as a second admin over IP it neither knows nor cares that the last hop is Thread.
Practical caveats: matter-server is Alpha, and battery Thread devices are “sleepy” (they wake on long intervals) — which is where an alpha controller is most likely to be flaky. That said, the first Thread device validated here was exactly such a sleepy battery sensor, and it behaved. And should a true gap ever surface, the WebSocket protocol the plugin speaks is deliberately compatible with Home Assistant’s python-matter-server — a different backend is a swap, not a rewrite.
Bluetooth, commissioning, and why this plugin needs neither
When you pair a brand-new Matter device (“commissioning”), the very first step usually happens over Bluetooth LE: the commissioner sends the device your Wi-Fi credentials (or Thread network key) over BLE, the device joins the network — and BLE is never used again.
That’s why phones and ecosystem hubs make good first commissioners: they have BLE radios and, for Thread, the network credentials. A headless Mac running Indigo is a poor first commissioner — matter-server runs without BLE on macOS, and macOS has no Thread credential store.
This plugin sidesteps the problem entirely with the share model — the plugin’s founding architecture decision:
That’s only possible because of Matter’s best feature: multi-admin.
Fabrics & multi-admin: one device, many controllers
A Matter fabric is a controller’s trust domain — a set of cryptographic credentials a controller installs on a device. The crucial design choice in Matter is that a device can belong to several fabrics at once. The spec floor is five — and since each fabric slot costs the device persistent storage, the floor is also what most devices ship. Treat five as your planning number. Each controller talks to the device directly and locally; none of them knows or cares about the others.
A single plug in this house happily serves four admins simultaneously:
- Apple Home
- Indigo — this plugin’s fabric
- The vendor’s app
- Home Assistant
— with no cross-interference. Removing one fabric (“Remove from Indigo”) leaves the others untouched; only a factory reset wipes them all.
The plugin’s fabric lives inside matter-server’s storage directory. It is the single point of total loss — destroyed, every device must be re-commissioned — which is why the plugin ships fabric backup and restore (menu items: Back up the Matter fabric… / Restore a fabric backup…).
0xFFF1, registered as “Matter
Test”. A custom name there needs a paid, certified CSA Vendor ID — the same limitation
every non-certified controller has (Home Assistant shows up the same way). Purely
cosmetic; control and security are unaffected.
The pieces, end to end
| Piece | Role |
|---|---|
| Apple Home | First commissioner. BLE onboarding and, for Thread, the border router. Alexa or Google Home can play this role instead (§ 07). |
| Domio | The add device UX. Relays the pairing code to the plugin. Not in the control path afterwards. |
| indigo-matter | Holds the Indigo fabric, translates Matter clusters ↔ Indigo device types, serves the Domio API, supervises matter-server. |
| matter-server | The Matter controller stack (matter.js). The plugin drives it over a local WebSocket. |
| Indigo | Where devices live. A Matter plug is a relay, a Matter bulb is a dimmer — first-class citizens in every Indigo feature. |
Adding a device
- Commission in Apple Home first. Scan the device’s QR code in the Home app. If your main Wi-Fi runs “advanced” features (WPA3-only, 802.11r, band steering), a basic 2.4 GHz IoT SSID is far more reliable — but it must be the same subnet as the Indigo Mac (§ 11).
- Open pairing mode. Home app → device settings → Turn On Pairing Mode. A fresh one-time setup code appears — the printed QR code will not work for this.
- Enter the code, in whichever is closer to hand — Domio (add Matter device → code, name, room) or Indigo (Plugins ▸ Matter ▸ Commission device by setup code…). Either way the plugin joins as a second admin over IP and creates the Indigo device(s). Discovery can take a couple of minutes on a busy LAN — the plugin waits up to five.
- Done. The device appears in Indigo (the room becomes a device folder), controllable from everything Indigo offers, plus Domio.
The two entry points are equals, and for the same reason: once the code exists, the rest is plain IP. The plugin menu’s Commission device by setup code… does exactly what Domio does — paste the pairing-mode code, Wi-Fi or Thread alike. Neither is a fallback for the other, and Domio is not required.
Pick on convenience, not capability. Domio wins when you’re standing at the new device with the Home app open and the code has just appeared — it’s the next tap on the same phone, and you never go near the Mac. The plugin menu wins when you’re already in Indigo, or have the code some other way. (And if a device is already on your network but was never commissioned by anyone, its printed code works directly in either entry point.)
Removing: plugin menu → Decommission Matter device… — removes only the Indigo fabric; the device stays in Apple Home and everywhere else. Deleting the Indigo device alone does not work — by design the plugin recreates it at the next reconcile. Only a factory reset on the device itself removes everything.
Don’t have Apple Home? Alexa or Google work too
The plugin and Domio never care which ecosystem is admin 1 — they just consume a pairing code. Apple Home is the smoothest path for Domio users (you’re on an iPhone already), but any Matter ecosystem can play the role:
- Alexa: commission in the Alexa app, then device settings → Other assistants and apps → it generates a pairing code. For Thread, a TBR-capable Echo plays the HomePod’s part.
- Google Home: commission in the Google Home app, then device settings → Linked Matter apps & services → share. Nest Hub / Nest Wifi are the TBRs.
Sharing with other platforms — and vendor apps
Multi-admin works in every direction: the same pairing-mode trick adds the device to Google Home, Alexa or Home Assistant alongside Indigo.
Adding a device to its vendor app is often worth doing once, because firmware updates usually ship through it (§ 10).
Bridges
A Matter bridge exposes non-Matter devices (Zigbee, proprietary RF) as Matter endpoints — Aqara, SwitchBot and Hue hubs all do this. The plugin supports bridges: each bridged child appears as its own Indigo device. It’s also a practical route into Indigo for the Zigbee sensors you already own behind such a hub.
What’s supported
| Matter capability | Indigo device |
|---|---|
| On/Off — plugs, switches, lights | Relay |
| Dimming (Level Control) | Dimmer |
| Colour & colour temperature | Colour dimmer (RGB + white-temp UI) |
| Temperature · humidity · occupancy · contact · illuminance · pressure · flow | Sensor — one device per measurement |
| Thermostats (incl. attached fan) | Thermostat |
| Standalone fans | Speed-controlled dimmer |
| Window coverings | Dimmer (100% = open) |
| Door locks | Relay with lock UI |
| Valves (water / irrigation) | Relay with flood-safe toggle behaviour |
| Buttons / scene switches | Button device firing Indigo trigger events |
| Smoke / CO alarms | Sensor (alarm latch) |
| Air quality — AQI · CO₂ · PM2.5 · TVOC | Sensors, one per metric |
| Power & energy metering | curEnergyLevel (W) / accumEnergyTotal (kWh) on the primary device |
| Battery level | batteryLevel on every device of the node |
| Bridges | One Indigo device per bridged child |
| Anything else | A visible placeholder listing the unsupported clusters — so you can report it, not lose it |
A node exposing several capabilities gets several Indigo devices (a multi-sensor becomes one device per measurement); secondary capabilities like energy and battery merge into the primary device’s states.
Firmware updates — they matter more than usual
Matter firmware arrives by two routes: the device vendor’s app, and the ecosystems themselves — those that act as Matter OTA providers push updates too (Apple Home auto-updates Matter accessory firmware; observed on this house’s Tapo plug). The vendor app typically gets releases first, so check there when you’re waiting on a feature. And vendors are still actively adding Matter features via firmware.
Rule of thumb: if a device seems to be missing a capability you know it has, check firmware first. The plugin’s diagnostics endpoint (API.md §3.5) lists exactly which clusters a node advertises — settling the “device or plugin?” question in one request.
Troubleshooting
Network first. Matter assumes a flat residential network. The plugin, the device and matter-server must share one subnet/VLAN: discovery is mDNS multicast, transport is link-local IPv6, and neither crosses routers. You do not need “IPv6 from your ISP” — link-local addresses are self-assigned and always present.
Common failure modes, in rough order of likelihood:
- Commissioning fails in Apple Home on the main SSID. Advanced Wi-Fi features break many 2.4 GHz-only IoT radios during onboarding. Use a backward-compatible IoT SSID — on the same subnet.
- Apple Home controls it, Indigo can’t reach it. The IoT SSID is on a separate VLAN, or AP client isolation is blocking station-to-LAN traffic. (Apple Home can ride BLE and hubs; the plugin is pure IP, so it notices first.)
- “1 discovered, attempt failed” / discovery timeouts. Pairing-mode windows are short (~15 min) — regenerate the code and commission promptly. mDNS snooping on managed switches also causes this.
- Commissioning times out, then the device appears anyway. LAN discovery can exceed 60 s; the plugin waits 300 s and reconciles late joins. Give it the full window.
- Unreachable after a vendor-app setup or firmware update. Normal for a minute or two while it reboots; the plugin marks it unreachable and self-clears. Persistently dead usually means a factory reset wiped the fabric — re-commission.
- Capability missing. Firmware first (§ 10), then diagnostics.
Backups. Back up the fabric after commissioning anything you’d hate to re-pair. The plugin keeps rotating zips; restore is menu-driven and reversible.