Misleading prompt when sharing Matter device

[NoRi2909]

The problem

When clicking "SHARE DEVICE" for a device in the Matter integration the following alert comes up:

For all the devices I tested this is exactly the wrong thing to do, as it will disconnect the device from Home Assistant causing the next step to fail.

Instead it's correct to not touch the device at all and simply proceed to the next step with the QR code, where HA even tells the user "Your device is ready to be added to another Matter platform".

Scanning the QR code from the other platform, Google Home in my case, worked for every device I tested fron several different vendors.

Things are made worse because Google Home always tells the user to enable commissioning mode when adding a new device , instead of asking if the device is already set up with another platform (like the HA app does). Most users will now press and hold the button on the device making absolutely sure that the whole process will fail.

So you should simply remove the above alert from the sharing process if HA can connect to the device and initiate the pairing itself.

What version of Home Assistant Core has the issue?

core-2024.9.1

What was the last working version of Home Assistant Core?

No response

What type of installation are you running?

Home Assistant OS

Integration causing the issue

Matter (BETA)

Link to integration documentation on our website

https://www.home-assistant.io/integrations/matter

Diagnostics information

No response

Example YAML snippet

No response

Anything in the logs that might be useful for us?

No response

Additional information

No response

[home-assistant[bot]]

Hey there @home-assistant/matter, mind taking a look at this issue as it has been labeled with an integration (matter) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of `matter` can trigger bot actions by commenting: - `@home-assistant close` Closes the issue. - `@home-assistant rename Awesome new title` Renames the issue. - `@home-assistant reopen` Reopen the issue. - `@home-assistant unassign matter` Removes the current integration label and assignees on the issue, add the integration domain after the command. - `@home-assistant add-label needs-more-information` Add a label (needs-more-information, problem in dependency, problem in custom component) to the issue. - `@home-assistant remove-label needs-more-information` Remove a label (needs-more-information, problem in dependency, problem in custom component) on the issue.

_{^{(message by CodeOwnersMention)}}

---

matter documentation matter source _{^{(message by IssueLinks)}}

[marcelveldt]

Well, its a matter of how you read this sentence. Most people read this as the action that is going to be being performed when you press that button below. No text here is saying that you need to reset the device.

@c0ffeeca7 do you have an idea how we could rephrase this text a little bit so its more clear ?

[NoRi2909]

OK, English is not precise here as you can read this both ways.

The German localization definitely understood it the wrong way as it's currently:

This is even more directed at the user saying "Do enable …" and made me understand the English original the same way.

By adding an "s" in English you could already mitigate the issue a bit

Enables commissioning mode on the device to pair it to another Matter controller.

Much better to make sure that all localizations are correct, too:

Clicking on "Share Device" enables commissioning mode …

And you might want to add a "Cancel" button here as well to make this a proper alert message.

[NoRi2909]

FYI, here a screenshot of what the Google Home app on Android displays after scanning the QR code provided by Home Assistant:

As you can see Google Home does not differentiate whether it's the first Matter controller here or the device was put into commissioning mode by an existing controller. This adds to the possible misunderstanding of the whole process.

So it makes sense for HA to explain on top that the user should not fiddle with a paring button in the device here at all.

[marcelveldt]

Ah yeah, the google popup is very helpful for NEW devices but indeed troublesome for existing devices.

[c0ffeeca7]

Well, its a matter of how you read this sentence. Most people read this as the action that is going to be being performed when you press that button below. No text here is saying that you need to reset the device.

@c0ffeeca7 do you have an idea how we could rephrase this text a little bit so its more clear ?

maybe To continue, select Share device. This enables Commissioning mode on your device and allows it to pair it with the Matter controller. In the message, can you use bold? if not, then maybe select the "Share device" button.

[NoRi2909]

To continue, select Share device. This enables Commissioning mode on your device and allows it to pair it with the Matter controller.

@c0ffeeca7 That sounds good to me, matching what I suggested above.

Alert texts should always refer to the button options the user can choose from, so this is much better than the current wording.

Given the very misleading instructions on other platforms like Google Home I suggest adding a note below, similar to the existing information in the Re-interview device and Ping device alerts.

So in combination something like:

To continue, select Share device. Home Assistant will then enable Commissioning mode on your device, allowing it to pair with another Matter controller.

Do not use the physical setup button on the device as this will reset it, effectively disconnecting it from all Matter controllers including Home Assistant.

[NoRi2909]

FYI: I have also submitted feedback to Google that they should simply remove the "Power on your device and make sure it's in setup mode." from the screen I posted above.

Most Matter devices already switch to "setup mode" (as Google calls it) when they are powered on for the first time. Then they also trigger a notification on the user's Android device (via Bluetooth) for adding them to their Matter setup - which then launches the setup process.

So when the user arrives at the depicted screen the prerequisite it talks about has already happened. And when a primary Matter controller like HA triggers it even more so.

Therefore I suggested to Google to completely remove this note and only bring it up in case the following workflow actually fails.

[3oris]

Hmm, not sure if this is comparing the right hings:

a) The HA notification we are looking at is about exporting a device that's already member of the HA matter controller's fabric to another (different fabric). And yes, the current message is confusing, and I think you have identified a better wording already.

b) The Google Home notification refers to that you are about to import a device into their matter fabric. So everything stated there is correct: If it is a new device it has to be turned on (and hence hopefully be in pairing mode already). If it is an existing device (as in part of another fabric already), you have had to press the "share device" button (in case of HA) to get the existing device into pairing mode. In both cases you had to "make sure that it's in pairing mode." Maybe "pairing" is more correct here than "setup", but also, we have to consider the target audience.

That said: If the Google Home notification actually appears after scanning the QR code, we could complain that by creating the QR code on Home Assistant you already had to turn on the device, and bring it into setup/pairing mode by pressing "share device". So the message at this point comes too late, and following the instructions now would probably disrupt the already started process.

[3oris]

And also regarding the current share notification in HA:

I as well read it as:

"Dear user, now bring your device into pairing/commissioning mode, and then press share"

Loving the latest suggestions though.

[3oris]

FYI: I have also submitted feedback to Google that they should simply remove the "Power on your device and make sure it's in setup mode." from the screen I posted above.

I believe the notification was originally designed to be placed before scanning the QR Code, because then it would have matched both new and existing device workflows (except for the unlucky word "setup"). And then they found people having a hard time with new devices like light bulbs that - after being turned on and brought to pairing mode - have to get screwed off their socket again in order to scan the QR code.......

So someone said "just move it after scanning the QR code".

Wild guessing though.

[NoRi2909]

@3oris As we're both German that's probably the explanation why we both understand the sentence this way:

I as well read it as:

"Dear user, now bring your device into pairing/commissioning mode, and then press share"

And the translator also came to the same result as the German UI is currently using this (wrong) meaning as well.

Regarding the Google Home dialog I was not comparing it to the Home Assistant alert, it was about the workflow the user gets to see when exporting from HA and importing into Google Home. Then both alerts do emphasize the same procedure that leads to the wrong outcome: Resetting the device and disconnecting it from HA.

Therefore I also submitted feedback to Google that they should change this alert to adapt to whether this pairing is for the first or a secondary controller. HA's own dialog already does this.

Regarding the rewording on HA, happy to hear that you agree with the suggestions.