Commissioning to Apple Home
Start with the checks you make before commissioning — the Apple home hub and the local network — then finish onboarding in the Home app, tidy up rooms and names, and diagnose No Response layer by layer without damaging the fabrics you already have.
Define Apple Home's role in the architecture first
Home Assistant Matter Hub exposes Home Assistant entities through a Matter bridge; Apple Home is the Matter controller ecosystem that receives that bridge. Once commissioning is done, you see the endpoints the controller understands in the Home app, and you drive them with Siri, scenes or automations. Home Assistant is still the state source for the original entities, and Matter Hub still handles the mapping and the protocol translation.
This process does not move your Home Assistant areas, names, Dashboard or automations wholesale into an Apple home. Apple's homes, rooms, display names, members and automations are a separate set of management data. Onboard a small number of devices and let them settle first, then tidy up in the Home app, instead of bridging every entity on day one.
The Apple Home pre-commissioning checklist
| Item | What you must confirm | What you see if it is not true |
|---|---|---|
| Apple device and account | The iPhone or iPad is signed in to the Apple account you plan to use, and the Home app opens the target home normally. | You join the wrong home, or you have no permission to add an accessory. |
| Home hub | The target home has a home hub that Apple officially supports, with its software up to date and online. | Remote control, automations or the long-term connection are unstable. |
| Local network | The phone, the home hub and Matter Hub can talk over IPv6 on the local network and discover each other over mDNS. | The accessory is not found, the join times out at the end, or you get intermittent No Response. |
| Matter Hub | The Stable 2.0.55 bridge is running, the persistent data is backed up, and the basic endpoint mappings are correct. | No devices after you scan the code, or the identity changes after a restart. |
| Change freeze | During commissioning, do not change the port, the network interface, filters, the bridge name or mappings in bulk. | You cannot tell whether the problem came from onboarding or from a structural change. |
Apple extends the set of Matter types with each system release; "Apple Home supports Matter" is not the same as "every device type Matter Hub maps gets a full set of controls". Pick one basic light or switch to establish a baseline, then test types such as covers, fans, sensors and vacuums.
Three kinds of support fact you must not mix
| Aspect | Conclusion for this chapter | Limits |
|---|---|---|
| Release channel | Matter Hub Stable v2.0.55, with the sources pinned to an exact commit. | Do not cite Alpha, Testing or later UI behavior. |
| Product maturity | Use the standard bridge and the commissioning flow as Stable features. | Multiple entities in Server Mode, the Camera and Security plugins and some Matter 1.4 types are experimental even though they appear in Stable. |
| Apple controller support | Apple documents that the Home app can add Matter accessories, and which types are supported depends on the Apple platform version. | The upstream manifest still marks Apple support as unknown for most individual types; you cannot claim that every mapping is certified by Apple. |
If an endpoint is missing a button or a state in Apple Home, that does not mean Matter Hub as a whole is broken. Check its Matter device type and clusters first, then compare them against what Apple currently supports; if the type is experimental, treat the result explicitly as an experiment, not as a guarantee.
Finish onboarding in the Home app
Prepare a minimal bridge
Open the target bridge on the Matter Hub Bridges page and confirm it is running; use Devices to cross-check that it holds only the entities you expect. Keep one low-risk light or switch for verification, and do not add special types at this point.
Open the commissioning window
The bridge's pairing area shows the QR code for this session. Do not download it, screenshot it, forward it or put the screen into a support ticket; only when the camera cannot scan it should you get ready to use the Home app's manual entry option.
Add the accessory from the Home app
On the iPhone, open Home, choose Add Accessory, and scan the QR code on the local Matter Hub screen. When you get an Uncertified Accessory notice or a security prompt, confirm first that you are connecting to your own bridge and the right home; do not skip past it blindly.
Choose the home and wait for onboarding to finish
Follow the Home app screens to pick the target home and room, and keep the app in the foreground with a steady network connection on the phone; do not restart Matter Hub, the home hub or the router at the same time.
Do the basic naming first
Give the bridge and the representative accessories names that are short, easy to say out loud and not duplicated. Avoid a room name that is identical to an accessory name, and avoid renaming every endpoint one by one at the start.
Verify both directions
Toggle the test light from the Home app and confirm the state changes in Home Assistant; then toggle it from Home Assistant and confirm the card updates in the Home app. Wait for the state report; do not paper over the delay by tapping repeatedly.
Verify again after a restart
Restart Matter Hub normally during a maintenance window and confirm the same accessory comes back instead of a second copy appearing. If duplicates keep appearing, stop making changes and check the bridge identity and the persistent data.
The order for tidying names, rooms and Siri phrases
After onboarding, tidy up room by room in the Home app. An Apple Home display name is controller-side data; it does not have to match the Home Assistant entity_id, and you should not edit entity_id to tidy up the voice experience. Settle the Home Assistant entities and the Matter Hub mappings first, then change the display names on the Apple side, which keeps structural changes to the bridge down.
| Layer | Recommendation | Rule behind the example |
|---|---|---|
| Bridge name | Identify it by area or purpose; keep versions, ports and secrets out of the name. | A role name such as "Ground floor core bridge". |
| Room | Assign the real space in the Home app; tidy one room at a time and test it. | Living room, kitchen, meeting room. |
| Accessory name | Short, unique and easy to say; leave the room information to the room field. | "Floor lamp" beats a long, repetitive full-path name. |
| Service / sub-accessory | When a composed device produces several cards, work out what each one does before you name it. | Do not delete the original HA entity just because there are several cards. |
After a rename, test once in the Home app and once with Siri. If Siri gets it wrong, deal with homophones, duplicates or room conflicts first; do not reset the bridge. In a multi-fabric setup, names on the Apple side do not sync to Google or Alexa.
How to read Apple-specific Matter support
The Matter categories listed on Apple's official support page give you the ceiling for the ecosystem, but what actually appears also depends on the Apple platform version, the home hub version, the device type and clusters the bridge declares, and how well that endpoint is mapped. This chapter does not turn "the Matter specification defines it" into "the Home app is bound to have a complete UI".
- Lights, plugs and switches: a good first baseline; you still have to verify on/off, brightness, color temperature and color separately.
- Covers, locks and thermostats: these carry position, direction, safety or mode semantics; verify a small number first, and do not stop at whether the card appears.
- Sensors: you may be able to see them in the accessory details and still not get a card on the home screen, a notification, or a way to trigger an automation.
- Vacuums and newer types: support and UI are sensitive to the Apple system version; if the Matter Hub side is a partial Matter 1.4 mapping, label it as experimental inside Stable as well.
- Camera and Security plugins: these are experimental plugins inside the Stable channel, so do not claim full support just because Apple Home has a similar accessory category.
Attack No Response by scope and timing
| Scope | Most likely layer | First action |
|---|---|---|
| The whole bridge is No Response | The Matter Hub process, the host network, IPv6 / mDNS, the home hub path or the bridge identity. | Look at Bridges, Health and the redacted logs; confirm the process and the persistence mount. |
| Only one endpoint | An HA entity that is unavailable, the mapping, the type or the controller UI. | Cross-check the original state in Home Assistant and in Matter Hub Devices. |
| It only fails when you are away | The Apple home hub, or the state of the home on the account. | Check the home hub in the Home app; do not change the Matter fabric. |
| Control works, the card is stuck on an old value | The subscription, or the state mapping. | Compare the state in both directions, wait for the subscription to recover, and avoid repeated commissioning. |
| It appears briefly after a restart | Session recovery, the startup order, or HA not being ready yet. | Watch how long it takes to settle and read the startup log; do not restart repeatedly during recovery. |
When the Apple devices and Matter Hub are on separate VLANs, being able to reach the internet does not mean Matter is reachable on the local network. Matter needs an IPv6 path and service discovery; do not substitute a public network address, port forwarding, or pasting the QR code onto a remote machine. Once the network is fixed, let the session recover on its own before you consider removing the accessory.
Common Apple Home pitfalls
The Home app cannot find the accessory
Confirm the commissioning window is still open, the bridge is running, and the phone and Matter Hub can discover each other locally over IPv6 / mDNS. Turn off any VPN that changes the path and retry, but do not reset.
The join times out at the last step
Keep the Home app in the foreground, confirm the home hub is online and the target home is the right one, and stop restarting or changing the bridge at the same time. Go back to Matter Hub to see whether an Apple fabric has already been added, so you do not create a duplicate.
You see the bridge but not the accessories you expect
Look at Devices and the filter to confirm the entities mapped successfully, then cross-check against the types Apple officially supports. Add a basic light as a reference point; you do not need to delete the fabric to test a type.
The card shows No Response
Classify it as the whole bridge, a single endpoint, remote-only or state-reporting-only; fix the Home Assistant unavailable state, the network, the session or the subscription first, and keep the fabrics that still work.
The name or the room reverts
Work out whether it is the Apple display name, the Matter Hub Node Label or the HA name; change one layer only and verify it. Do not rename the HA entity_id and the bridge at the same time.
Duplicate gray cards appear after a removal
Clean up the old accessory and any automation references in the Home app first; a Matter Hub reset affects the other fabrics, so it is not the first choice for clearing an app's cache.