Devices and Entity Mapping

The filter picks the candidates; the mapping decides how they appear

The Devices page collects the leaf endpoints of every bridge, so you can work back from what Matter actually built to the Home Assistant entity behind it. Entity Mapping is the explicit override for one entity on one bridge: it can change the name, the Matter device type, the identity details, the disabled state and the linked helpers. It does not change the Home Assistant entity registry, and it does not turn Matter Hub into a controller.

Work in this order: control the candidate set with the Filter Preview first, confirm the endpoint on Devices next, and add a mapping only for the entities that are exceptions. If you override the type and the identity for every entity from the start, you lose the benefit of automatic detection, and you are more likely to hit a type the controller does not support or an identity change after commissioning.

Search, filter, sort, failures and paging

Devices collects only the leaves of the endpoint tree whose endpoint number is not 0; the root node and the aggregator do not become ordinary device cards. A card can show reachable, the HA state, clusters, the battery percentage, the automatic or explicit mapping link, and the matching status chips. When you cannot see something in the controller, Devices is the first checkpoint, and it sits closer to the bridge than the controller UI does.

Complete a minimal mapping from the device card

1. Lock on to the right bridge

   Go to Devices in the sidebar, pick the target bridge with the Bridge filter first, then search by name or type. Expand the card and confirm the entity it maps to; in documentation, write that entity as the placeholder <ENTITY_ID>.

2. Open Edit Mapping

   Press the mapping edit button in the top right of the card. The page first loads that bridge's mappings and looks for existing settings with the same entityId. If the load fails, the dialog opens as though there were no existing mapping, and that is not the moment to start overriding.

3. Keep Auto Detect as the baseline

   Leave Matter Device Type on Auto Detect unless there is a clear problem with it. If you do override it, read the suggested types and the controller support chips on each row first, then look at the support warning that follows your choice.

4. Fill in only the fields you need

   For a naming problem, fill in Custom Name only. Fill in Custom Product Name only when one controller displays the productName. Change the type only when the endpoint is wrong. Turn on Disabled only to pause exposure. Empty fields are sent as undefined.

5. Save and read the feedback

   Press Save. On success it shows a saved message; on failure it keeps the error. Go back to the card and check the mapping and the clusters. Do not run Force Sync, change the filter and commission again all at once.

6. Verify in the controller

   Confirm the support status of that type first, then watch the target controller. If a change in the type or the cluster topology means it has to be discovered or commissioned again, deal only with this one exception device, and keep a way back first.

You can also add, edit or delete a mapping in the Entity Mapping section on a single bridge's detail page. When you add one you can search for or type an entity ID. Deleting a mapping returns to automatic detection and the defaults; it is not the same as excluding the entity in the filter.

Name, full identity override, Disable and Type Override

Two kinds of rename: Custom Name is an override on the Matter side and leaves the HA entity_id alone; actually changing the entity_id in HA can pull in the endpoint identity. The bridge feature flag stableIdentity anchors identity to the HA registry unique_id, so a rename does not mint a new device. Without stable identity turned on, do not bundle an HA rename, a custom serial and a suffix change into one batch in an environment that is already commissioned.

How to read the A / G / X / Q support chips

Each row of the type picker can show four round chips: A is Apple Home, G is Google Home, X is Alexa and Q is Aqara Home. Green means works and orange means partly works. Both no and unknown use gray at a lower opacity, so you have to rest the cursor on the chip and read the tooltip to tell "not supported" from "unverified".

Once you pick a type, the dialog shows an information warning if any controller is explicitly no. Some types carry a note of their own as well, such as the limits on how a standalone fan is presented in Apple Home. This is a point-in-time snapshot taken from the v2.0.55 source, not a permanent guarantee from the controller vendor. SmartThings is not in this set of UI chips, and a missing chip is no basis for inferring either support or the lack of it.

Export, preview and selective import

A Mapping Profile is JSON at version: 1, holding name, createdAt, domains, entryCount and entries. What it carries is a set of mapping rules, not bridge identity, the fabric, pairing data or a full backup. The export dialog preselects the existing mappings; you can select or clear all of them, tick them one by one, and give the profile a name.

1. Choose what to export

   In Entity Mapping on the bridge detail page, press Export. Tick only the entity mappings you intend to share or move, and use a profile name that carries nothing confidential about the environment.

2. Save the JSON

   Check the downloaded file name and its contents. Before you share it, review entityIdPattern, custom names, service names, area data and the identity fields by hand, and remove anything that identifies a live environment; a profile is not an automatic de-identification tool.

3. Pick the import file

   Press Import and choose the .json. The frontend requires version and entries first, then the backend preview validates the entries against the entity IDs that are available.

4. Review the preview

   Check the profile name, the total count, matched, unmatched, matchType (exact or domain) and existing mapping. Every match is ticked by default, so clear the ones you do not want to overwrite.

5. Apply selectively

   After you apply, read applied, skipped and errors. In v2.0.55, apply matches the profile entry's entityIdPattern against the selected IDs, so an exact entity ID match is the most reliable way to work across environments; do not read a domain fallback in the preview as certain to succeed.

6. Reload and verify one by one

   The mappings reload after the import. Look at a few devices first, then widen it. If the result is wrong, delete that mapping to return to automatic detection instead of resetting the whole bridge.

The v2.0.55 profile is not a full backup of EntityMappingConfig. It holds type, customName, disabled, and most of the battery, sensor, energy, vacuum, lock, cover, fan and climate helpers; but the profile type and the export conversion have no customProductName, customVendorName, customSerialNumber, customVendorId, composedEntities, chargingStateEntity, currentRoomEntity, cleanedAreaEntity, coverExposeAsDimmableLight, select switch helpers, updateThrottleMs or disableCustomAreaRoomModes fields. When you need full disaster recovery, use the real Backup rather than treating a profile as a complete snapshot of the mappings.

Upload, remove and automatic resolution

The image sources for a Devices card have this precedence: a custom file (custom) → the Zigbee2MQTT model URL (z2m) → none. The backend sanitizes the entity_id first, then looks for a file of the same name in the device-images directory in persistent storage. When there is no custom file and the HA device registry has a model, it builds the official Zigbee2MQTT image URL. The image affects the Matter Hub UI card only; no image is synced to the controller.

To upload, press the camera button on the card; on success the page bumps the cache version and runs the batch resolve again. A delete resolves again as well. Use only images you have the right to use, and do not upload files that contain pictures of a home, serial numbers on labels or other personal data. When you back up or migrate, count the persistent device-images among the assets you plan for.

Troubleshooting Devices and mappings

1. Search cannot find an entity_id you know exists

   Search looks only at the display name, the bridge name and the type. Pick the bridge and the type first, then expand the cards to find the HA entity; or go to that bridge's Entity Mapping section and search with the Entity Autocomplete.

2. Failed focus still shows healthy devices

   That is what v2.0.55 actually does: showFailed=true shows the failure summary but does not filter the cards below it. Take the bridge and the entity_id from the summary and go back to the filter, the mapping and the failed reason to work it out.

3. The controller shows nothing after a type override

   Go back to the picker and read the support chips, the tooltip and the warning to establish the maturity of the type. Restore Auto Detect first; do not start by changing the identity or by commissioning the whole bridge again.

4. The import preview says matched but applying skips it

   Check whether the profile's entityIdPattern is exactly the same as the target. In v2.0.55, apply matches the selected IDs against the entry pattern, and a domain fallback preview is unreliable when the entity IDs differ; use an exact match, or create the mapping by hand.

5. There is still an image after you delete one

   Deleting a custom image triggers a fresh resolve. If the HA device has a model, the source falls back to z2m; that is not a failed delete. When the remote URL has no image, the built-in icon appears only after the load error.

6. A new device appears in the controller after an HA rename

   Confirm whether the bridge uses stableIdentity, and check whether the serial, the unique suffix or the custom serial changed at the same time. Undo the identity changes you did not need. In an environment that is already commissioned, start from the backup and an assessment of the controller impact rather than renaming over and over.

Entity Mapping FAQ

Stable 2.0.55 pinned-version sources

• DevicesPage.tsx: search, filter, sort, paging and failed focus
• EntityMappingDialog.tsx: the mapping fields and what they do
• entity-mapping.ts: identity, Matter types and controller support data
• mapping-profile.ts: the profile v1 format and its subset of fields
• mapping-profile-api.ts: export, preview and selective import
• device-image-api.ts: formats, size, storage and z2m resolution