Home Assistant Matter Hub is not a Matter controller

Keep that sentence in front of you for the rest of this part. Matter Hub reads a Home Assistant entity, builds a Matter endpoint that describes what that entity can do, and then hands the whole thing to whatever is actually acting as the controller — Apple Home, Google Home, Amazon Alexa, Aqara or SmartThings. The controller is the one that decides whether to draw a tile, a slider or a voice capability for that endpoint. Matter Hub's job ends at a correctly described endpoint. What happens after that is out of its hands.

Take an ordinary wall relay. In Stable 2.0.55, on_off_plugin_unit means a switchable load — the conservative default for a plug or an appliance. on_off_switch, despite the name, is implemented as a Matter On/Off Light (0x0100), so a controller draws it as a light, not a wall controller. mounted_on_off_control is the experimental Matter 1.4 wall-control type. on_off_light also means a light. All four can carry On/Off, and none of them guarantees the same picture on a controller's screen. The safe order is: keep the automatic mapping first, confirm in Home Assistant what the entity can actually do, and reach for a Matter override only for a specific, named controller gap.

Sensors add a third failure mode on top of that. A control device is either the wrong type or the right one; a sensor value can build correctly, fail to display, and still be wrong, all for different reasons that live in different places:

• Matter Hub skips it outright. An unrecognized device_class is logged as an entity warning and left out. Nothing is guessed.
• The endpoint is healthy, but the controller does not support that type. This is a platform limitation, not a Home Assistant or Matter Hub fault.
• The controller has a tile, and the number on it is wrong. The source unit, the source state, or a linked entity is the actual problem, not the mapping.

Working out which of those three you are in, before you touch anything, is most of what this part is trying to teach. Safety sensors deserve one more sentence up front: they only give you notifications and automation signals. They do not replace the smoke, gas, leak or freeze equipment that regulations require, and the energy and EVSE types bridge Home Assistant states and commands — they are not billing-grade metering and not a charging safety controller.

The seven control domains, and everything that can override them

The table below lists the default type candidates for the seven control domains covered in this part, alongside what actually decides the result. A candidate is not a guaranteed outcome — the real endpoint still comes from the capability bits and the attributes on the entity.

Every Matter override this part discusses, with its maturity and the controller snapshot in the pinned source, is below.

SmartThings does not appear in the four-column picker matrix in the pinned source at all, and the feature manifest marks most of the rows above as unknown for it. Unknown means the pinned version has no sufficient evidence — it is neither yes nor no. Do not rewrite one working case into a blanket support claim, and do not read an unknown as a quiet no either.

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 a Color Temperature Light initialization problem in the underlying implementation. That is a choice about the endpoint base, not a sign that color temperature went missing.

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; a voltage or current link enables Electrical Power Measurement even with no separate power entity.

flowchart TD
  A["switch domain entity"] --> B["Automatic type:
on_off_plugin_unit
(a switchable plug)"]
  A -->|"override to on_off_switch"| C["Matter On/Off Light 0x0100.
Controller draws a light tile"]
  A -->|"override to mounted_on_off_control"| D["Experimental Matter 1.4
wall-control type"]
  A -->|"override to dimmable_plugin_unit"| E["Plug-in load with
adjustable output"]

Two workarounds are worth naming here because they are the ones people reach for first. If Alexa overwrites the previous brightness when you “turn on the light,” the bridge feature flag alexaPreserveBrightnessOnTurnOn is an Alexa-only fix: Stable, maturity stable, yes for Amazon Alexa and no for Apple Home. It does not add brightness the light never had, and it should not be switched on preemptively for other controllers. Turning a Google Home room off while keeping light state in sync got a source-code fix in this version, but your success criterion is still whether Home Assistant's own state reporting is correct.

Where safety limits and platform support both live

lock maps to a Door Lock. In Home Assistant, 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 claim as every lock being able to physically open the door on command.

Entity Mapping also carries disableLockPin, the lock-code service, slots, and minimum and maximum lengths, but this guide gives no real lock codes anywhere. A controller may cache fixed attributes, so it will 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 exactly how to restore them.

Any cover that can be built carries Lift and PositionAwareLift; even when Home Assistant does not declare the open feature, the code fills in a valid descriptor and logs a warning rather than failing. 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.

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 independent setpoints enables Matter AutoMode safely. A single-setpoint Home Assistant auto is mapped dynamically instead, and does not declare AutoMode — which keeps some controllers from writing auto as heat or cool on your behalf.

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” command from switching the thermostat off along with the lights. 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 a plain 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.

flowchart TD
  A["climate entity"] --> B{"Does hvac_modes include
heat_cool with two real,
independent setpoints?"}
  B -->|"yes"| C["Matter AutoMode is
declared safely"]
  B -->|"no, only a single-
setpoint auto"| D["Mapped dynamically as
heat or cool.
AutoMode is not declared"]
  A --> E{"Are FAN_MODE features
present on the entity?"}
  E -->|"yes"| F["Room Air Conditioner +
Fan Control endpoint"]
  E -->|"no"| G["Plain Thermostat endpoint"]
  F -->|"a platform such as Aqara
does not recognize the type"| H["disableClimateFanControl
falls back to Thermostat"]

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 is literally 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, filterLifeEntity, temperatureEntity and humidityEntity link the air filter and the environment measurements onto the same endpoint. That mapping sits at maturity stable; Google Home, Amazon Alexa and Aqara yes, Apple Home 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 Home in particular is a no.

Where sensor, binary_sensor and weather come in

A Home Assistant sensor can be a temperature, a pressure, an illuminance, a flow rate, a pollutant, instantaneous power, accumulated energy or a battery percentage. A binary_sensor can be a door or window, motion, occupancy, smoke, a leak, or a plain boolean state. Matter Hub picks the endpoint from device_class first, and the controller then decides whether it shows that device type and cluster at all.

On a sensor, temperature builds a Temperature Sensor; humidity and moisture both map to Relative Humidity, and the second suits the 0–100% soil-moisture meaning; illuminance maps to Light Sensor; pressure and atmospheric_pressure map to Pressure; volume_flow_rate maps to Flow. PM2.5, PM10 and CO2 are not override names in the Entity Mapping picker, but the v2.0.55 automatic path still has endpoint implementations for them — the tables in this part list the complete override set the manifest defines, so do not confuse automatic support with the override options.

On a binary_sensor, door, garage_door, opening and window become Contact; motion / moving become Motion; occupancy / presence become Occupancy; smoke becomes Smoke Alarm; carbon_monoxide / gas become CO Alarm. cold and moisture use the detector contact variants. battery_charging, light, plug, power and running use OnOff Sensor; everything else — including battery, connectivity, heat, lock, problem, safety, sound, tamper, update and vibration — uses Contact.

flowchart TD
  A["A sensor or binary_sensor
entity"] --> B{"Does Matter Hub recognize
the device_class?"}
  B -->|"no, or none set"| C["Skipped outright, or falls
back to a plain OnOff Sensor"]
  B -->|"yes"| D["Endpoint builds"]
  D --> E{"Does the target controller
support that Matter type?"}
  E -->|"no"| F["Endpoint is healthy.
The controller shows no tile"]
  E -->|"yes"| G{"Does the shown value or
state look correct?"}
  G -->|"no"| H["Check the source unit,
state, or linked entity"]
  G -->|"yes"| I["Working as intended"]

Temperature, humidity, pressure, illuminance and flow

A Temperature Sensor can use humidityEntity, pressureEntity and batteryEntity to build a flat multi-measurement endpoint. Stable 2.0.55 puts the Temperature, Humidity and Pressure device types all into the descriptor, which gives controllers such as SmartThings a better chance of recognizing each one. The available combinations are temperature with humidity, temperature with pressure, temperature with humidity and pressure, and each of those with a battery added.

The bridge flags autoHumidityMapping, autoPressureMapping and autoBatteryMapping can find linked entities on the same Home Assistant device automatically; autoComposedDevices may build a composed device structure instead. These flags sit at maturity stable, but whether the automatic link is correct still depends on the Home Assistant device registry. Similar names do not mean the same piece of hardware, so cross-check which device an entity belongs to, and its unit, before you save anything.

Before data reaches Matter it still has to match the unit meaning of the Home Assistant device class. If a temperature looks an order of magnitude off, a humidity falls outside 0–100, or a pressure reading is implausible, fix the source integration or the template sensor first. Do not just relabel it with a different override.

Eight pollutants, seven detectors, and a thin layer of support underneath

Air quality is not one cluster. AQI, CO, CO2, TVOC, NO₂, O₃, formaldehyde, radon, PM1, PM2.5 and PM10 each measure something different, and the Matter override picker in Stable 2.0.55 treats them as eight separate types. Even when a controller does not display one of them, the underlying endpoint can still be perfectly healthy.

carbon_monoxide_sensor, which carries a CO concentration value, is not the same thing as smoke_co_alarm, which detects a dangerous condition. The first reports a number; the second reports an alarm event.

flowchart TD
  A["A CO-related source
in Home Assistant"] --> B{"Numeric concentration
reading, or binary
alarm state?"}
  B -->|"numeric reading"| C["carbon_monoxide_sensor:
reports a concentration"]
  B -->|"binary alarm"| D["smoke_co_alarm:
reports an alarm event"]
  C -->|"forced into an
alarm type"| E["Wrong alarm semantics"]
  D -->|"forced into a
reading type"| F["Loses the alerting display"]

Contact, motion, occupancy, smoke, leak and weather detection

A Smoke/CO Alarm can use the mapping's faultEntity so a problem or safety binary sensor on the same device drives the hardware fault alert. That fault entity is not necessarily absorbed into the alarm — it can keep its own endpoint. This is a device fault signal, not an active alarm; choose the wrong one and the controller treats a maintenance problem as a fire, or the reverse.

Door, window and motion sensors need no control commands, so verify them with read-only state changes. Do not create a real hazard to test a leak or smoke endpoint. Documented test entities belong in a Home Assistant development or test environment; this chapter gives no data from a live one.

Power, energy, battery, utility meters and EVSE

Power, energy, voltage and current device classes map to electrical_meter by default, because the pinned sources say both Google Home and SmartThings can display an Electrical Meter. electrical_sensor is the legacy SolarPower alias; solar_power is for generation. Choosing consumption or generation has to match the sign convention and the actual meaning of the source.

An Electrical Meter can fold powerEntity, energyEntity, voltageEntity and currentEntity into the same endpoint. A Utility Meter can also carry meter serial and point-of-delivery fields — this guide uses text placeholders only, and puts no real identifying data anywhere. Battery Storage becomes a fuller energy storage system once you add batteryPowerEntity and batteryEnergyEntity; cross-check the charge and discharge directions against the source definition before you trust the numbers.

EVSE can carry both state and control, but controller support is a clear limit. Do not treat a Matter tile as electrical protection, load management or a basis for billing. Any remote start or stop still has to follow the safety rules of the charging equipment and of the installation site.

One routine, for control devices and for sensors alike

Control mappings and sensor mappings are verified the same way, and the routine is deliberately slow. Every step below applies whether you are chasing a light that will not dim or a pressure reading that never appears.

1. Step 1

   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 or sensor.example_temperature, and copy nothing out of a live environment.

2. Step 2

   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 the capabilities shown match the tables in this part before you decide whether to open the Entity Mapping editor at all.

3. Step 3

   Cross-check any linked entities

   If you are adding a humidity, pressure, battery or power measurement, confirm each one belongs to the same physical device and that the units are compatible. Add one link at a time, so you can always tell which value caused a problem if one shows up.

4. Step 4

   Change one override or workaround only

   Pick the exact Matter device type when you need one; change workarounds such as cover direction, climate fan control, or the Alexa brightness flag, one at a time. Do not rename the entity, change the type and reorder the bridge in the same sitting, or you will not be able to locate the difference afterward.

5. Step 5

   Check the bridge status after you save

   Go back to that bridge's Details or Devices page and confirm the endpoint has no failed entity, and that the value Matter Hub shows matches Home Assistant. If the type turns out unsupported, restore the last known-good setting rather than resetting or deleting the fabric outright.

6. Step 6

   Do a low-risk check on the controller, and record what you learned

   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; safety detection should be observed read-only, never triggered for real. Then note three things separately: 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 one observation into a claim of general support.

flowchart TD
  A["A mapped entity does not
look right on the controller"] --> B{"Does Matter Hub show it
with no failed status?"}
  B -->|"failed, or missing
entirely"| C["Fix the Home Assistant
source first: device_class,
features, unit"]
  B -->|"healthy"| D{"Is that Matter type listed
as yes for this controller
in this part's tables?"}
  D -->|"no, or unknown"| E["Endpoint is fine. The
platform will not show it —
keep Home Assistant as
the primary view"]
  D -->|"yes"| F{"Does the value or control
on the controller match
Home Assistant?"}
  F -->|"no"| G["Check one linked entity
or one workaround flag
at a time"]
  F -->|"yes"| H["Confirmed working"]

The symptom you see, matched to what to do about it

FAQ

Where to go from here