Pairing Matter Devices

Use this guide after completing the Matter and Thread Protocol Setup . Your OpenThread Border Router, Thread integration, Matter Server, and Companion App should all be configured and running before you begin commissioning devices.

Before You Start

Confirm the following before commissioning:

1. The Matter Server integration shows as connected in Settings → Devices & Services.
2. The Thread integration shows an active Thread network with at least one border router.
3. Your phone has received Thread credentials from Home Assistant (see the Companion App Matter over Thread Setup guide).
4. Bluetooth is enabled on the phone being used for commissioning. Matter uses BLE for the initial pairing handshake.
5. Each device’s Matter QR code or numeric setup code (format: XXXX-XXX-XXXX) is captured and accessible.

Sync Thread Credentials to Your Phone

Before commissioning Matter over Thread devices, your phone must have the Thread network credentials so it can pass them to the device during commissioning.

Android

1. Open the Home Assistant Companion App.
2. Go to Settings → Companion App → Troubleshooting.
3. Select Sync Thread credentials.
4. Follow the prompts until the phone confirms that Thread credentials from Home Assistant were added.

iPhone

1. In Home Assistant, go to Settings → Devices & Services and open the Thread integration.
2. Select Configure under Services.
3. At the bottom of the preferred network section, select Send credentials to phone.
4. Confirm the iPhone receives the credentials before continuing.

Commission a Matter Device

1. Open the Home Assistant Companion App on your phone.
2. Tap Settings → Devices & Services.
3. Select + Add Integration and choose Add Matter device (or scan the Matter QR code directly if prompted).
4. Scan the device’s Matter QR code or enter the numeric setup code manually.
5. The app handles the BLE handshake, passes Thread or WiFi credentials to the device, and registers it with the Matter Server.
6. Once commissioning completes, the device appears under Settings → Devices & Services → Matter.

WiFi vs Thread Devices

Matter devices connect over either WiFi or Thread. The device determines which transport it supports — you do not choose during commissioning.

• Thread devices join the Thread mesh network managed by your border router. They benefit from low latency, low power consumption, and mesh reliability.
• WiFi devices connect directly to your home WiFi network. During commissioning, the Companion App passes your WiFi credentials to the device.
• If a device supports both WiFi and Thread and your installation uses Thread, commission it over Thread for mesh benefits.

Tips for Reliable Commissioning

• Commission one device at a time.
• Keep the phone within Bluetooth range of the device during the initial handshake (typically within 5 meters).
• If commissioning fails on the first attempt, power cycle the device and try again. Some devices need a factory reset before a second attempt.
• If your system uses more than one communication protocol, finish setting up and pairing all devices for one protocol before moving to the next.

If Commissioning Fails

1. Confirm the Matter Server is still running under Settings → Devices & Services.
2. Confirm the Thread network is still active (for Thread devices).
3. Re-sync Thread credentials to your phone.
4. Verify Bluetooth is still enabled and the Companion App has Bluetooth permissions.
5. Power cycle the device and attempt commissioning again.
6. Check the Matter Server add-on logs for error details.

For detailed troubleshooting, see the Matter device pairing failures guide .