Matter

Matter devices run over Wi-Fi on top of regular IP and don't share the air with the Zigbee coordinator. In Home Assistant they become regular lights, outlets and sensors: they go on the plan and join groups and presets. The only new part is adding them.

Where it is

	Where
App	Settings → Devices → Matter devices → “Add Matter” or “+” in the plan header → Matter
Web	The “Home” page → “Matter” block (owner only)

What the home needs

• A Matter server. In Home Assistant OS it's the “Matter Server” add-on. Plain Docker has no add-ons — run the server as a separate container (ghcr.io/home-assistant-libs/python-matter-server).
• The “Matter” integration in Home Assistant — it asks for the server address.
• An HA admin token. Pairing needs admin rights. Without them the screen says: “The home has Matter, but this token can't add devices”.
• Bluetooth at home — only to add a device out of the box without a phone: the Matter server's own BLE adapter or an ESPHome proxy in the same room.

Three ways

Way	When it fits
It's already on the network	Matter bridges (SwitchBot, Hue, Aqara), devices shared by another ecosystem. The home looks for the device by IP. A light out of the box can't be added this way
Search over Bluetooth	A device out of the box, if the home has Bluetooth. The home finds it over radio and hands it the Wi-Fi
Via phone and Google	Any device out of the box: the phone in your hand provides Bluetooth. Only in the app and only on a device with Google services. Home Assistant still becomes the owner, not Google

Code from the device

The pairing code is on the sticker on the device or its box:

• 11 digits (manual code),
• 21 digits,
• an MT:… string from the QR code.

In the app you can scan the QR with the camera (“Scan QR”) or type the code by hand. The last digit of the manual code is a check digit: the app catches a typo before sending.

The app parses the code and suggests which way will work. A device out of the box has only Bluetooth in its code — “It's already on the network” is doomed for it from the start.

Search over Bluetooth

1. Enter the code.
2. Pick the Wi-Fi network the device should move to, and the password. In the app the network is picked from a list; each shows its band.
3. “Search over Bluetooth” (on the web — the checkbox “The device is not on the network yet — let the home find it over Bluetooth”, then “Add”).

The password goes to your home's Matter server and nowhere else.

2.4 GHz only

Matter Wi-Fi devices work only on 2.4 GHz. The app marks a 5 GHz-only network as unsuitable.

If Home Assistant has already answered that the Matter server has no radio adapter, the Bluetooth way is closed for this home. Got a BLE proxy — tap “Try Bluetooth anyway”.

For the network list Android needs location turned on and location access. Without them you can type the network name by hand.

Finish by PIN and address

Web only: “Finish pairing by PIN and address…” — an 8-digit PIN and, optionally, the device IP.

Pairing takes up to three minutes. With the Google way, hold the phone close to the device and don't leave the app while it runs.

After adding

The device appears in the “Matter devices in the home” list by itself, as soon as Home Assistant interviews it. One row is one physical device, even if it has many entities.

Tap “place” and pick a room — then as in How a device gets onto the plan.

Share

Give the device to one more ecosystem without taking it away from the home.

Web only: “Share” on the device row. The home opens a pairing window and shows the manual code and QR. The code lives a few minutes — enter it in the other ecosystem's app.

Remove

In the app — “remove” on the row, on the web — “✕”. The device and all its entities disappear from Home Assistant, and the home revokes its keys. After that it accepts a pairing code again. If the device has no power, this takes up to a minute.

What's missing

• Thread — needs a border router, and the home doesn't have one.
• Matter on the link map — Matter has no equivalent of the Zigbee LQI map.