Repository navigation
Make the Companion App capability-aware to guide users through Matter device setup #245
Description
Problem statement
Adding a Matter device through the Companion App works — but it asks users to know things they should not have to know before they even reach the QR scanner.
The current flow (Settings → Devices & services / Connectivity → Matter → Add device → "No, it's new" → OS handover) contains no signal about whether the user's setup is actually ready for the device they are about to add:
- Whether Home Assistant's Thread border router is reachable and IPv6 is functional
- Whether this phone holds Home Assistant's Thread credentials — or whether the OS will silently hand a new Thread device the credentials of another ecosystem's network (Apple, Google), stranding it where Home Assistant can never see it
- Whether the device the user is about to scan is likely certified, or will be rejected by strict attestation (Matter Server 9.0) with no path forward other than a global "allow test devices" flag and a server restart
When one of these preconditions is not met, the user only finds out after the OS-owned commissioning step fails — with a generic, platform-specific error ("Couldn't reach device" / "Unable to Add Accessory") that hides the real cause. Community support then starts with "which phone?", because Android and iOS fail at different moments with different wording.
Home Assistant knows the answers to most of these questions before handing over to the OS. It just doesn't ask them.
This effort is a continuation of OpenHomeFoundation/goals#19 (approachable Matter setup) and #31 (first-device wizard) and complements #177 and #237.
Community signals
- Discussions before/during/after Lisbon 2026 summit
- https://docs.google.com/presentation/d/1RnSnGULr1dbziATmjJFZPMVUO_YimXxgykrPkQCdKFw/edit?slide=id.g35c9c97dd26_0_0#slide=id.g35c9c97dd26_0_0
- https://ux-design-concepts.openhomefoundation.org/ha-matter-commissioning-flows-revisited/
Scope & Boundaries
In scope
- A capability preflight in the Add Matter device flow on both Companion Apps, run before the OS handover, covering:
- Home Assistant Thread network health (OTBR present, IPv6 functional) — surfaced as a readiness signal, not a blocker
- Thread credential check against the phone's OS store
- Android: name the preferred network via Play services (
isPreferredCredentials/getPreferredCredentials, behind user consent) and warn deterministically on mismatch - iOS: detect whether Home Assistant's credentials are present/preferred by Border Agent ID; warn on "another network is preferred" even though it cannot be named
- Android: name the preferred network via Play services (
- Offer "Sync credentials & continue" inline instead of requiring the user to find the sync action under Troubleshooting first
- Consistent, platform-neutral failure explanations after the OS step, building on Show snackbar with troubleshooting link for Matter/Thread non-OK activity results home-assistant/android#6614 and extending the same information to iOS
- Clear wording for the uncertified-device dead end, pointing to the actual resolution rather than a bare error
- Reuse of the shipped first-device wizard (First device setup wizard focusing on Matter devices #31) as the flow's end state
Not in scope
- Replacing the OS-owned commissioning UI (Play services / Apple accessory sheet)
- Browser / frontend commissioning path (see separate opportunity)
- Passive discovery of commissionable devices (see separate opportunity)
- Other protocols than Matter / Thread (for now)
Foreseen solution
- Discussion basis to further refine upon is https://ux-design-concepts.openhomefoundation.org/ha-matter-commissioning-flows-revisited/
Risks & open questions
- Platform asymmetry
Appetite
Medium - 1-2 cycles
Execution issues
No response
Decision log
| Date | Decision | Outcome |
|---|---|---|
Activity
Hedda commentedon Sep 29, 2026
For reference, there are a few other things also need to take into consideration when it comes to Matter commisioning today and the future:
mkerstner commentedon Sep 29, 2026
Agree that we can expand this pre-flight check further, we just also need to start somewhere to further iterate upon.
Based on recent discussions the items outlined in the refined flow could be a viable starting point - but not an exhaustive one of course.
Ideally, users would never need to care about these detail screens as the checks are running in the background and only surface if needed or if someone is interested to get more insights. That's how we envision the pre-flight check and the overarching flow at the moment - which based on feedback sounds like a reasonable approach to start with. Of course, we can further expand on this idea but having a sound baseline to start with already reduces some of the friction our users currently encounter.