The share model
A headless Mac running Indigo is a poor first commissioner. The plugin’s Matter stack runs without Bluetooth on macOS, and macOS has no Thread credential store — so the one job that needs a BLE radio and network credentials is the one job it can’t do. The plugin’s founding architecture decision sidesteps the problem entirely.
This is why Thread works here at all. The admin-1 ecosystem provisions the device onto its own mesh with its own radios; from then on the device is just an IP endpoint, and that ecosystem’s border router routes IPv6 between mesh and LAN. When the plugin joins as a second admin it neither knows nor cares that the last hop is Thread.
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 (§ 04). |
| 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). Beta, exact-pinned to 1.2.2, installed and supervised by the plugin. Driven 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. |
The plugin holds one fabric, and it lives inside matter-server’s storage directory. It is the single point of total loss — destroy it and every device must be re-commissioned — which is why the plugin ships fabric backup and restore (Back up the Matter fabric… / Restore a fabric backup…).
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 (§ 07).
- 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 (advanced)…). 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. 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. The plugin menu wins when you’re already in Indigo, or have the code some other way. (If a device is on your network but was never commissioned by anyone, its printed code works directly in either entry point.)
Removing: Plugins ▸ Matter ▸ 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 removes everything.
Any ecosystem can be admin 1
The plugin and Domio never care which ecosystem commissioned the device — 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.
The same trick works in every direction: the pairing-mode code that adds a device to Indigo will just as happily add it to Home Assistant, or to a second ecosystem, alongside. Adding a device to its vendor app once is often worth doing too, because firmware updates usually ship there first (§ 07).
A Matter bridge — an Aqara, SwitchBot or Hue hub publishing its Zigbee devices as Matter endpoints — is supported the same way: each bridged child becomes its own Indigo device. It is a practical route into Indigo for Zigbee sensors you already own.
What lands in Indigo
| 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 the power source says it powers (usually the whole 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.
Proven on real hardware
Wi-Fi · validated Thread · validated
Both transports have run the full share-model flow on a production Indigo server:
- TP-Link Tapo P110M — Wi-Fi. On/off plus live energy metering. The energy clusters only appeared after Tapo’s Matter 1.3 firmware update, and the existing Indigo device gained its energy states automatically: no restart, no re-pairing.
- Aqara FP300 — Thread, via a HomePod border router. A ten-second join, all four sensor endpoints, battery fan-out, unprompted live reports. First try, and from a third-party tester rather than the author.
The one Thread operation the controller stack can’t do is first-admin commissioning — handing a factory-fresh device Thread credentials over BLE. The share model never asks it to. And should a real gap ever surface, the WebSocket protocol the plugin speaks is deliberately compatible with Home Assistant’s python-matter-server — a different backend would be a swap, not a rewrite.
The full method and record is № 4 — The Proving Ground.
When it doesn’t work
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.
- A capability you know the device has is missing. Check firmware first — vendors are still actively adding Matter clusters by update, and Apple Home auto-updates Matter accessory firmware. Then check the plugin’s diagnostics endpoint (API.md §3.5), which lists exactly which clusters a node advertises and settles the “device or plugin?” question in one request.
Back up the fabric after commissioning anything you’d hate to re-pair. The plugin keeps rotating zips; restore is menu-driven and reversible.