Device mapping 1: control devices
See how Stable 2.0.55 turns Home Assistant lights, plugs, locks, covers, climate devices, fans and humidity devices into Matter devices, and judge the capabilities and the controller support before you reach for an override or a workaround.
A mapping is more than changing an icon
Home Assistant Matter Hub is not a Matter controller. It reads the domain, device_class, supported_features and attributes of a Home Assistant entity, builds a Matter endpoint, and then leaves it to an external controller — Apple Home, Google Home, Alexa, Aqara or SmartThings — to decide whether to show a control interface. Map the same entity to a different Matter device type and the controller may give you completely different tiles, sliders and voice capabilities.
Take a wall relay. on_off_plugin_unit means a switchable load. The misleadingly named on_off_switch is implemented in v2.0.55 as a Matter On/Off Light (0x0100), so a controller renders it as a light, not as a wall controller. mounted_on_off_control is the experimental Matter 1.4 wall-control type. on_off_light also means a light. All three can carry On/Off, and none of them guarantees that a controller presents them the same way. The right approach is to keep the automatic mapping first, confirm what Home Assistant can do, and only then use a Matter override for a specific controller gap.
mounted_on_off_control is an experimental type inside Stable; and controller support differs type by type, so you cannot infer from "it is in Stable" that "every home platform will show it".By the end of this chapter you should be able to answer three things: which default path a source domain takes, which Matter features the entity capabilities add, and whether a controller that shows nothing calls for a different type, a workaround, or leaving things as they are until the platform catches up.
Control domains and the override matrix
The full HomeAssistantDomain list in Stable 2.0.55 has 27 entries; this chapter covers seven of them, the control domains. The table below lists the default type candidates for those seven alongside every Matter override in this chapter. A candidate is not a guaranteed result: the actual endpoint is still chosen from the capability bits and the attributes.
| Home Assistant domain | Default or optional Matter type | What decides it |
|---|---|---|
light | on_off_light, dimmable_light, color_temperature_light, extended_color_light | Brightness, color temperature and color capability come from supported_color_modes. |
switch | on_off_plugin_unit; can be overridden to on_off_switch, dimmable_plugin_unit or mounted_on_off_control | An ordinary switch defaults to something that behaves like a switchable plug; you have to cross-check what the load really is. |
lock | door_lock | The OPEN feature decides whether unlatch is included; a battery can add a Power Source. |
cover | window_covering | Lift, position awareness and tilt capability come from the supported features. |
climate | thermostat | At least one of heat, cool, heat_cool, auto, fan_only or dry has to be available. |
fan | fan; can be overridden to air_purifier | Speed, presets, direction, oscillation and the natural-wind mode are decided by capabilities and names. |
humidifier | humidifier_dehumidifier | The Auto name and current_humidity decide the modes and the measurement capability. |
| Matter override in this chapter | What it is for | Maturity / key compatibility |
|---|---|---|
on_off_light | A light that only switches on and off | stable; yes for Apple, Google, Alexa and Aqara. |
dimmable_light | A dimmable light with no color | stable; yes on all four main controllers. |
color_temperature_light | The override name for a color-temperature light | stable; the implementation presents it as an Extended Color Light capability set that initializes safely. |
extended_color_light | A light with brightness, color temperature and color | stable; yes on all four main controllers. |
on_off_plugin_unit | A switchable plug or an ordinary load | stable; yes on all four main controllers. |
dimmable_plugin_unit | A plug-in load with adjustable output | stable; no for Google, yes for the other main platforms listed. |
on_off_switch | Named switch, but the implementation emits a Matter On/Off Light 0x0100 | stable; a controller shows it as a light, not as a wall-control device you can expose. |
mounted_on_off_control | The Matter 1.4 wall-control type | Experimental inside Stable; no for Apple, Google and Alexa, yes for Aqara; not a general-purpose substitute. |
door_lock | A door lock | stable; partial for Google, yes for Apple, Alexa and Aqara. |
window_covering | Curtains, roller blinds, venetian blinds, doors or garage doors | stable; yes on all four main controllers, but the position direction still needs verifying. |
thermostat | Air conditioning, heating, thermostats and ventilation | stable; yes on all four main controllers, though the detailed modes still depend on the platform. |
fan | A standalone fan | stable; Apple no, Google, Alexa and Aqara yes. |
air_purifier | An air purifier; it can link an air filter and temperature and humidity | stable; Apple no, Google, Alexa and Aqara yes. |
humidifier_dehumidifier | Humidifier and dehumidifier control | stable; Google no, Alexa yes, Apple and Aqara unknown. |
SmartThings does not appear in the four-column picker matrix in the pinned source, and the feature manifest marks most of the items above as unknown for it. unknown means this pinned version has no sufficient evidence; it means neither yes nor no. Do not rewrite one successful case into a blanket support claim.
How lights, switches and plugs get their capabilities
The automatic path for light checks supported_color_modes. With only onoff it builds an On/Off Light; any mode that is neither unknown nor onoff can carry brightness; HS, RGB, XY, RGBW and RGBWW mean color capability; color_temp means color-temperature capability. In this version a color or color-temperature light assembles the features it needs on an Extended Color Light, which avoids the Color Temperature Light initialization problem. That does not mean color temperature is missing; it is an implementation choice about the endpoint base.
switch defaults to an On/Off Plug-in Unit with Groups and Scenes Management attached. A battery / battery_level attribute, or a batteryEntity named in Entity Mapping, can add a Power Source. Lights and switches can also link powerEntity, energyEntity, voltageEntity and currentEntity; voltage or current enables Electrical Power Measurement even when there is no separate power entity.
on_off_switch if you want a light tile, and only evaluate the experimental mounted_on_off_control for a genuine wall control; the buttons, scenes and scripts handled in Chapter 11 are momentary actions, and should not be dressed up as permanently powered devices just because a controller prefers a plug tile.If Alexa overwrites the previous brightness when you "turn on the light", the bridge feature flag alexaPreserveBrightnessOnTurnOn is an Alexa-only workaround: Stable, maturity stable, and the manifest marks it yes for Alexa and no for Apple. It does not add brightness the light never had, and it should not be switched on preemptively for other controllers. Turning a Google room off and keeping light state in sync got a source-code fix in this version, but your success criterion is still whether Home Assistant state reporting is correct.
Locks, covers and safety limits
lock maps to a Door Lock. In HA, locked / locking becomes Locked, unlocked / unlocking becomes Unlocked, open / opening becomes Unlatched, and every other state is conservatively reported as Not Fully Locked. If the supported features include OPEN, the endpoint adds Unbolting, and a platform that supports it, such as Apple Home, can show unlatch. That is an "unlatch" capability; it is not the same as every lock being able to physically open the door.
Entity Mapping also has disableLockPin, the lock-code service, slots and minimum and maximum lengths, but this guide gives no real lock codes. A controller may cache fixed attributes, so it does not necessarily pick up a changed length limit right away. A service that writes user codes into a physical lock is a high-risk integration: leave it unset unless you have backed up the lock and the integration settings and confirmed how to restore them.
Any cover that can be built carries Lift and PositionAwareLift; even when HA does not declare the open feature, the code fills in a valid descriptor and logs a warning. open_tilt or set_tilt_position can add Tilt, and only set_tilt_position adds PositionAwareTilt. Binary doors and garage doors report fully open or fully closed from their state and never invent an intermediate position.
| Setting | When to consider it | Risk and verification |
|---|---|---|
coverDoNotInvertPercentage | When the controller's percentage semantics are the reverse of what you expect | Stable/stable; change one thing at a time and compare fully open, half open and fully closed in HA and on the controller. |
coverUseHomeAssistantPercentage | When you want to take the HA percentage directly | Stable/stable; do not blind-test it together with the other direction fixes. |
coverSwapOpenClose | When the open and close commands are swapped | Stable/stable; test it first somewhere you can watch, with no risk of trapping anything. |
coverSliderDebounceMs | When the controller sends a stream of slider updates | Stable/stable; 0 means no global value is set, and an entity override wins. |
coverExposeAsDimmableLight | The specific workaround for Alexa no longer sending Window Covering position commands | It presents the cover as a dimmable light, which distorts the semantics; use it only on a bridge dedicated to that controller. |
Climate, fans, air purifiers and humidifiers
climate has to declare at least one of heat, cool, heat_cool, auto, fan_only or dry, or the endpoint fails as an unsupported device. The code adds Heating and Cooling separately from hvac_modes; only a heat_cool combination that genuinely supports two setpoints enables Matter AutoMode safely. A single-setpoint HA auto is mapped dynamically and does not declare AutoMode, which keeps some controllers from writing auto as heat or cool.
A present current_humidity or the TARGET_HUMIDITY feature can add humidity measurement; OnOff is added only when both TURN_ON and TURN_OFF are supported. disableClimateOnOff stops a room-wide "turn everything off" from switching the thermostat off with it. FAN_MODE makes the endpoint use Room Air Conditioner and Fan Control; if a platform such as Aqara does not recognize that device type, disableClimateFanControl falls back to Thermostat. climateExposeFan is the companion fan composition for bridge mode; Server Mode does not support the composed shape and falls back to a flat endpoint.
A fan with no speed and no usable speed preset maps to an On/Off Plug-in Unit, which keeps a controller from showing a fake speed slider. MultiSpeed and Step are added only when there is SET_SPEED or a non-Auto preset; Auto is added only when a preset really is named "auto"; DIRECTION and OSCILLATE add direction and oscillation. natural, nature, sleep, or the localized names listed in fanWindPresets, can add Wind. fanSliderDebounceMs handles a stream of slider updates; it does not add speed steps the hardware does not have.
Once fan is overridden to air_purifier, you can use filterLifeEntity, temperatureEntity and humidityEntity to link the air filter and the environment measurements. This mapping is in Stable at maturity stable; Google, Alexa and Aqara yes, Apple no. A humidifier builds one of four capability sets depending on whether available_modes contains Auto and whether current_humidity exists; controller support for humidifier_dehumidifier is noticeably thinner, and Google in particular is no.
humidifier_dehumidifier is not a Home Assistant service error. Separate endpoint health from platform UI support first.Verify a control mapping with the smallest possible change
Cross-check the capabilities in Home Assistant first
Go to Settings → Devices & services → Entities and look at the target entity's domain, device class, current state and available controls. Record it with a documentation placeholder such as
light.example_lamp, and copy nothing out of a live environment.Open Devices in Matter Hub
Search for the entity and look at its current mapping and any failure reason. Keep the automatic type for now; confirm that the capabilities shown match the matrix in this chapter before you decide whether to open the Entity Mapping editor.
Change one override or workaround only
Pick the exact Matter device type when you need one; change workarounds such as cover direction, climate fan or Alexa brightness one at a time. Do not rename, change the type and reorder the bridge at the same time, or you will not be able to locate the difference.
Check the bridge status after you save
Go back to that bridge's Details or Devices and confirm the endpoint has no failed entity. If the type is not supported, restore the last known-good setting rather than resetting or deleting the fabric outright.
Do a low-risk check on the controller
Compare the state first, then test on/off once; move a slider only to a position that is easy to recognize. Locks and moving devices need someone present and a local way to stop them.
Record the three conclusions separately
Note whether Stable 2.0.55 built it, the maturity of that feature, and whether the target controller shows it. Leave unknown as unknown; do not promote a single observation into a claim of production support.
Control-device pitfalls and fallback points
The light only switches, with no brightness or color
Check
supported_color_modesin HA first. If the source declares only onoff, Matter Hub will not manufacture brightness; if the capability is complete but the override wrongly pickedon_off_light, remove the override and go back to the automatic result.The cover percentage or direction is reversed
Test fully open, half open and fully closed in that order to tell an inverted value from swapped commands. Try one cover flag at a time, and turn off any workaround you do not need once you are done.
The climate endpoint fails to build
Check whether hvac_modes contains at least one of heat, cool, heat_cool, auto, fan_only or dry, and whether the min_temp / max_temp units make sense. Do not use a thermostat override to paper over a source entity that has no usable mode.
Apple Home does not show the fan or the air purifier
In the pinned matrix, Apple is no for both standalone fan and air_purifier. Keep the HA control, or build a bridge dedicated to another controller if you need one; do not delete and re-commission over and over.
Aqara misses a climate device that has a fan mode
Confirm first whether a plain Thermostat shows up. If it is a Room Air Conditioner type-compatibility problem, then consider
disableClimateFanControl. The cost is that the controller side no longer has Fan Control.Alexa rejects a cover position, or the light brightness misbehaves
Split the bridge before you use a controller-specific workaround, so other fabrics are not affected. A cover disguised as a dimmable light loses the correct device semantics, so name it clearly and leave a record of how to roll it back.
FAQ
Does an override change the Home Assistant entity?
For a switch, should I pick plug unit or on/off switch?
Why does a color-temperature light appear to use Extended Color Light?
Can a lock stop requiring controller verification?
disableLockPin can turn off Matter Hub's PIN requirement for a specific mapping, but whether that is allowed, how the platform presents it and the security policy of the physical lock are separate questions. This chapter gives no real code values, and we do not recommend weakening lock protection for convenience.What are partial and unknown in the controller matrix?
Stable 2.0.55 pinned sources
- The full HomeAssistantDomain enum
- Matter overrides, the domain default matrix and controller support
- Bridge feature flags
- The control-domain endpoint implementations
- Pinned Home Assistant Add-on mirror
Every link above is pinned to a specific commit and never to branch HEAD. Controller support is a point-in-time matrix inside the pinned version; later platform changes have to be verified separately.