Filtering picks the candidates. Mapping decides how they show up

The Devices page collects the leaf endpoints of every bridge you have — the actual Matter endpoints Matter Hub built, one card per endpoint, so you can work back from what Matter actually produced to the Home Assistant entity behind it. Entity Mapping is the explicit override for one entity on one bridge, and only that entity: it can change the name, the Matter device type, the identity details, the disabled state, and which helper entities feed it. It does not change the Home Assistant entity registry, and it does not turn Matter Hub into a controller of its own.

Work in this order. The Filter Preview from the previous part controls the candidate set. The Devices page confirms the endpoint that actually got built from that candidate. A mapping is added only for the entities that are exceptions to what Auto Detect already got right. 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 land on a type the controller does not support, or an identity that shifts after the device is already commissioned.

flowchart LR
  F["Filter Preview:
which entities become
candidate endpoints"] --> D["Devices page:
confirm the endpoint
Matter actually built"]
  D --> M["Entity Mapping:
override only the
exceptions"]

Search, filter, sort, failures and paging — and what each one actually touches

Every control on this page looks like it does one obvious thing. A couple of them do something narrower than the label suggests, and knowing the actual scope saves you a search that comes back empty for no good reason.

Devices collects only the leaves of the endpoint tree whose endpoint number is not 0; the root node and the aggregator never become ordinary device cards. A card can show reachable, the Home Assistant state, the clusters, the battery percentage, whether the mapping is automatic or explicit, and the matching controller-status chips. When something is missing from the controller, Devices is the first place to check, because it sits one layer closer to the bridge than any controller's own UI does.

A minimal edit, and the fields that make it possible

1. Step 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 your own notes, write that entity as the placeholder <ENTITY_ID> rather than the real value.

2. Step 2

   Open Edit Mapping

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

3. Step 3

   Keep Auto Detect as the baseline

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

4. Step 4

   Fill in only the fields you need

   For a naming problem, fill in Custom Name only. Fill in Custom Product Name only when a controller displays the productName. Change the type only when the endpoint itself is wrong. Turn on Disabled only to pause exposure. An empty field is sent as undefined, not as a blank string.

5. Step 5

   Save and read the feedback

   Press Save. Success shows a saved message; failure keeps the error on screen. Go back to the card and check the mapping and the clusters. Do not run Force Sync, change the filter, and commission again all in the same sitting — one change, one check.

6. Step 6

   Verify in the controller

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

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 search for or type an entity ID. Deleting a mapping returns that entity to automatic detection and its defaults — which is a different thing from excluding it with a filter rule, and does not remove it from the candidate set.

Two kinds of rename exist, and they are not interchangeable. Custom Name is a Matter-side override and leaves the Home Assistant entity_id completely alone. Actually renaming the entity inside Home Assistant is a separate operation, and it can pull the endpoint's identity along with it. The bridge feature flag stableIdentity anchors identity to the HA registry unique_id instead of to the name, so a rename does not mint a new device in the controller. Without stable identity turned on, do not bundle a Home Assistant rename, a custom serial change, and a suffix change into one batch on an environment that is already commissioned — any one of the three could look, from the controller's side, like a brand-new device.

flowchart TD
  A["Endpoint currently on
Auto Detect"] --> B{"Is the detected type
actually wrong for
this endpoint?"}
  B -->|"no"| C["Leave it on Auto Detect"]
  B -->|"yes"| D["Open the type picker and
read the A / G / X / Q
chips on each row"]
  D --> E{"Does any controller
chip read explicit no?"}
  E -->|"none does"| F["Save the override,
then verify in that
controller"]
  E -->|"at least one does"| G["Read the warning and
the type note before
you save"]

Four round chips, and the difference between “no” and “nobody's checked”

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 it works, orange means it partly works. Both no and unknown render as gray at a lower opacity, which is the trap — 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 chip is explicitly no. Some types carry a note of their own on top of that, such as the limits on how a standalone fan is presented in Apple Home. All of this is a point-in-time snapshot taken from the Stable 2.0.55 source, not a permanent guarantee from any controller vendor. SmartThings is not part of this set of four UI chips at all — a missing chip is no basis for inferring either support or the lack of it.

One physical device, five scattered entities, and three different ways to bring them back together

Many integrations split one physical device into a primary control entity plus a battery, a temperature-and-humidity pair, a power sensor, a cumulative energy sensor, a mode select, and an action button. If every one of those becomes its own Matter endpoint, a controller can end up showing a pile of fragments, or it simply cannot put a secondary value into the right cluster. Linked fields in Entity Mapping let you say which entity is which kind of data source for the primary endpoint. composedEntities does something different: it builds extra entities as sub-endpoints under the same BridgedNodeEndpoint.

flowchart TD
  H["One Home Assistant device
with several related entities"] --> M1["Automatic mapping:
a bridge feature flag such
as autoComposedDevices"]
  H --> M2["An explicit linked field:
batteryEntity, powerEntity
and similar, set by hand"]
  H --> M3["composedEntities:
an extra entityId becomes
its own sub-endpoint"]
  M1 --> R1["Battery, humidity, pressure,
power and energy merged
into the primary endpoint"]
  M2 --> R2["One named field feeds one
specific cluster on the
primary endpoint"]
  M3 --> R3["A new sub-endpoint under
the same BridgedNodeEndpoint"]

autoComposedDevices is the master toggle for automatic composition: turning it on is what allows battery, humidity, pressure, power and energy to be merged automatically at all. Within that, autoBatteryMapping defaults to false; autoHumidityMapping and autoPressureMapping default to true. Filling in batteryEntity and the other linked fields by hand is explicit mapping, and it is worth being precise about that distinction in your own notes — do not describe a hand-filled field as something a flag “found automatically.”

The Devices card lists the battery, humidity, pressure, power, energy, voltage, current, battery-power / battery-energy, charging-switch and current-limit links a mapping carries, and marks the clusters those links produce. A card can be showing runtime automatic mapping and a saved explicit mapping at the same time, so cross-check it against both the bridge flags and the entity mapping before you assume you know which one is responsible for what you see.

Battery, temperature, humidity, pressure, and faults

Battery Storage has its own batteryPowerEntity and batteryEnergyEntity. Do not confuse them with the battery percentage of an ordinary device: they describe the charge and discharge power and the lifetime throughput of home energy storage, while batteryEntity describes where the device itself draws its own charge from.

Power, energy, voltage, current, utility meter, and EVSE

An ordinary switch, light or plug-in unit can take power and energy. on_off_switch is presented as a plain On/Off Light, and the UI offers it no electrical fields at all. electrical_meter, solar_power, electrical_sensor and electrical_utility_meter show the full power/energy/voltage/current group. EVSE shows the charging switch, the current limit, and optional power/energy — it does not duplicate the ordinary electrical group.

Lock, vacuum, fan, cover, select, climate — and the two timers that are not the same thing

Lock

• disableLockPin: one lock stops requiring credential verification. If the system already has credentials configured, the default is still to require them. Never put a real lock code in a document — use a placeholder.
• lockUsercodeService: an optional HA service that syncs the credential a controller sets or clears back to the physical lock; without it, the credential is only kept inside Matter Hub. This is opt-in behavior that writes to an external device, so confirm what the integration's service actually does before you enable it.
• lockUsercodeSlot: the code slot on the physical lock, default 1; the UI only accepts integers of 1 or more.
• lockPinMinLength / lockPinMaxLength: the lengths advertised to a controller, 1–20, default 4 and 8. They are fixed attributes, and a controller may cache them until the next commissioning. Record the lengths only — never the real credential.

Vacuums and areas

• cleaningModeEntity: the cleaning-mode select. When it is not set, the backend can derive a conventional name from the vacuum entity ID.
• suctionLevelEntity and mopIntensityEntity: the suction and mop-water selects, which add intensity variants to the cleaning modes.
• roomEntities: an array of room / scene buttons; after Matter picks a room, the matching button is pressed. The UI can read the related buttons and also lets you type an entity ID directly.
• currentRoomEntity: the current-room sensor. cleanedAreaEntity: the cumulative cleaned-area sensor, which together with each area's sizeSqm advances the progress.
• vacuumAscendingRoomOrder: dispatches in ascending area-ID order instead of the controller's own selection order; it also changes which area the current room and the progress are attributed to.
• vacuumRoomSwitches: creates a momentary sibling switch per area, for routines on platforms that cannot send an array command.
• disableCustomAreaRoomModes: skips building custom areas as per-room RvcRunMode entries, so Apple Home falls back to its own multi-room area picker. Leave this off wherever Google Home or Alexa depends on those modes.
• valetudoIdentifier: keeps the exact case of the Valetudo MQTT identifier; unset, it is derived from the lowercase entity ID.
• customFanSpeedTags: a map from HA option strings to Matter ModeTag numbers, overriding the default speed tags.
• cleanAreaRooms: filled in automatically at runtime when the vacuum supports HA 2026.3 CLEAN_AREA, as a mapping from HA area to Matter ServiceArea ID. It is not a field you fill in yourself in the dialog.

Every area in customServiceAreas carries a required name and service, plus an optional target, a plain-object data, batchDispatch and sizeSqm. batchDispatch takes the service and target of the first matching area as a template, and can merge arrays, join primitives with commas, and inject the selection metadata; the default is to dispatch area by area. data has to be a JSON object — the UI rejects an array or a primitive as invalid. These services make a real device act, so verify them in Home Assistant at the smallest scope first, before trusting them to a controller-driven room pick.

Fan, cover, select, climate, and momentary

• fanWindPresets.natural / .sleep: arrays of localized HA preset names mapped to the Matter wind modes; the UI takes them comma-separated.
• fanRestoreSpeedOnPowerOn: when a fan is turned on from off, ignores the 100% / High a controller injects and restores the last speed. You can still specify a lower speed while the fan is off.
• coverSwapOpenClose: swaps open and close for one cover, overriding the bridge flag. coverExposeAsDimmableLight: an Alexa workaround that uses level as the position and on/off as open and close; there is no stop, and it should not go into the lights group of an Alexa room.
• selectExposeAsSwitch together with selectSwitchOnOption / selectSwitchOffOption: turns a select or input_select into a switch. The two option strings have to match exactly, and after the change that device has to be commissioned again.
• disableClimateOnOff: skips the climate OnOff cluster, so a voice command that turns a room off does not call climate.turn_off.
• disableClimateFanControl: skips FanControl and uses ThermostatDevice instead, for controllers that do not recognize RoomAirConditioner. Home Assistant can still control the fan modes underneath.
• climateKeepModeOnIdle: when HA is off and hvac_action is idle, keeps reporting the last mode so an internal cleaning cycle can still be cancelled — HA and Matter deliberately disagree for a while here.
• climateExposeFan: builds a companion Fan tile alongside the same HA climate entity. The entity has to report FAN_MODE, and it re-registers that air conditioner as a composed device, which means commissioning that one air conditioner again.
• climateAutoMode: only heat or cool, pinning the Matter direction of a single-setpoint auto climate.
• disableMomentaryFlip: script, scene, automation, input_button and button entities stop sending the optimistic on→off report, while the underlying HA action still runs. It is a workaround for Echo units that get stuck on that report pair.

Throttle and debounce are not interchangeable

flowchart LR
  C["Controller sends a slider
or speed command"] -->|"debounce waits for
the last write"| H["Home Assistant
service call"]
  S["Home Assistant sensor
state changes"] -->|"throttle limits how
often this fires"| R["Matter attribute report
back to the controller"]

Do not use updateThrottleMs to stop a cover from moving several times, and do not use fan debounce to thin out a power sensor that reports too often — each field is built for the direction of traffic in its own row above, not the other one. Start with one entity and a small value, then adjust from what you see in the logs and how the control actually feels. Profile v1 carries the cover and fan debounce fields but not updateThrottleMs; if you move settings with a profile, cross-check the throttle by hand after the import, and do not assume a profile carried a bridge's global debounce setting across with it.

1. Step 1

   Confirm the primary entity and the same-device sources

   In Home Assistant, read-only, confirm the primary entity, the device relationship, and each sensor's device_class, unit and valid state. Record them in a local list; do not paste a live entity ID or a supply identifier into a document.

2. Step 2

   Check the bridge's automatic flags

   Look at autoComposedDevices and the auto battery, humidity and pressure flags. If the automatic result is already right, do not link it again by hand; if only one device is the exception, use Entity Mapping for that one device alone.

3. Step 3

   Open the primary entity's mapping

   On the Devices card, press Edit Mapping and keep the correct primary Matter type. Use the field autocomplete to pick the battery, humidity, power and other sources; the dedicated groups only appear for a matching type or domain.

4. Step 4

   Set up one group of helpers

   Fill in only the fields that serve one purpose at a time — power plus energy, say, or humidity plus pressure. Add a composed entity only when you need an extra sub-endpoint, and confirm the bridge already has autoComposedDevices on before you try.

5. Step 5

   Save and check the endpoint

   Go back to the Devices card, expand the clusters, and confirm the linked entity labels and their values. If the endpoint fails, delete the mapping you just added to get back to the baseline — do not reset the whole bridge.

6. Step 6

   Run the controller-specific check

   Check the target controller against the support chips and the maturity notes. For power, utility and EVSE fields, confirm they appear before you test the readings; for anything that issues commands, such as a lock or a vacuum service area, run only the smallest authorized test.

Move mappings between bridges, and give a card a picture — neither one touches the controller

Mapping profiles

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. Step 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. Step 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. Step 3

   Pick the import file

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

4. Step 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. Step 5

   Apply selectively

   After you apply, read applied, skipped and errors. In Stable 2.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. Step 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 Stable 2.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, the select-switch helpers, updateThrottleMs, or disableCustomAreaRoomModes. When you need full disaster recovery, use the real Backup rather than treating a profile as a complete snapshot of the mappings.

Device images

The image sources for a Devices card have this precedence: a custom uploaded file → the Zigbee2MQTT model URL → 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 instead. The image affects the Matter Hub UI card only; no image is synced to any Matter controller.

flowchart TD
  A["Devices card needs
an image"] --> B{"Is there a custom
uploaded file for
this entity_id?"}
  B -->|"yes"| C["Show the custom file"]
  B -->|"no"| D{"Does the HA device
registry have a model?"}
  D -->|"yes"| E["Build the Zigbee2MQTT
image URL and try it"]
  D -->|"no"| F["Show the built-in
device-type icon"]
  E --> G{"Does the remote
image load?"}
  G -->|"yes"| I["Show the z2m image"]
  G -->|"no"| F

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 interior, serial numbers on labels, or other personal data. When you back up or migrate, count the persistent device-images directory among the assets you plan for — a profile export never carries it.

The symptom you will actually hit, mapped to the page that explains it

The ones that come up again and again

Where to go from here